Metadata-Version: 2.4
Name: pycen
Version: 0.1.0a1
Summary: Lightweight Python package for exploring and acquiring U.S. Census data with spatial integration
Author: pycen contributors
License-Expression: MIT
Keywords: census,acs,demographics,gis,spatial
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Scientific/Engineering :: GIS
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas<3.0,>=1.5
Requires-Dist: requests<3.0,>=2.28
Requires-Dist: us<4.0,>=2.0
Requires-Dist: tqdm<5.0,>=4.64
Requires-Dist: geopandas<1.0,>=0.14
Requires-Dist: pygris<0.3,>=0.1.6
Requires-Dist: shapely<3.0,>=2.0
Requires-Dist: matplotlib<4.0,>=3.5
Requires-Dist: mapclassify<3.0,>=2.4
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Dynamic: license-file

# pycen

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

```mermaid
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

```python
# 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:
```python
pycen.set_api_key("YOUR_KEY")  # get key at api.census.gov/data/key_signup.html
```

