polaris.analyze.geo_mapping.USCensusMapping

class polaris.analyze.geo_mapping.USCensusMapping(location_mode: LocationMode, popsyn_to_survey: DataFrame, location_to_popsyn: DataFrame | None = None, block_to_puma: DataFrame | None = None)

Bases: GeoMappingStrategy

US Census-based geographic mapping (tract → PUMA).

Maps households to US 2010 Census tracts and aggregates to PUMAs (Public Use Microdata Areas) using the standard Census Bureau crosswalk.

__init__(location_mode: LocationMode, popsyn_to_survey: DataFrame, location_to_popsyn: DataFrame | None = None, block_to_puma: DataFrame | None = None)

Initialize with resolved mode and pre-loaded crosswalks.

For typical use, prefer the from_location_mode class method.

Args:

location_mode: How household.location is encoded (POI, TRACT, or BLOCK). popsyn_to_survey: Pre-loaded crosswalk with popsyn_region_col and survey_region_col. location_to_popsyn: (POI mode only) DataFrame mapping location → popsyn_region. block_to_puma: (BLOCK mode only) DataFrame mapping block_id → puma_id.

Methods

__init__(location_mode, popsyn_to_survey[, ...])	Initialize with resolved mode and pre-loaded crosswalks.
from_location_mode(location_mode[, ...])	Create USCensusMapping by resolving location mode and loading data upfront.
get_popsyn_region(households)	Derive census tract from location field based on location_mode.
get_survey_region(households_with_popsyn)	Map census tracts to PUMAs using standard Census Bureau crosswalk.

Attributes

popsyn_region_col
survey_region_col

popsyn_region_col: str = 'popsyn_region'

survey_region_col: str = 'puma_id'

__init__(location_mode: LocationMode, popsyn_to_survey: DataFrame, location_to_popsyn: DataFrame | None = None, block_to_puma: DataFrame | None = None)

Initialize with resolved mode and pre-loaded crosswalks.

For typical use, prefer the from_location_mode class method.

Args:

location_mode: How household.location is encoded (POI, TRACT, or BLOCK). popsyn_to_survey: Pre-loaded crosswalk with popsyn_region_col and survey_region_col. location_to_popsyn: (POI mode only) DataFrame mapping location → popsyn_region. block_to_puma: (BLOCK mode only) DataFrame mapping block_id → puma_id.

classmethod from_location_mode(location_mode: LocationMode | str | None, supply_db: PathLike | None = None, block_to_puma: DataFrame | None = None, puma_id_contains_state_id: bool = False, puma_to_tract_csv: PathLike | None = None) → USCensusMapping

Create USCensusMapping by resolving location mode and loading data upfront.

Loads the supply_db location→popsyn_region mapping (if supply_db is given) and the standard 2010 Census PUMA-to-tract crosswalk.

Args:

location_mode: How household.location is encoded. If None, defaults to POI when

supply_db is available, otherwise TRACT.

supply_db: Path to supply database (required for POI mode). block_to_puma: DataFrame mapping block_id → puma_id (required for BLOCK mode). puma_id_contains_state_id: Whether PUMA IDs include state prefix. puma_to_tract_csv: Optional path to local PUMA-to-tract crosswalk CSV

(Census Bureau format with STATEFP/COUNTYFP/TRACTCE/PUMA5CE columns). If not provided, downloads from remote URL.

get_popsyn_region(households: DataFrame) → Series

Derive census tract from location field based on location_mode.

get_survey_region(households_with_popsyn: DataFrame) → Series

Map census tracts to PUMAs using standard Census Bureau crosswalk.