Stable API reference¶
- class geoestimate.Sample(data, *, cluster=None, weights=None, strata=None)[source]¶
Bind observations to a sampling design.
Notes
Samplesupports design weights, strata, clusters, and post-stratification. Linearized standard errors come fromsvy; 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.- classmethod from_file(path, *, cluster=None, weights=None, strata=None)[source]¶
Read a Parquet, CSV, or TSV file and construct a sample.
- post_stratify(by, shares)[source]¶
Rescale weights so each cell of
byhas 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:
- 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:
- property n_clusters: int | None¶
Return the declared cluster count, or
Nonefor unclustered samples.
- mean(variable, *, inference='design', confidence_level=0.95, bootstrap_reps=2000, seed=None)[source]¶
Estimate the population mean of a numeric variable.
Estimate the population share of units at or above a threshold.
- 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_sizetimes 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:
- ratio(numerator, denominator, *, inference='design', confidence_level=0.95, bootstrap_reps=2000, seed=None)[source]¶
Estimate a ratio of population totals.
- 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.