acspsuedo

Objects for handling the extraction of American Community Survey data.

Installation

From source:

$ git clone https://github.com/ramindersinghdubb/acspsuedo
$ cd acspsuedo
$ pip install .

Purposes

acspsuedo seeks to make data queries and extraction as seemless as possible with a user-friendly interface designed to support a host of purposes, such as:

• Running data queries to the Bureau, with support for concurrent application for users interested in ETL/ELT processes

• Querying metadata on particular variable and/or table information offered by any one of the ACS datasets (cf. acspsuedo.datasets)

• Querying metadata on the types of geographic scopes at which ACS demographic data may be available at (such as at the state-level, the county-level, and so forth)

• Enabling users with Census Bureau API keys to run multiple data queries in a session

• Continuous monitoring of the Census Bureau API, in order to ensure the most up-to-date information on all ACS datasets

• Caching the Bureau's Topologically Integerated Geographic Encoding and Referencing (TIGER) shapefiles, which are designed to provide geographic representations to support maps and/or geographic analysis

Usage

See notebooks for a demonstration of the module's utilities/interface.

acspsuedo handles the extraction of ACS data. For example, if one were interested in the B25058 "Median Contract Rents" table from the American Community Survey's 5-Year Estimates Detailed Tables dataset at the census tract level for California, it would be as so.

import acspsuedo.query as apq
from acspsuedo.datasets import ACS5
from acspsuedo.fips.states import CA

df = apq.download(
    dataset = ACS5,
    year    = 2023,
    table   = 'B25058',
    # Geographic specifiers
    state = CA,
    tract = '*'
)

Likewise, acspsuedo enriches data queries by providing geospatial information taken from the Census Bureau's TIGER Shapefile database. As a result, users can conduct geospatial analysis/visualization.

gdf = apq.download(
    dataset = ACS5,
    year    = 2023,
    table   = 'B25058',
    include_geometries = True,
    # Geographic specifiers
    state = CA,
    tract = '*'
)

An example of some geospatial visualization with the data generated from the query above. You can click on the image to see the notebook that generated it.

Note that an API key is recommended for querying multiple (50+) datasets in a session. You can obtain a free API key at https://api.census.gov/data/key_signup.html. We have implemented a interface via acspsuedo.query.api_key_config in which users can set their API keys. See the notebooks/API_Key notebook.

Repo Structure

acspsuedo/
├── .github/
│   └── workflows/
│       └── acs-api.yml      # CI/CD to ensure upkeep with API releases
│
├── acspsuedo/
│   ├── fips/                # Federal Information Processing Standard (FIPS) Codes
│   │   └── ...
│   │
│   ├── source/
│   │   └── ...
│   │
│   ├── __init__.py
│   ├── datasets.py          # Info on supported datasets
│   └── query.py             # Main interface
│
├── notebooks/
│   └── ...
│
├── tests/
│   └── ...
│
├── utils/
│   └── ...
│
├── .gitattributes
├── .gitignore
├── LICENSE
├── poetry.lock
├── pyproject.toml
└── README.md

Licensing

acspsuedo is licensed under the terms and conditions of the MIT license.