pycen 0.1.0a1

Lightweight Python package for exploring and acquiring U.S. Census data with spatial integration

pycen

Lightweight Python package for exploring and acquiring U.S. Census data with intuitive spatial integration.

flowchart TD
    A[Need Census data?]

    A --> B & C

    subgraph PYCEN["<i>pycen</i>"]
        direction TB
        B[<b>`explore`</b><br/>Intuitive metadata<br/>keyword search]
        C[<b>`acquire`</b><br/>Data + boundaries<br/>in one call]

        C --> D
        C --> E

        D[<b>`quick_check`</b><br/>Quality validation]
        E[<b>`quick_viz`</b><br/>Instant maps]
    end

    B --> F
    D & E --> F[Domain analysis]

    style A fill:#94a3b8,stroke:#334155,stroke-width:2px,color:#000
    style B fill:#3b82f6,stroke:#1e40af,stroke-width:2px,color:#fff
    style C fill:#3b82f6,stroke:#1e40af,stroke-width:2px,color:#fff
    style D fill:#22c55e,stroke:#15803d,stroke-width:2px,color:#fff
    style E fill:#22c55e,stroke:#15803d,stroke-width:2px,color:#fff
    style F fill:#94a3b8,stroke:#334155,stroke-width:2px,color:#000
    style PYCEN fill:#1e293b,stroke:#64748b,stroke-width:2px,color:#fff

overview

pycen makes the exploration and acquisition of U.S. Census data accessible and intuitive for spatial data scientists. It presents Census API metadata as collapsible, interactive tree tables organized by topics. Built-in and customizable themes highlight curated variable combinations based on domain knowledge, making complex variable hierarchies easy to navigate. Spatial workflows are streamlined: one function call returns both data and boundaries as a GeoDataFrame, with separate tabular and spatial downloads available. Multi-year data fetch and longitudinal comparisons are also supported.

sample use

# basic workflow

import pycen
from pycen import explore, acquire

# 1. Explore variables
explore.search("income", year=2021, dataset="acs5").show()
explore.lookup("B19013_001E", year=2021, dataset="acs5")

# 2. Acquire data
gdf = acquire.get_censhp(
    variables=["B19013_001E", "B01003_001E"],
    geography="tract",
    state="CA",
    county="Alameda",
    year=2021,
)

acquire.quick_viz(gdf, "B19013_001E")

core functions

Explore

• explore.search(query, year, dataset) - supports exact term match and fuzzy keyword search
• explore.browse(year, dataset) - view all variables via interactive tree table with theme variable highlights
• explore.lookup(code, year, dataset) - inspect variable details

Acquire

• acquire.get_censhp(...) - data + boundaries --> GeoDataFrame
• acquire.get_census(...) - data only --> DataFrame
• acquire.get_boundaries(...) - boundaries only --> shp/gpkg
• acquire.quick_check(gdf) - N/A values summary
• acquire.quick_viz(gdf, column) - exploratory map + distribution histogram for select variable

Info

• pycen.get_product() - list datasets and years
• pycen.get_geography() - list geography levels by dataset

Notes

• Datasets: acs5, acs1, dec_pl, dec_sf1
• Spatial features require: geopandas, pygris

API key for higher rate limits:

pycen.set_api_key("YOUR_KEY")  # get key at api.census.gov/data/key_signup.html