Stable API reference

class geoestimate.Sample(data, *, cluster=None, weights=None, strata=None)[source]

Bind observations to a sampling design.

Notes

Sample supports design weights, strata, clusters, and post-stratification. Linearized standard errors come from svy; the bootstrap resamples primary units. Variance treats primary units as drawn with replacement, so it applies no finite population correction. It does not implement PPS or GRTS variance estimation.

Parameters:
  • data (DataFrame)

  • cluster (str | None)

  • weights (str | None)

  • strata (str | None)

classmethod from_file(path, *, cluster=None, weights=None, strata=None)[source]

Read a Parquet, CSV, or TSV file and construct a sample.

Parameters:
  • path (str | Path)

  • cluster (str | None)

  • weights (str | None)

  • strata (str | None)

Return type:

Sample

post_stratify(by, shares)[source]

Rescale weights so each cell of by has a known population share.

Use this when the sample’s mix differs from the population’s for a reason the design did not intend: uneven nonresponse, or a collection route that over-represents some kinds of road. Variance then counts only variation within cells. The shares fix the mix, not the population size, so a weighted total keeps the sampling error of the weight total.

Parameters:
  • by (str) – Column whose values define the cells.

  • shares (Mapping[object, float]) – Population share of each cell. Shares must be positive, sum to one, and name exactly the cells present in the sample.

Returns:

A new sample whose estimates are calibrated to the shares.

Raises:

ValueError – If the column or the shares are invalid, or the sample is already post-stratified.

Return type:

Sample

property cluster: str | None

Return the declared cluster-column name.

property weights: str | None

Return the declared weight-column name.

property strata: str | None

Return the declared stratum-column name.

property n_observations: int

Return the number of sampled observations.

property n_clusters: int | None

Return the declared cluster count, or None for unclustered samples.

mean(variable, *, inference='design', confidence_level=0.95, bootstrap_reps=2000, seed=None)[source]

Estimate the population mean of a numeric variable.

Parameters:
  • variable (str)

  • inference (Literal['design', 'iid', 'cluster', 'bootstrap'])

  • confidence_level (float)

  • bootstrap_reps (int)

  • seed (int | None)

Return type:

Estimate

share_at_least(variable, threshold, *, inference='design', confidence_level=0.95, bootstrap_reps=2000, seed=None)[source]

Estimate the population share of units at or above a threshold.

Parameters:
  • variable (str)

  • threshold (float)

  • inference (Literal['design', 'iid', 'cluster', 'bootstrap'])

  • confidence_level (float)

  • bootstrap_reps (int)

  • seed (int | None)

Return type:

Estimate

total(variable, *, population_size=None, inference='design', confidence_level=0.95, bootstrap_reps=2000, seed=None)[source]

Estimate a population total.

With declared weights this is the Horvitz-Thompson total, the weighted sum. Without weights it is population_size times the sample mean.

Parameters:
  • variable (str) – Numeric column to total.

  • population_size (int | None) – Number of units in the population. Required for unweighted samples and not allowed for weighted ones.

  • inference (Literal['design', 'iid', 'cluster', 'bootstrap']) – Uncertainty method.

  • confidence_level (float) – Coverage of the confidence interval.

  • bootstrap_reps (int) – Number of bootstrap draws.

  • seed (int | None) – Seed for bootstrap draws.

Returns:

The estimated total.

Raises:
  • TypeError – If population_size is not an integer.

  • ValueError – If population_size is missing, redundant, or too small.

Return type:

Estimate

ratio(numerator, denominator, *, inference='design', confidence_level=0.95, bootstrap_reps=2000, seed=None)[source]

Estimate a ratio of population totals.

Parameters:
  • numerator (str)

  • denominator (str)

  • inference (Literal['design', 'iid', 'cluster', 'bootstrap'])

  • confidence_level (float)

  • bootstrap_reps (int)

  • seed (int | None)

Return type:

Estimate

mean_of_ratios(numerator, denominator, *, inference='design', confidence_level=0.95, bootstrap_reps=2000, seed=None)[source]

Estimate the population mean of row-level numerator/denominator ratios.

Parameters:
  • numerator (str)

  • denominator (str)

  • inference (Literal['design', 'iid', 'cluster', 'bootstrap'])

  • confidence_level (float)

  • bootstrap_reps (int)

  • seed (int | None)

Return type:

Estimate

class geoestimate.Estimate(estimand, variables, estimate, standard_error, confidence_interval, confidence_level, inference_method, n_observations, n_clusters, population_size, diagnostics)[source]

A scalar estimate with uncertainty and design diagnostics.

Parameters:
summary()[source]

Return a compact, human-readable summary.

Return type:

str

to_frame()[source]

Return the scalar result as a one-row tidy table.

Return type:

DataFrame

class geoestimate.Diagnostics(iid_standard_error, cluster_standard_error, design_effect, effective_sample_size, cluster_sizes, effective_cluster_count)[source]

Analytic diagnostics for one estimate.

Parameters:
  • iid_standard_error (float)

  • cluster_standard_error (float | None)

  • design_effect (float | None)

  • effective_sample_size (float)

  • cluster_sizes (tuple[int, ...] | None)

  • effective_cluster_count (float | None)

iid_standard_error

Standard error that treats rows as independent.

Type:

float

cluster_standard_error

Cluster-sandwich standard error, when declared.

Type:

float | None

design_effect

Cluster variance divided by iid variance, when defined.

Type:

float | None

effective_sample_size

Observation count divided by the design effect.

Type:

float

cluster_sizes

Number of observations in each declared cluster.

Type:

tuple[int, …] | None

effective_cluster_count

Kish effective count of declared clusters.

Type:

float | None