Sample Analytics

Help Shape the Future of Samplics

We are driven by community feedback and would love to hear from you! Please take a few minutes to complete our user survey.

➡️ Share Your Feedback

In large-scale surveys, often complex random mechanisms are used to select samples. Estimates derived from such samples must reflect the random mechanism. Samplics is a python package that implements a set of sampling techniques for complex survey designs. These survey sampling techniques are organized into the following four sub-packages.

Sampling provides a set of random selection techniques used to draw a sample from a population. It also provides procedures for calculating sample sizes. The sampling subpackage contains:

• Sample size calculation and allocation: Wald and Fleiss methods for proportions.
• Equal probability of selection: simple random sampling (SRS) and systematic selection (SYS)
• Probability proportional to size (PPS): Systematic, Brewer's method, Hanurav-Vijayan method, Murphy's method, and Rao-Sampford's method.

Weighting provides the procedures for adjusting sample weights. More specifically, the weighting subpackage allows the following:

• Weight adjustment due to nonresponse
• Weight poststratification, calibration and normalization
• Weight replication i.e. Bootstrap, BRR, and Jackknife

Estimation provides methods for estimating the parameters of interest with uncertainty measures that are consistent with the sampling design. The estimation subpackage implements the following types of estimation methods:

• Taylor-based, also called linearization methods
• Replication-based estimation i.e. Boostrap, BRR, and Jackknife
• Regression-based e.g. generalized regression (GREG)

Small Area Estimation (SAE). When the sample size is not large enough to produce reliable / stable domain level estimates, SAE techniques can be used to model the output variable of interest to produce domain level estimates. This subpackage provides Area-level and Unit-level SAE methods.

For more details, visit https://samplics-org.github.io/samplics/

Usage

Let's assume that we have a population and we would like to select a sample from it. The goal is to calculate the sample size for an expected proportion of 0.80 with a precision (half confidence interval) of 0.10.

```python from samplics.utils.types import SizeMethod, PopParam from samplics.sampling import SampleSize

samplesize = SampleSize(param=PopParam.prop, method=SizeMethod.wald) samplesize.calculate(target=0.80, half_ci=0.10) ```

Furthermore, the population is located in four natural regions i.e. North, South, East, and West. We could be interested in calculating sample sizes based on region specific requirements e.g. expected proportions, desired precisions and associated design effects.

```python from samplics.utils.types import SizeMethod, PopParam from samplics.sampling import SampleSize

sample_size = SampleSize(param=PopParam.prop, method=SizeMethod.wald, strat=True)

expectedproportions = {"North": 0.95, "South": 0.70, "East": 0.30, "West": 0.50} halfci = {"North": 0.30, "South": 0.10, "East": 0.15, "West": 0.10} deff = {"North": 1, "South": 1.5, "East": 2.5, "West": 2.0}

samplesize = SampleSize(param=PopParam.prop, method=SizeMethod.fleiss, strat=True) samplesize.calculate(target=expectedproportions, halfci=half_ci, deff=deff) ```

To select a sample of primary sampling units using PPS method, we can use code similar to the snippets below. Note that we first use the datasets module to import the example dataset.

```python

First we import the example dataset

from samplics.datasets import loadpsuframe psuframedict = loadpsuframe() psuframe = psuframe_dict["data"]

Code for the sample selection

from samplics.sampling import SampleSelection from samplics.utils import SelectMethod

psusamplesize = {"East":3, "West": 2, "North": 2, "South": 3} ppsdesign = SampleSelection( method=SelectMethod.ppssys, strat=True, wr=False )

psuframe["psuprob"] = ppsdesign.inclusionprobs( psuframe["cluster"], psusamplesize, psuframe["region"], psuframe["numberhouseholds_census"] ) ```

The initial weighting step is to obtain the design sample weights. In this example, we show a simple example of two-stage sampling design.

```python import pandas as pd

from samplics.datasets import loadpsusample, loadssusample from samplics.weighting import SampleWeight

Load PSU sample data

psusampledict = loadpsusample() psusample = psusample_dict["data"]

Load PSU sample data

ssusampledict = loadssusample() ssusample = ssusample_dict["data"]

fullsample = pd.merge( psusample[["cluster", "region", "psuprob"]], ssusample[["cluster", "household", "ssu_prob"]], on="cluster" )

fullsample["inclusionprob"] = fullsample["psuprob"] * fullsample["ssuprob"] fullsample["designweight"] = 1 / fullsample["inclusionprob"] ```

To adjust the design sample weight for nonresponse, we can use code similar to:

```python import numpy as np

from samplics.weighting import SampleWeight

Simulate response

np.random.seed(7) fullsample["responsestatus"] = np.random.choice( ["ineligible", "respondent", "non-respondent", "unknown"], size=full_sample.shape[0], p=(0.10, 0.70, 0.15, 0.05), )

Map custom response statuses to teh generic samplics statuses

status_mapping = { "in": "ineligible", "rr": "respondent", "nr": "non-respondent", "uk":"unknown" }

adjust sample weights

fullsample["nrweight"] = SampleWeight().adjust( sampweight=fullsample["designweight"], adjclass=fullsample["region"], respstatus=fullsample["responsestatus"], respdict=statusmapping ) ```

To estimate population parameters using Taylor-based and replication-based methods, we can use code similar to:

```python

Taylor-based

from samplics.utils.types import PopParam, RepMethod from samplics.datasets import load_nhanes2

nhanes2dict = loadnhanes2() nhanes2 = nhanes2_dict["data"]

from samplics.estimation import TaylorEstimator

zincmeanstr = TaylorEstimator(PopParam.mean) zincmeanstr.estimate( y=nhanes2["zinc"], sampweight=nhanes2["finalwgt"], stratum=nhanes2["stratid"], psu=nhanes2["psuid"], removenan=True, )

Replicate-based

from samplics.datasets import load_nhanes2brr

nhanes2brrdict = loadnhanes2brr() nhanes2brr = nhanes2brr_dict["data"]

from samplics.estimation import ReplicateEstimator

ratiowgthgt = ReplicateEstimator(RepMethod.brr, PopParam.ratio).estimate( y=nhanes2brr["weight"], sampweight=nhanes2brr["finalwgt"], x=nhanes2brr["height"], repweights=nhanes2brr.loc[:, "brr1":"brr32"], remove_nan=True, )

```

To predict small area parameters, we can use code similar to:

```python import numpy as np import pandas as pd

Area-level basic method

from samplics.utils.types import FitMethod from samplics.datasets import loadexpendituremilk

milkexpdict = loadexpendituremilk() milkexp = milkexp_dict["data"]

from samplics.sae import EblupAreaModel

fhmodelreml = EblupAreaModel(method=FitMethod.reml) fhmodelreml.fit( yhat=milkexp["directest"], X=pd.getdummies(milkexp["majorarea"], dropfirst=True), area=milkexp["smallarea"], errorstd=milkexp["stderror"], intercept=True, tol=1e-8, ) fhmodelreml.predict( X=pd.getdummies(milkexp["majorarea"], dropfirst=True), area=milkexp["small_area"], intercept=True, )

Unit-level basic method

from samplics.datasets import loadcountycrop, loadcountycrop_means

Load County Crop sample data

countycropdict = loadcountycrop() countycrop = countycropdict["data"]

Load County Crop Area Means sample data

countycropmeansdict = loadcountycropmeans() countycropmeans = countycropmeansdict["data"]

from samplics.sae import EblupUnitModel

eblupbhfreml = EblupUnitModel() eblupbhfreml.fit( countycrop["cornarea"], countycrop[["cornpixel", "soybeanspixel"]], countycrop["countyid"], ) eblupbhfreml.predict( Xmean=countycropmeans[["avecornpixel", "avecorn_pixel"]], area=np.linspace(1, 12, 12), )

```

Installation

pip install samplics

Python 3.10 or newer is required and the main dependencies are numpy, polars, and statsmodel.

Contribution

If you would like to contribute to the project, please read contributing to samplics

License

MIT

Contact

created by Mamadou S. Diallo - feel free to contact me!