Skip to content

epymorph.geography.us_geography

Encodes the geographic system made up of US Census delineations. This system comprises a set of perfectly-nested granularities, and a structured ID system for labeling all delineations (sometimes loosely called FIPS codes or GEOIDs).

CensusGranularityName module-attribute 

CensusGranularityName = Literal[
    "state", "county", "tract", "block group", "block"
]

Type alias: the name of a supported Census granularity.

CENSUS_HIERARCHY module-attribute 

CENSUS_HIERARCHY = (
    "state",
    "county",
    "tract",
    "block group",
    "block",
)

The granularities in hierarchy order (largest to smallest).

STATE module-attribute 

STATE = State()

A singleton State instance.

COUNTY module-attribute 

COUNTY = County()

A singleton County instance.

TRACT module-attribute 

TRACT = Tract()

A singleton Tract instance.

BLOCK_GROUP module-attribute 

BLOCK_GROUP = BlockGroup()

A singleton BlockGroup instance.

BLOCK module-attribute 

BLOCK = Block()

A singleton Block instance.

CENSUS_GRANULARITY module-attribute 

CENSUS_GRANULARITY = (
    STATE,
    COUNTY,
    TRACT,
    BLOCK_GROUP,
    BLOCK,
)

CensusGranularity singletons in hierarchy order.

CensusGranularity 

CensusGranularity(
    name: CensusGranularityName,
    length: int,
    match_pattern: str,
    extract_pattern: str,
    decompose_pattern: str,
)

Bases: ABC

Each CensusGranularity instance defines a set of utility functions for working with GEOIDs of that granularity, as well as inspecting and manipulating the granularity hierarchy itself.

In typical usage, you will not construct this class directly, but use the CensusGranularity.of(granularity) static method to obtain an instance, or import one of the singleton instances: STATE, COUNTY, TRACT, BLOCK_GROUP, or BLOCK.

Parameters:

  • name (CensusGranularityName) –

    The granularity.

  • length (int) –

    The number of digits in the GEOIDs for this granularity.

  • match_pattern (str) –

    A regex pattern matching GEOIDs for this granularity.

  • extract_pattern (str) –

    A regex pattern with match groups for extracting this granularity segment from a GEOID of an equal or finer granularity.

  • decompose_pattern (str) –

    A regex pattern with match groups for decomposing a GEOID of this granularity into segments.

name property 

name: CensusGranularityName

The name of the granularity this class models.

length property 

length: int

The number of digits in a GEOID of this granularity.

is_nested 

is_nested(outer: CensusGranularityName) -> bool

Test whether this granularity is nested inside (or equal to) the given granularity.

Parameters:

Returns:

  • bool –

    True if this granularity is inside or the same as other.

matches 

matches(geoid: str) -> bool

Test whether the given GEOID matches this granularity exactly. For example: "04" matches state granularity but not county granularity.

Parameters:

  • geoid (str) –

    The GEOID to test.

Returns:

  • bool –

    True if the GEOID given matches this granularity.

extract 

extract(geoid: str) -> str

Extracts this level of granularity's GEOID segment, if the given GEOID is of this granularity or smaller.

Parameters:

  • geoid (str) –

    The GEOID to operate on.

Returns:

  • str –

    The segment of the GEOID that matches this granularity.

Raises:

truncate 

truncate(geoid: str) -> str

Truncates the given GEOID to this level of granularity. If the given GEOID is for a granularity larger than this level, the GEOID will be returned unchanged.

Parameters:

  • geoid (str) –

    The GEOID to operate on.

Returns:

  • str –

    The truncated GEOID.

truncate_unique 

truncate_unique(geoids: Iterable[str]) -> Iterable[str]

Truncates an Iterable of GEOIDs to this level of granularity, returning only unique entries without changing the ordering of entries.

Parameters:

  • geoids (Iterable[str]) –

    The list of GEOIDs to operate on.

Returns:

  • Iterable[str] –

    The unique values contained in geoids after truncation to this level of granularity.

decompose abstractmethod 

decompose(geoid: str) -> tuple[str, ...]

Decompose a GEOID into a tuple containing all of its granularity component IDs. The GEOID must match this granularity exactly.

Parameters:

  • geoid (str) –

    The GEOID to operate on.

Returns:

  • tuple[str, ...] –

    A tuple as long as the number of granularity segments used for this level of granularity.

Raises:

  • GeographyError –

    If the GEOID does not match this granularity exactly.

grouped 

grouped(
    sorted_geoids: NDArray[str_],
) -> dict[str, NDArray[str_]]

Group a list of GEOIDs by this level of granularity. WARNING: Requires that the GEOID array has been sorted!

Parameters:

  • sorted_geoids (NDArray[str_]) –

    The GEOIDs to group, as a sorted array.

Returns:

  • dict[str, NDArray[str_]] –

    A dictionary where the keys represent the unique groups present and the values are all GEOIDs contained in each group.

of staticmethod 

of(name: CensusGranularityName) -> CensusGranularity

Get a CensusGranularity instance by name.

Parameters:

Returns:

  • CensusGranularity –

    The CensusGranularity instance, whose type matches the named granularity.

State 

State()

Bases: CensusGranularity

State-level utility functions.

decompose 

decompose(geoid: str) -> tuple[str]

Decompose a GEOID into a tuple containing the state ID. The GEOID must be a state GEOID.

Parameters:

  • geoid (str) –

    The GEOID to operate on.

Returns:

Raises:

  • GeographyError –

    If the GEOID does not match this granularity exactly.

County 

County()

Bases: CensusGranularity

County-level utility functions.

decompose 

decompose(geoid: str) -> tuple[str, str]

Decompose a GEOID into a tuple containing the state and county ID. The GEOID must be a county GEOID.

Parameters:

  • geoid (str) –

    The GEOID to operate on.

Returns:

Raises:

  • GeographyError –

    If the GEOID does not match this granularity exactly.

Tract 

Tract()

Bases: CensusGranularity

Census-tract-level utility functions.

decompose 

decompose(geoid: str) -> tuple[str, str, str]

Decompose a GEOID into a tuple containing the state, county, and tract ID. The GEOID must be a tract GEOID.

Parameters:

  • geoid (str) –

    The GEOID to operate on.

Returns:

Raises:

  • GeographyError –

    If the GEOID does not match this granularity exactly.

BlockGroup 

BlockGroup()

Bases: CensusGranularity

Block-group-level utility functions.

decompose 

decompose(geoid: str) -> tuple[str, str, str, str]

Decompose a GEOID into a tuple containing the state, county, tract, and block group ID. The GEOID must be a block group GEOID.

Parameters:

  • geoid (str) –

    The GEOID to operate on.

Returns:

Raises:

  • GeographyError –

    If the GEOID does not match this granularity exactly.

Block 

Block()

Bases: CensusGranularity

Block-level utility functions.

decompose 

decompose(geoid: str) -> tuple[str, str, str, str, str]

Decompose a GEOID into a tuple containing the state, county, tract, block group, and block ID. The GEOID must be a block GEOID. Note that block IDs are kind of strange -- the block group ID is a single digit, but the block ID also includes this digit. Thus, the returned tuple will include this digit in both of the last two parts.

Parameters:

  • geoid (str) –

    The GEOID to operate on.

Returns:

Raises:

  • GeographyError –

    If the GEOID does not match this granularity exactly.