morpc-census

Introduction

morpc-census is a Python package maintained by the MORPC data team for working with US Census Bureau data. It provides tools for connecting to the Census API, retrieving survey data, and structuring results as long-format tables with frictionless metadata.

This package depends on morpc-py for shared MORPC utilities.

Modules

• morpc_census.api — Census API client (Endpoint, Group, CensusAPI) and data structuring classes (DimensionTable, RaceDimensionTable, TimeSeries, RaceTable) for reshaping results into long- and wide-format DataFrames with frictionless metadata.
• morpc_census.geos — Geography utilities: Scope (named query extents), SumLevel (summary level codes), GeoIDFQ (GEOID parser/builder), and functions for translating between Census GEOIDs and MORPC geography definitions.
• morpc_census.tigerweb — Fetches GeoDataFrames from the Census TIGERweb REST API.
• morpc_census.constants — Domain lookup tables for age groups, race, education, income-to-poverty, and NTD categories.

Installation

pip install morpc-census

Dev Install

To install an editable version for development:

git clone https://github.com/jinskeep-morpc/morpc-census.git
pip install -e /path/to/morpc-census/

Then import as:

import morpc_census

Usage

from morpc_census import Endpoint, Group, CensusAPI, DimensionTable, RaceDimensionTable, SCOPES, SumLevel

ep  = Endpoint('acs/acs5', 2023)
grp = Group(ep, 'B01001')

# Fetch ACS 5-year age/sex data for counties in the 15-county region
api = CensusAPI(ep, SCOPES['region15'], group=grp, sumlevel=SumLevel('county'))

# Long-format DataFrame
print(api.long.head())

# Reshape into wide MultiIndex table and compute percentages
table = DimensionTable(api.long)
wide  = table.wide()
pct   = table.percent()

# Save data + frictionless schema + resource to disk
api.save('./output')

Demos and Documentation

See demos for examples and documentation.

Roadmap — Code Improvements

• Fix Python 3.10/3.11 syntax bug in geos.py
• Cache _get_api_key()
• Replace global _avail_endpoints_cache with @functools.cache
• Avoid double-computing wide() inside percent()
• Rename DimensionTable.variable_type → value_cols
• Rename map parameter in find_replace_variable_map → label_map
• Split CensusAPI.melt() into focused private helpers
• Pin numpy as an explicit dependency
• Add minimum version pins to all dependencies
• Add module docstrings to geos.py and tigerweb.py
• Validate or auto-fetch tigerweb.py current_endpoints

Roadmap — Production Readiness & PyPI Release

Phase 1 — Pre-release cleanup

• Apply all code improvement items above
• Fix the README usage example
• Expand test coverage for offline paths (wide(), percent(), remap(), drop(), melt())
• Update pyproject.toml classifier from Development Status :: 1 - Planning to 4 - Beta
• Add a CHANGELOG.md
• Add a py.typed marker file

Phase 2 — Dependency audit

• Assess whether morpc can be published to PyPI or replaced
• Document installation order if morpc remains a private dependency
• Pin morpc to a minimum version in pyproject.toml

Phase 3 — CI/CD

• Add GitHub Actions CI workflow (pytest -m "not network" on push/PR, Python 3.10–3.12)
• Add build verification step (python -m build + twine check)
• Add publish workflow triggered on release tags

Phase 4 — Versioning & release

• Switch to dynamic versioning via setuptools-scm
• Tag v0.1.0 and publish first release
• Document versioning policy and breaking-change rules in CONTRIBUTING.md

Phase 5 — Documentation

• Auto-generate API reference docs from docstrings
• Add CONTRIBUTING.md with setup instructions and PR process
• Add usage examples to docstrings for commonly called functions

This product uses the Census Bureau Data API but is not endorsed or certified by the Census Bureau.