carto_flow.data¶

Data loading utilities for example datasets used in documentation and examples.

This module provides convenience functions to load example datasets without requiring users to manually download and manage data files. The datasets are either included with the package or downloaded on-demand from reliable sources.

Census Data

load_us_census reads a bundled snapshot (ACS 2020, GeoParquet) shipped inside the package for its default resolution, so that path needs no network access, API key, or optional dependency at runtime. Requests outside the bundled snapshot (a vintage other than 2020, or a simplify tolerance finer than 1000 m) fall back to a live download via censusdis (extra data), which needs a Census API key. See load_us_census for details and scripts/build_census_snapshot.py to regenerate the bundled snapshot.

State-Region and State-Division Mappings

The following dictionaries provide mappings between US states (identified by their 2-digit FIPS codes) and their respective census regions and divisions, as defined by the US Census Bureau:

STATE_REGIONS: Maps state FIPS codes to region codes (1-4)
STATE_DIVISIONS: Maps state FIPS codes to division codes (1-9)
REGION_NAMES: Maps region codes to human-readable region names
DIVISION_NAMES: Maps division codes to human-readable division names
REGION_DIVISIONS: Maps region codes to lists of division codes within that region

Functions:

load_sample_cities –

Load a sample dataset of cities with population information.
load_us_census –

Load US boundaries with ACS demographic data from the US Census Bureau.
load_us_covid_weekly –

Load weekly US COVID-19 confirmed cases per state (2020-01 to 2023-03).
load_us_state_population –

Load historical US state population estimates (1900-2024).
load_us_states –

Load a US states dataset with population and area information.
load_world –

Load a world countries dataset with population estimates.

load_sample_cities ¶

load_sample_cities() -> geopandas.GeoDataFrame

Load a sample dataset of cities with population information.

This dataset includes major cities around the world with population estimates.

Returns:

GeoDataFrame –

Cities dataset with geometry and population information.

Examples:

>>> from carto_flow.data import load_sample_cities
>>> gdf = load_sample_cities()
>>> print(gdf.shape)
(200, ...)

load_us_census ¶

load_us_census(
    population: bool = True,
    race: bool = False,
    poverty: bool = False,
    level: str = "state",
    simplify: float | None = None,
    vintage: int = 2020,
    contiguous_only: bool = True,
) -> geopandas.GeoDataFrame

Load US boundaries with ACS demographic data from the US Census Bureau.

For the default vintage (2020) at the bundled resolution (simplify None or >= 1000), this reads a bundled snapshot of the American Community Survey (ACS) 5-year estimates shipped inside the package as GeoParquet: no network access or Census API key is required. Geometries are bundled at 500k cartographic-boundary resolution, coverage-simplified at 1000 m, then densified so no straight segment exceeds 5 km (see carto_flow.geo_utils.simplify_coverage for why: algorithms that move vertices, like the flow cartogram, cannot bend a segment that has no interior vertices).

For any other request — a vintage other than 2020, or a simplify tolerance finer than the bundled 1000 m — this falls back to a live download via censusdis (install with pip install carto-flow[data]), which needs a Census API key (see https://api.census.gov/data/key_signup.html), read from the US_CENSUS_API_KEY environment variable or ~/.censusdis/api_key.txt.

In both cases the result is projected to the Albers equal-area projection (ESRI:102008) and has the same columns.

Parameters:

population (bool, default: True ) –

Include total population. Adds columns: - Population, Population (Millions), Population Density
race (bool, default: False ) –

Include race/ethnicity breakdown. Adds columns: - Total Race, White, Black or African American, Asian, Hispanic or Latino, and corresponding <group> % columns.
poverty (bool, default: False ) –

Include poverty status. Adds columns: - Total Poverty, Below Poverty Level, Above Poverty Level, Below Poverty Level %, Above Poverty Level %
level (str, default: "state" ) –

Geographic level of detail. One of: - "state" — one row per US state. Adds column State Name. - "congressional_district" — one row per congressional district. Adds columns District Name and State Name.
simplify (float or None, default: None ) –

Simplification tolerance in meters (units of ESRI:102008). None (default) keeps the source resolution: the bundled 1000 m (already densified to 5 km segments) for vintage 2020, or full resolution for a live download. A value >= 1000 with vintage 2020 re-simplifies the bundled geometries locally; any other value (including < 1000) triggers a live download, simplified to that tolerance and densified to 5 km segments.
vintage (int, default: 2020 ) –

ACS 5-year vintage year. 2020 uses the bundled snapshot (at the bundled resolution); any other vintage triggers a live download.
contiguous_only (bool, default: True ) –

Exclude Alaska, Hawaii, Puerto Rico, and DC.

Returns:

GeoDataFrame –

Dataset in ESRI:102008 (Albers equal-area, meters). Both levels include State Abbreviation, Region, and Division columns.

Raises:

ImportError –

If a live download is needed and censusdis is not installed.
RuntimeError –

If a live download is needed and no Census API key is found, or the download itself fails.

Examples:

>>> from carto_flow.data import load_us_census
>>> gdf = load_us_census(population=True, race=True)
>>> print(gdf["State Name"].head())

>>> gdf_dist = load_us_census(level="congressional_district", population=True)
>>> print(gdf_dist["District Name"].head())

load_us_covid_weekly ¶

load_us_covid_weekly() -> pandas.DataFrame

Load weekly US COVID-19 confirmed cases per state (2020-01 to 2023-03).

Values are weekly new confirmed cases -- counts, not rates -- for all 50 states, DC, and five territories, summed from the county-level cumulative series and aggregated into weeks ending Sunday. Divide by a population column to get a rate.

The data comes from the Johns Hopkins University Center for Systems Science and Engineering (JHU CSSE) COVID-19 Data Repository, licensed CC BY 4.0; attribution to JHU is required wherever the data is shown. Collection ended on 2023-03-09 and the repository was archived, so the series is final.

state_name matches the State Name column of load_us_census for the 50 states and DC.

To update the data, run scripts/download_covid_cases.py.

Returns:

DataFrame –

Columns: week_ending (datetime64), state_name, new_cases.

Examples:

>>> from carto_flow.data import load_us_covid_weekly
>>> df = load_us_covid_weekly()
>>> print(df.shape)
(9184, 3)
>>> weekly = df.pivot(index="week_ending", columns="state_name", values="new_cases")
>>> print(weekly.shape)
(164, 56)

load_us_state_population ¶

load_us_state_population() -> pandas.DataFrame

Load historical US state population estimates (1900-2024).

Annual population estimates for all 50 states, DC, and Puerto Rico (Puerto Rico from 2010 onward only). Pre-1970 values are rounded intercensal estimates; 1970-2024 are from the US Census Bureau.

The data was compiled from:

1900-1969: JoshData/historical-state-population-csv (GitHub)
1970-2024: US Census Bureau population estimate programs

To update the data, run scripts/download_state_population.py.

Returns:

DataFrame –

Columns: year, state_fips, state_name, state_abbr, population.

Examples:

>>> from carto_flow.data import load_us_state_population
>>> df = load_us_state_population()
>>> df.head(2)
   year state_fips state_name state_abbr  population
0  1900         01    Alabama         AL     1830000
1  1900         02     Alaska         AK      ...

load_us_states ¶

load_us_states() -> geopandas.GeoDataFrame

Load a US states dataset with population and area information.

This dataset includes state boundaries, population estimates, and area information from the US Census Bureau.

Returns:

GeoDataFrame –

US states dataset with geometry and demographic information.

Examples:

>>> from carto_flow.data import load_us_states
>>> gdf = load_us_states()
>>> print(gdf.shape)
(51, ...)

load_world ¶

load_world() -> geopandas.GeoDataFrame

Load a world countries dataset with population estimates.

This dataset includes country boundaries and population estimates from Natural Earth (public domain data).

Returns:

GeoDataFrame –

World countries dataset with geometry and population information. Columns: - name: Country name - continent: Continent name - pop_est: Population estimate - gdp_md_est: GDP estimate (millions USD) - geometry: Country boundaries

Examples:

>>> from carto_flow.data import load_world
>>> gdf = load_world()
>>> print(gdf.shape)
(177, 5)