pycen 0.1.0a2__tar.gz

pycen-0.1.0a2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pycen contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pycen-0.1.0a2/PKG-INFO

@@ -0,0 +1,209 @@
+Metadata-Version: 2.4
+Name: pycen
+Version: 0.1.0a2
+Summary: Lightweight Python package for intuitively 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 workflows. The `explore` module presents browsable Census API metadata via topic-organized, interactive nested tables, with customizable themes to highlight curated variable recipes. It also supports natural‑language keyword searches for efficient variable discovery. The `acquire` module streamlines data processing: one function call returns both data and boundaries as a GeoDataFrame with built-in quality checks and rapid visualizations;simple tabular or boundaries-only downloads are separately callable. `pycen` pulls live data products with efficient local caches to keep iterations fast, smooth, and reproducible. The multi‑year fetch function enables longitudinal comparisons tracking change over time.
+
+## sample use
+
+```python
+# basic workflow
+import pycen
+from pycen import explore, acquire
+
+# 1. Explore variables
+# `browse` and `search` return interactive tables
+# `lookup` returns details
+explore.browse(year=2023, dataset="acs5").show()
+explore.search("vehicle", year=2023, dataset="acs5").show()
+explore.lookup("B08201_002E", year=2021, dataset="acs5")
+
+# 2. Acquire data
+## continental US income gini map
+gdf = acquire.get_censhp(
+    variables={"B19083_001E":"gini_index"},
+    geography="place",               # if no state/county, gets nationwide
+    dataset="acs5",
+    year=2023,
+)
+acquire.quick_check(gdf)             # returns N/A summary
+acquire.quick_viz(gdf, "gini_index") # returns map + distribution histogram
+
+## finer scale
+## Cook County income gini at tract level
+gdf = acquire.get_censhp(
+    variables={"B19083_001E":"gini_index"},
+    geography="tract",
+    county="Cook County County",
+    state="IL",
+    dataset="acs5",
+    year=2023,
+)
+acquire.quick_viz(gdf, "gini_index")
+
+## neighborhood analyses
+## Chicago super commuters
+gdf = acquire.get_censhp(
+    variables={"B08303_013E":"commute_over_60min", "B08303_001E":"total_commuters"},
+    geography="block group",
+    county="Cook County",
+    state="IL",
+    dataset="acs5",
+    year=2023,
+    clip_to="place",                    # default off, clip to [place/cbsa/csa]
+    place="Chicago city",
+)
+gdf["pct_super_commuters"] = gdf["commute_over_60min"] / gdf["total_commuters"] * 100
+acquire.quick_viz(gdf, "pct_super_commuters")
+
+## decennial data supports block-scale (finest)
+## Chicago housing vacancy rates at block level
+select_var={
+    "H001003": "vacant_hh",
+    "H001001": "total_hh"
+}
+gdf = acquire.get_censhp(
+    variables=select_var,
+    geography="block",
+    county="Cook County",
+    state="IL",
+    dataset="dec_pl",
+    year=2010,
+)
+gdf['vacancy_rate'] = gdf['vacant_hh'] / gdf['total_hh'] * 100
+acquire.quick_viz(gdf, "vacancy_rate")
+
+# 3. Tabular data only
+df = acquire.get_census(
+    variables=["B25032_022E"],  # renter-occupied, mobile home
+    geography="tract",
+    state="CA",
+    year=2021,
+)
+
+# 4. Multi-year tabular data for trend analysis
+# comparative tracking of remote work surge (2019–2023)
+from pycen import acquire
+import matplotlib.pyplot as plt
+
+# explore.search("work from home", year=2023, dataset="acs5").show()
+# B08101_049E = worked from home
+df_long = acquire.get_census(
+    variables={'B08101_049E': 'wfh_workers', 'B08101_001E': 'total_workers'},
+    geography='county',
+    state='CA',
+    years=[2019, 2020, 2021, 2022, 2023],
+    merge='long'
+)
+
+df_long['wfh_pct'] = (df_long['wfh_workers'] / df_long['total_workers']) * 100
+bay_area = df_long[df_long['NAME'].str.contains('San Francisco|Alameda|Santa Clara|Contra Costa|San Mateo')]
+
+for county in bay_area['NAME'].unique():
+    county_data = bay_area[bay_area['NAME'] == county]
+    plt.plot(county_data['year'], county_data['wfh_pct'], marker='o', label=county)
+
+plt.title('Bay Area WFH 2019-2023')
+plt.ylabel('Work From Home (%)')
+plt.xlabel('Year')
+plt.legend()
+plt.grid(alpha=0.3)
+plt.tight_layout()
+```
+
+## 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
+
+Themes
+- `pycen.set_theme(name_or_dict)` - set active theme name or register a custom theme (dict)
+- `pycen.get_theme_settings()` - get active theme name (defaults to a general curation of useful variables)
+- `pycen.explore.get_theme(name=None)` - get theme details (dict); defaults to active theme
+- `pycen.list_themes()` - list available theme names (includes session custom themes)
+
+## Notes
+
+- Datasets: `acs5`, `acs1`, `dec_pl`, `dec_sf1`
+- Spatial features require: `geopandas`, `pygris`
+- Geographies are resolved per dataset/year from Census geography metadata (live/cache/static)
+
+API key for higher rate limits:
+```python
+pycen.set_api_key("YOUR_KEY")  # get key at api.census.gov/data/key_signup.html
+```

pycen-0.1.0a2/README.md

@@ -0,0 +1,178 @@
+# 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 workflows. The `explore` module presents browsable Census API metadata via topic-organized, interactive nested tables, with customizable themes to highlight curated variable recipes. It also supports natural‑language keyword searches for efficient variable discovery. The `acquire` module streamlines data processing: one function call returns both data and boundaries as a GeoDataFrame with built-in quality checks and rapid visualizations;simple tabular or boundaries-only downloads are separately callable. `pycen` pulls live data products with efficient local caches to keep iterations fast, smooth, and reproducible. The multi‑year fetch function enables longitudinal comparisons tracking change over time.
+
+## sample use
+
+```python
+# basic workflow
+import pycen
+from pycen import explore, acquire
+
+# 1. Explore variables
+# `browse` and `search` return interactive tables
+# `lookup` returns details
+explore.browse(year=2023, dataset="acs5").show()
+explore.search("vehicle", year=2023, dataset="acs5").show()
+explore.lookup("B08201_002E", year=2021, dataset="acs5")
+
+# 2. Acquire data
+## continental US income gini map
+gdf = acquire.get_censhp(
+    variables={"B19083_001E":"gini_index"},
+    geography="place",               # if no state/county, gets nationwide
+    dataset="acs5",
+    year=2023,
+)
+acquire.quick_check(gdf)             # returns N/A summary
+acquire.quick_viz(gdf, "gini_index") # returns map + distribution histogram
+
+## finer scale
+## Cook County income gini at tract level
+gdf = acquire.get_censhp(
+    variables={"B19083_001E":"gini_index"},
+    geography="tract",
+    county="Cook County County",
+    state="IL",
+    dataset="acs5",
+    year=2023,
+)
+acquire.quick_viz(gdf, "gini_index")
+
+## neighborhood analyses
+## Chicago super commuters
+gdf = acquire.get_censhp(
+    variables={"B08303_013E":"commute_over_60min", "B08303_001E":"total_commuters"},
+    geography="block group",
+    county="Cook County",
+    state="IL",
+    dataset="acs5",
+    year=2023,
+    clip_to="place",                    # default off, clip to [place/cbsa/csa]
+    place="Chicago city",
+)
+gdf["pct_super_commuters"] = gdf["commute_over_60min"] / gdf["total_commuters"] * 100
+acquire.quick_viz(gdf, "pct_super_commuters")
+
+## decennial data supports block-scale (finest)
+## Chicago housing vacancy rates at block level
+select_var={
+    "H001003": "vacant_hh",
+    "H001001": "total_hh"
+}
+gdf = acquire.get_censhp(
+    variables=select_var,
+    geography="block",
+    county="Cook County",
+    state="IL",
+    dataset="dec_pl",
+    year=2010,
+)
+gdf['vacancy_rate'] = gdf['vacant_hh'] / gdf['total_hh'] * 100
+acquire.quick_viz(gdf, "vacancy_rate")
+
+# 3. Tabular data only
+df = acquire.get_census(
+    variables=["B25032_022E"],  # renter-occupied, mobile home
+    geography="tract",
+    state="CA",
+    year=2021,
+)
+
+# 4. Multi-year tabular data for trend analysis
+# comparative tracking of remote work surge (2019–2023)
+from pycen import acquire
+import matplotlib.pyplot as plt
+
+# explore.search("work from home", year=2023, dataset="acs5").show()
+# B08101_049E = worked from home
+df_long = acquire.get_census(
+    variables={'B08101_049E': 'wfh_workers', 'B08101_001E': 'total_workers'},
+    geography='county',
+    state='CA',
+    years=[2019, 2020, 2021, 2022, 2023],
+    merge='long'
+)
+
+df_long['wfh_pct'] = (df_long['wfh_workers'] / df_long['total_workers']) * 100
+bay_area = df_long[df_long['NAME'].str.contains('San Francisco|Alameda|Santa Clara|Contra Costa|San Mateo')]
+
+for county in bay_area['NAME'].unique():
+    county_data = bay_area[bay_area['NAME'] == county]
+    plt.plot(county_data['year'], county_data['wfh_pct'], marker='o', label=county)
+
+plt.title('Bay Area WFH 2019-2023')
+plt.ylabel('Work From Home (%)')
+plt.xlabel('Year')
+plt.legend()
+plt.grid(alpha=0.3)
+plt.tight_layout()
+```
+
+## 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
+
+Themes
+- `pycen.set_theme(name_or_dict)` - set active theme name or register a custom theme (dict)
+- `pycen.get_theme_settings()` - get active theme name (defaults to a general curation of useful variables)
+- `pycen.explore.get_theme(name=None)` - get theme details (dict); defaults to active theme
+- `pycen.list_themes()` - list available theme names (includes session custom themes)
+
+## Notes
+
+- Datasets: `acs5`, `acs1`, `dec_pl`, `dec_sf1`
+- Spatial features require: `geopandas`, `pygris`
+- Geographies are resolved per dataset/year from Census geography metadata (live/cache/static)
+
+API key for higher rate limits:
+```python
+pycen.set_api_key("YOUR_KEY")  # get key at api.census.gov/data/key_signup.html
+```

pycen-0.1.0a2/pycen/__init__.py

@@ -0,0 +1,82 @@
+"""pycen: Lightweight Python package for U.S. Census data with spatial integration."""
+
+__version__ = "0.1.0a2"
+
+from pycen import explore, acquire, geography
+from pycen.products import get_product, get_geography
+from pycen.explore.theme_config import list_themes as _list_themes
+
+_metadata_cache_enabled = False
+_metadata_cache_path = None
+_theme_name = None
+_api_key = None
+
+def set_api_key(key):
+    '''Set Census API key for this session.'''
+    global _api_key
+    _api_key = key
+
+def get_api_key():
+    '''Return the active Census API key (if set).'''
+    return _api_key
+
+def enable_metadata_cache(path=None):
+    '''Enable on-disk metadata cache.'''
+    global _metadata_cache_enabled, _metadata_cache_path
+    _metadata_cache_enabled = True
+    _metadata_cache_path = path
+
+def disable_metadata_cache():
+    '''Disable on-disk metadata cache.'''
+    global _metadata_cache_enabled
+    _metadata_cache_enabled = False
+
+def get_metadata_cache_settings():
+    '''Return (enabled, path) for metadata cache.'''
+    if not _metadata_cache_enabled:
+        return (False, None)
+    if _metadata_cache_path:
+        return (True, _metadata_cache_path)
+    from pathlib import Path
+    return (True, str(Path.home() / '.pycen' / 'metadata.db'))
+
+def set_theme(theme):
+    '''
+    Set the active search display theme.
+
+    theme: str theme name or None to reset to default.
+    '''
+    global _theme_name
+    if theme is None or isinstance(theme, str):
+        _theme_name = "default" if theme is None else theme
+        return
+    if isinstance(theme, dict):
+        from pycen.explore.theme_config import register_theme
+        name = register_theme(theme)
+        _theme_name = name
+        return
+    raise ValueError("theme must be a name (str), dict, or None.")
+
+def get_theme_settings():
+    '''Return the active theme name (defaults to "default").'''
+    return _theme_name or "default"
+
+def list_themes():
+    '''Return available theme names (built-in + custom).'''
+    return _list_themes()
+
+__all__ = [
+    'explore',
+    'acquire',
+    'geography',
+    'enable_metadata_cache',
+    'disable_metadata_cache',
+    'get_metadata_cache_settings',
+    'set_api_key',
+    'get_api_key',
+    'set_theme',
+    'get_theme_settings',
+    'list_themes',
+    'get_product',
+    'get_geography'
+]

pycen-0.1.0a2/pycen/acquire/__init__.py

@@ -0,0 +1,9 @@
+from pycen.acquire.get import get_census, get_boundaries, get_censhp, join_data
+from pycen.geography.listing import list_places, list_cbsa, list_csa, list_zcta
+from pycen.acquire.quick import quick_check, quick_viz
+
+__all__ = [
+    'get_census', 'get_boundaries', 'get_censhp', 'join_data',
+    'list_places', 'list_cbsa', 'list_csa', 'list_zcta',
+    'quick_check', 'quick_viz',
+]