API Reference

Composition results

instate.lookup_state_composition(data, surname_column=None)[source]

Look up a surname’s state composition in the included electoral rolls.

Each share is the fraction of the surname’s included, processed roll occurrences recorded in a state. Unknown surnames abstain; they do not receive a default distribution.

Parameters:

  • data (DataFrame | Series | list[str | None] | str) – DataFrame of inputs, or a surname string, list, or Series.

  • surname_column (str | None) – Column holding surnames for DataFrame input.

Returns:

A copy of the input with 35 state_share_* columns, surname_record_count, and the contract metadata columns.

Return type:

DataFrame

instate.estimate_state_composition(data, surname_column=None)[source]

Estimate a surname’s state composition with the calibrated model.

The character-BiLSTM targets the same quantity the lookup reports and generalizes to surnames outside the lookup table. Probabilities are temperature-scaled on surnames excluded from training and epoch selection.

Parameters:

  • data (DataFrame | Series | list[str | None] | str) – DataFrame of inputs, or a surname string, list, or Series.

  • surname_column (str | None) – Column holding surnames for DataFrame input.

Returns:

A copy of the input with 35 state_share_* columns and the contract metadata columns.

Return type:

DataFrame

instate.estimate_language_composition(data, surname_column=None, *, basis='auto')[source]

Estimate a surname’s language composition from state evidence.

The language shares are defined, not observed: the surname’s state composition mixed with each state’s Census 2011 mother-tongue shares. The mixing assumes language and surname are independent within a state, which understates community-specific associations.

Parameters:

  • data (DataFrame | Series | list[str | None] | str) – DataFrame of inputs, or a surname string, list, or Series.

  • surname_column (str | None) – Column holding surnames for DataFrame input.

  • basis (Literal['auto', 'lookup', 'model']) – State evidence to mix. lookup uses the electoral table and abstains on unknown surnames; model uses the calibrated LSTM; auto prefers the lookup and falls back to the model.

Returns:

A copy of the input with language_share_* columns, a language_basis column, and the contract metadata columns.

Raises:

ValueError – If basis is not one of the documented options.

Return type:

DataFrame

Reference lookups

instate.lookup_state_official_languages(data, state_column=None)[source]

Look up each state’s official languages.

Parameters:

  • data (DataFrame | list[str] | str) – DataFrame of inputs, or a state name string or list.

  • state_column (str | None) – Column holding state names for DataFrame input.

Returns:

A copy of the input with an official_languages column; states outside the table receive a missing value.

Raises:

  • TypeError – If data is not a supported input type.

  • ValueError – If state_column is missing or absent for DataFrame input.

Return type:

DataFrame

instate.list_supported_states()[source]

List the states covered by the composition functions.

Returns:

State names in vocabulary order.

Return type:

list[str]

Coverage adjustment

instate.coverage.adjust_surname_counts(counts, totals, *, strata, source_revision, target_revision, assumption)[source]

Estimate surname counts by reweighting within explicitly supplied strata.

Parameters:

  • counts (pd.DataFrame) – Unique stratum/surname rows with positive integer observed_count. Include all observed surnames before minimum-cell suppression.

  • totals (pd.DataFrame) – Unique stratum rows with nonnegative integer target_count, using matching source geography, year, population and surname definition.

  • strata (Sequence[str]) – Shared grouping columns, such as state, year, district and sex.

  • source_revision (str) – Immutable revision of the observed surname counts.

  • target_revision (str) – Immutable revision of the population control totals.

  • assumption (Literal['mcar', 'conditional_mar']) – Explicit mcar assumption within each supplied population, typically state and roll edition, or conditional_mar for adjustment within finer covariate strata. Neither assumption is tested here.

Returns:

Separate observed and estimated counts, weights and coverage diagnostics. The inputs are unchanged. Zero-target empty strata have null weights. No weights are applied to inference, training or packaged lookup tables.

Raises:

ValueError – Schemas, counts, support, revisions or assumptions are invalid.

Return type:

CoverageAdjustment

Notes

Weighting does not correct misclassified surnames or identify unobserved surname categories. Known absence of a family surname is not a missing surname to impute. Entirely missing positive-target strata cannot be recovered by weighting. This function cannot verify missingness assumptions.

class instate.coverage.CoverageAdjustment(estimates, diagnostics, source_revision, target_revision, assumption)[source]

Observed counts, estimated counts and the assumptions behind their difference.

Parameters:

  • estimates (pd.DataFrame)

  • diagnostics (pd.DataFrame)

  • source_revision (str)

  • target_revision (str)

  • assumption (str)