API reference

The public API is intentionally small while the library is at version 0.

designweights.estimators

Point estimators for finite-population parameters.

Every estimator here is a function of the data and a weight vector. That is the design thesis of the library: anything that adjusts for the sampling design, for nonresponse, or for calibration does so by transforming the weights, and the estimator itself never changes. The weight vector is whatever the analysis calls for: base design weights 1 / pi_k, or weights after nonresponse adjustment and calibration.

References

Horvitz, D. G. and Thompson, D. J. (1952). A generalization of sampling without replacement from a finite universe. Journal of the American Statistical Association, 47(260), 663-685.

Hajek, J. (1971). Comment on "An essay on the logical foundations of survey sampling, part one". In Foundations of Statistical Inference, p. 236. Holt, Rinehart and Winston, Toronto.

total(y, weights)

Estimate the population total of y.

Computes the expansion estimator sum_k w_k * y_k over the sample. With base design weights w_k = 1 / pi_k this is the Horvitz-Thompson estimator, which is design-unbiased for the finite-population total. With adjusted weights it is the corresponding weighted total.

Parameters:

Name	Type	Description	Default
y	array-like of shape (n,)	Study variable, one value per sampled unit.	required
weights	array-like of shape (n,)	Positive survey weights, one per sampled unit.	required

Returns:

Type	Description
float	The estimated population total.

Examples:

>>> total([2.0, 3.0], weights=[10.0, 10.0])
50.0

Source code in src/designweights/estimators.py

def total(y: ArrayLike, weights: ArrayLike) -> float:
    """Estimate the population total of ``y``.

    Computes the expansion estimator ``sum_k w_k * y_k`` over the sample.
    With base design weights ``w_k = 1 / pi_k`` this is the
    Horvitz-Thompson estimator, which is design-unbiased for the
    finite-population total. With adjusted weights it is the corresponding
    weighted total.

    Parameters
    ----------
    y : array-like of shape (n,)
        Study variable, one value per sampled unit.
    weights : array-like of shape (n,)
        Positive survey weights, one per sampled unit.

    Returns
    -------
    float
        The estimated population total.

    Examples
    --------
    >>> total([2.0, 3.0], weights=[10.0, 10.0])
    50.0
    """
    y_arr = _validate("y", y)
    w = _validate_weights(weights, y_arr.size)
    return float(w @ y_arr)

mean(y, weights)

Estimate the population mean of y.

Computes the Hajek estimator sum_k w_k * y_k / sum_k w_k: the weighted total of y divided by the estimated population size. It is the standard design-based estimator of a mean when the population size is not known exactly, and it is invariant to rescaling all weights by a constant.

Parameters:

Name	Type	Description	Default
y	array-like of shape (n,)	Study variable, one value per sampled unit.	required
weights	array-like of shape (n,)	Positive survey weights, one per sampled unit.	required

Returns:

Type	Description
float	The estimated population mean.

Examples:

>>> mean([2.0, 4.0], weights=[30.0, 10.0])
2.5

Source code in src/designweights/estimators.py

def mean(y: ArrayLike, weights: ArrayLike) -> float:
    """Estimate the population mean of ``y``.

    Computes the Hajek estimator ``sum_k w_k * y_k / sum_k w_k``: the
    weighted total of ``y`` divided by the estimated population size. It is
    the standard design-based estimator of a mean when the population size
    is not known exactly, and it is invariant to rescaling all weights by a
    constant.

    Parameters
    ----------
    y : array-like of shape (n,)
        Study variable, one value per sampled unit.
    weights : array-like of shape (n,)
        Positive survey weights, one per sampled unit.

    Returns
    -------
    float
        The estimated population mean.

    Examples
    --------
    >>> mean([2.0, 4.0], weights=[30.0, 10.0])
    2.5
    """
    y_arr = _validate("y", y)
    w = _validate_weights(weights, y_arr.size)
    return float((w @ y_arr) / w.sum())

ratio(y, x, weights)

Estimate the ratio of the population totals of y and x.

Computes sum_k w_k * y_k / sum_k w_k * x_k. Means over domains, rates, and per-unit quantities are all ratios of totals, which is why this estimator is a workhorse of official statistics.

Parameters:

Name	Type	Description	Default
y	array-like of shape (n,)	Numerator study variable.	required
x	array-like of shape (n,)	Denominator study variable. Its weighted total must be nonzero.	required
weights	array-like of shape (n,)	Positive survey weights, one per sampled unit.	required

Returns:

Type	Description
float	The estimated ratio of population totals.

Examples:

>>> ratio([2.0, 3.0], x=[1.0, 1.0], weights=[10.0, 10.0])
2.5

Source code in src/designweights/estimators.py

def ratio(y: ArrayLike, x: ArrayLike, weights: ArrayLike) -> float:
    """Estimate the ratio of the population totals of ``y`` and ``x``.

    Computes ``sum_k w_k * y_k / sum_k w_k * x_k``. Means over domains,
    rates, and per-unit quantities are all ratios of totals, which is why
    this estimator is a workhorse of official statistics.

    Parameters
    ----------
    y : array-like of shape (n,)
        Numerator study variable.
    x : array-like of shape (n,)
        Denominator study variable. Its weighted total must be nonzero.
    weights : array-like of shape (n,)
        Positive survey weights, one per sampled unit.

    Returns
    -------
    float
        The estimated ratio of population totals.

    Examples
    --------
    >>> ratio([2.0, 3.0], x=[1.0, 1.0], weights=[10.0, 10.0])
    2.5
    """
    y_arr = _validate("y", y)
    x_arr = _validate("x", x, y_arr.size)
    w = _validate_weights(weights, y_arr.size)
    denominator = w @ x_arr
    if denominator == 0:
        raise ValueError("the weighted total of x is zero; the ratio is undefined.")
    return float((w @ y_arr) / denominator)