API reference¶

Naampy exposes two public functions. Each accepts one first name or a one-dimensional collection and returns a new pandas DataFrame in input order.

Pattern estimate¶

naampy.estimate_first_name_pattern(names)[source]¶

Estimate the female source-label share associated with name patterns.

This is a population-level name-pattern estimate. It is not an observation of any person’s gender and must not be used for individual or consequential decisions. Inputs outside the frozen training domain are returned as explicit abstentions rather than transformed, truncated, or guessed.

Parameters:: names (str | None | Sequence[str | None] | Series) – One first name or a one-dimensional collection of first names.
Returns:: A new DataFrame with a calibrated nullable score, eligibility status, and immutable model provenance for every input row.
Return type:: DataFrame

Exact aggregate lookup¶

naampy.lookup_first_name_composition(names)[source]¶

Return exact electoral-roll source-label composition for first names.

This function performs only an exact table lookup after lossless normalization. It never falls back to a learned estimate.

Parameters:: names (str | None | Sequence[str | None] | Series) – One first name or a one-dimensional collection of first names.
Returns:: A new DataFrame with nullable counts, shares, lookup status, and immutable table provenance for every input row.
Return type:: DataFrame