{"id":32958493,"url":"https://github.com/mmann1123/pytidycensus","last_synced_at":"2025-11-12T23:00:48.306Z","repository":{"id":314479188,"uuid":"1055061472","full_name":"mmann1123/pytidycensus","owner":"mmann1123","description":"pytidycensus is a Python library that provides an integrated interface to several United States Census Bureau APIs and geographic boundary files. It allows users to return Census and American Community Survey (ACS) data as pandas DataFrames, and optionally returns GeoPandas GeoDataFrames with feature geometry for mapping and spatial analysis.","archived":false,"fork":false,"pushed_at":"2025-10-30T23:01:40.000Z","size":10364,"stargazers_count":8,"open_issues_count":3,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-31T01:04:34.082Z","etag":null,"topics":["census","geospatial"],"latest_commit_sha":null,"homepage":"https://mmann1123.github.io/pytidycensus/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mmann1123.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"docs/contributing.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-11T17:56:13.000Z","updated_at":"2025-10-27T00:50:28.000Z","dependencies_parsed_at":null,"dependency_job_id":"74486969-b3e0-44e9-a8f4-b3bdf2f5b985","html_url":"https://github.com/mmann1123/pytidycensus","commit_stats":null,"previous_names":["mmann1123/pytidycensus"],"tags_count":13,"template":false,"template_full_name":null,"purl":"pkg:github/mmann1123/pytidycensus","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mmann1123%2Fpytidycensus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mmann1123%2Fpytidycensus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mmann1123%2Fpytidycensus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mmann1123%2Fpytidycensus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mmann1123","download_url":"https://codeload.github.com/mmann1123/pytidycensus/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mmann1123%2Fpytidycensus/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":284110567,"owners_count":26949102,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-11-12T02:00:06.336Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["census","geospatial"],"created_at":"2025-11-12T23:00:36.034Z","updated_at":"2025-11-12T23:00:48.294Z","avatar_url":"https://github.com/mmann1123.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!-- # pytidycensus --\u003e\n                                         \n![pytidycensus logo](docs/static/logo.png)\n\n[![Python package](https://github.com/mmann1123/pytidycensus/actions/workflows/python-package.yml/badge.svg)](https://github.com/mmann1123/pytidycensus/actions/workflows/python-package.yml)\n[![Documentation Status](https://github.com/mmann1123/pytidycensus/actions/workflows/docs.yml/badge.svg)](https://mmann1123.github.io/pytidycensus)\n[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.17127531.svg)](https://doi.org/10.5281/zenodo.17127531)\n\n\n**pytidycensus** is a Python library that provides an integrated interface to several United States Census Bureau APIs and geographic boundary files. It allows users to return Census and American Community Survey (ACS) data as pandas DataFrames, and optionally returns GeoPandas GeoDataFrames with feature geometry for mapping and spatial analysis.\n\nIn version 1.0, pytidycensus introduces a conversational interface powered by Large Language Models (LLMs) to help users discover variables, choose geographic levels, and generate code snippets for data retrieval. This feature aims to make accessing Census data more intuitive and user-friendly.\n\n**This package is a Python port of the popular R package [tidycensus](https://walker-data.com/tidycensus/) created by Kyle Walker.**\n\n\n## Supported Datasets\n\n- **American Community Survey (ACS)**:  1-year and 5-year estimates (2005-2022) using `get_acs()` \n- **Decennial Census**:  1990, 2000, 2010, and 2020 using `get_decennial()`\n- **Population Estimates Program**:  Annual population estimates and components of change using `get_estimates()`\n- **Migration Flows**:  County-to-county migration data (2010-2018) using `get_flows()`\n\n## Geographic Levels\n\npytidycensus supports all major Census geographic levels:\n\n- US, Regions, Divisions\n- States, Counties  \n- Census Tracts, Block Groups\n- Places, ZCTAs\n- Congressional Districts\n- And more...\n\n## Features\n\n- **Simple API**: Clean, consistent interface for all Census datasets\n- **Pandas Integration**: Returns familiar pandas DataFrames\n- **Spatial Support**: Optional GeoPandas integration for mapping with TIGER/Line shapefiles\n- **Time Series Analysis**: Collect multi-year data with automatic area interpolation for changing boundaries\n- **Multiple Datasets**: Support for ACS, Decennial Census, Population Estimates, and Migration Flows\n- **Geographic Flexibility**: From national to block group level data\n- **Migration Analysis**: County-to-county population movement patterns with demographic breakdowns\n- **Caching**: Built-in caching for variables and geography data\n- **Comprehensive Testing**: Full test suite with high coverage\n- **LLM Assistant**: Conversational interface for variable discovery and code generation\n\n## Installation\n\n### From PyPI (Recommended)\n\n```bash\npip install pytidycensus\n```\n\n### Latest Version with Additional Features\n\nTo install with optional dependencies:\n\n```bash\n# For mapping functionality \npip install purify census[map]\n\n# For LLM assistant\npip install pytidycensus[LLM]\n\n# For time series analysis with area interpolation\npip install pytidycensus[time]\n\n# For development tools\npip install pytidycensus[dev]\n\n# For documentation tools\npip install pytidycensus[docs]\n\n# For all optional dependencies (including visualization)\npip install pytidycensus[all]\n```\n\nTo install the latest development version directly from GitHub:\n\n```bash\npip install git+https://github.com/mmann1123/pytidycensus.git\n```\n\n### For Contributors\n\nClone the repository and install in development mode:\n\n```bash\ngit clone https://github.com/mmann1123/pytidycensus.git\ncd pytidycensus\npip install -e .[all]\n```\n\n## Quick Start\n\nFirst, obtain a free API key from the [US Census Bureau](https://api.census.gov/data/key_signup.html):\n\n```python\nimport pytidycensus as tc\n\n# Set your API key\ntc.set_census_api_key(\"your_key_here\")\n\n# Get median household income by county in Texas\ntx_income = tc.get_acs(\n    geography=\"county\",\n    variables=\"B19013_001\",\n    state=\"TX\",\n    year=2022\n)\n\nprint(tx_income.head())\n```\n\n## Examples\n\n### ACS Data with Geometry\n\n```python\n# Get data with geographic boundaries for mapping\ntx_income_geo = tc.get_acs(\n    geography=\"county\",\n    variables=\"B19013_001\", \n    state=\"TX\",\n    geometry=True\n)\n\n# Plot the data\nimport matplotlib.pyplot as plt\ntx_income_geo.plot(column='value', legend=True, figsize=(12, 8))\nplt.title(\"Median Household Income by County in Texas\")\nplt.show()\n```\n\n### Multiple Variables\n\n```python\n# Get multiple demographic variables\ndemo_vars = {\n    \"Total_Population\": \"B01003_001\",\n    \"Median_Household_Income\": \"B19013_001\", \n    \"Median_Home_Value\": \"B25077_001\"\n}\n\nca_demo = tc.get_acs(\n    geography=\"county\",\n    variables=demo_vars,\n    state=\"CA\",\n    year=2022,\n    output=\"wide\"\n)\n```\n\n### Decennial Census\n\n```python\n# Get 2020 Census population data\npop_2020 = tc.get_decennial(\n    geography=\"state\",\n    variables=\"P1_001N\",  # Total population\n    year=2020\n)\n```\n\n### Searching for Variables\n\n```python\n# Find variables related to income\nincome_vars = tc.search_variables(\"income\", 2022, \"acs\", \"acs5\")\nprint(income_vars[['name', 'label']].head())\n```\n\n### Population Estimates Program\n\nThe Population Estimates Program (PEP) provides annual population estimates and components of change. For years 2020+, data is retrieved from CSV files; for earlier years, it uses the Census API.\n\n```python\n# Get total population estimates by state\nstate_pop = tc.get_estimates(\n    geography=\"state\",\n    variables=\"POP\",\n    year=2022\n)\n\n# Get components of population change\ncomponents = tc.get_estimates(\n    geography=\"state\", \n    variables=[\"BIRTHS\", \"DEATHS\", \"DOMESTICMIG\", \"INTERNATIONALMIG\"],\n    year=2022\n)\n\n# Get demographic breakdowns (characteristics)\ndemographics = tc.get_estimates(\n    geography=\"state\",\n    variables=\"POP\",\n    breakdown=[\"SEX\", \"RACE\"],\n    breakdown_labels=True,\n    year=2022\n)\n\n# Time series data\ntime_series = tc.get_estimates(\n    geography=\"state\",\n    variables=\"POP\",\n    time_series=True,\n    vintage=2023\n)\n```\n\n## Time Series Analysis\n\npytidycensus provides powerful time series functionality that automatically handles changing geographic boundaries through area interpolation. This is particularly useful for tract-level analysis where boundaries change between Census years.\n\n### Installation for Time Series\n\n```bash\n# Install with time series support\npip install pytidycensus[time]\n```\n\n### Basic Time Series\n\n```python\n# Get ACS data across multiple years with area interpolation\ndata = tc.get_time_series(\n    geography=\"tract\",\n    variables={\"total_pop\": \"B01003_001E\", \"median_income\": \"B19013_001E\"},\n    years=[2015, 2020],\n    dataset=\"acs5\",\n    state=\"DC\",\n    base_year=2020,  # Use 2020 boundaries as base\n    extensive_variables=[\"total_pop\"],      # Counts/totals\n    intensive_variables=[\"median_income\"],  # Rates/medians\n    geometry=True,\n    output=\"wide\"\n)\n```\n\n### Decennial Census Time Series\n\n```python\n# Handle different variable codes across years\nvariables = {\n    2010: {\"total_pop\": \"P001001\"},    # 2010 uses P001001\n    2020: {\"total_pop\": \"P1_001N\"}     # 2020 uses P1_001N\n}\n\ndata = tc.get_time_series(\n    geography=\"tract\",\n    variables=variables,\n    years=[2010, 2020],\n    dataset=\"decennial\",\n    state=\"DC\",\n    base_year=2020,\n    extensive_variables=[\"total_pop\"],\n    geometry=True\n)\n```\n\n### Time Period Comparison\n\n```python\n# Compare specific time periods\ncomparison = tc.compare_time_periods(\n    data=data,\n    base_period=2015,\n    comparison_period=2020,\n    variables=[\"total_pop\", \"median_income\"],\n    calculate_change=True,\n    calculate_percent_change=True\n)\n\n# Results include columns like:\n# total_pop_2015, total_pop_2020, total_pop_change, total_pop_pct_change\n```\n\n### Key Features\n\n- **Automatic Area Interpolation**: Handles changing tract boundaries using the `tobler` library\n- **Variable Classification**: Distinguishes between extensive (counts) and intensive (rates) variables\n- **Flexible Output**: Wide format (multi-index columns) or tidy format (long form)\n- **Built-in Validation**: Checks interpolation accuracy and data conservation\n- **Multiple Datasets**: Support for both ACS and Decennial Census time series\n\n### Geographic Boundary Handling\n\n- **Stable Geographies** (state, county): No interpolation needed\n- **Changing Geographies** (tract, block group): Automatic area interpolation\n- **Base Year Selection**: Choose which year's boundaries to use as the reference\n\nFor detailed examples, see [examples/time_series_analysis_comprehensive.py](examples/time_series_analysis_comprehensive.py).\n\n\n### Migration Flows\n\nThe Migration Flows API provides data on population movement between geographic areas based on American Community Survey (ACS) 5-year estimates.\n\n```python\n# Get county-to-county migration flows for Texas\ntx_flows = tc.get_flows(\n    geography=\"county\",\n    state=\"TX\",\n    year=2018,\n    output=\"wide\"\n)\n\n# Get flows with demographic breakdowns (2006-2015 only)\nca_flows = tc.get_flows(\n    geography=\"county\",\n    breakdown=[\"AGE\", \"SEX\"],\n    breakdown_labels=True,\n    state=\"CA\",\n    year=2015,\n    output=\"tidy\"\n)\n\n# MSA-level migration flows\nmsa_flows = tc.get_flows(\n    geography=\"metropolitan statistical area\",\n    year=2018\n)\n\n# Flows with geometry for mapping (when TIGER server is available)\ntry:\n    flows_geo = tc.get_flows(\n        geography=\"county\",\n        state=\"FL\",\n        year=2018,\n        geometry=True\n    )\nexcept RuntimeError:\n    # Fallback without geometry if server issues\n    flows_geo = tc.get_flows(\n        geography=\"county\",\n        state=\"FL\",\n        year=2018,\n        geometry=False\n    )\n\n# See examples/09_migration_flows_example.ipynb for comprehensive tutorial\n```\n\n## LLM Assistant\nFor users interested in leveraging Large Language Models (LLMs) to interact with Census data, pytidycensus offers a conversational interface. This feature helps users discover relevant variables, choose appropriate geographic levels, and generate code snippets for data retrieval.\n\nPlease refer to the [LLM Assistant Documentation](docs/llm_assistant.md) for detailed instructions on setup and usage.\n\n\n#### Example: Spatial Analysis with Geometry\n\n```\n👤 User: I need Wisconsin county income data for mapping\n🏛️ Assistant: I understand. What additional details do you need for this analysis?\n\n👤 User: Include geographic boundaries\n🏛️ Assistant: I understand. What additional details do you need for this analysis?\n\n👤 User: 2020 ACS data\n🏛️ Assistant: 2020 ACS data is a good choice. Should I use the 5-year estimates for better coverage?\n\n👤 User: Generate the mapping-ready code\n🏛️ Assistant: I'll generate the pytidycensus code for you now.\n\n📋 Final State: geography=county, variables=['B19013_001'], state=WI, year=2020, geometry=True\n```\n\n**Generated Code:**\n```python\nimport pytidycensus as tc\n\n# Get Census data (wide format with cleaned variable names)\ndata = tc.get_acs(\n    geography=\"county\",\n    variables=[\"B19013_001E\"],\n    state=\"WI\",\n    year=2020,\n    output=\"wide\",\n    geometry=True,\n    api_key=census_api_key\n)\n\nprint(data.head())\n\n# Ready for mapping with GeoPandas\ndata.plot(column='B19013_001', legend=True)\n```\n\n**Result:** GeoPandas GeoDataFrame ready for mapping with clean column name `B19013_001`\n\n## Documentation\n\nFull documentation is available at: [https://mmann1123.github.io/pytidycensus/](https://mmann1123.github.io/pytidycensus/)\n\n## Contributing\n\nContributions are welcome! Please see our [contributing guidelines](CONTRIBUTING.md) for details.\n\n## Testing\n\nRun the test suite:\n\n```bash\npytest\n```\n\nWith coverage:\n\n```bash\npytest --cov=pytidycensus --cov-report=html\n```\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Acknowledgments\n\n- Kyle Walker for creating the original [tidycensus](https://walker-data.com/tidycensus/) R package\n- The US Census Bureau for providing comprehensive APIs and data access\n- The pandas and GeoPandas communities for excellent geospatial Python tools\n\n## Citation\n\nIf you use pytidycensus in your research, please cite:\n\n```\nMichael Mann. (2025). mmann1123/pytidycensus: Pulling_dats (v0.1.1). Zenodo. https://doi.org/10.5281/zenodo.17127531\n```\n\n```bibtex\n@software{michael_mann_2025_17127531,\n  author       = {Michael Mann},\n  title        = {mmann1123/pytidycensus: Pulling\\_dats},\n  month        = sep,\n  year         = 2025,\n  publisher    = {Zenodo},\n  version      = {v0.1.1},\n  doi          = {10.5281/zenodo.17127531},\n  url          = {https://doi.org/10.5281/zenodo.17127531},\n  swhid        = {swh:1:dir:3b2349029a986051469f46880930526c33d2dac5\n                   ;origin=https://doi.org/10.5281/zenodo.17127530;vi\n                   sit=swh:1:snp:2ff62e0d63a7af64334553edefe8f76a906d\n                   c93f;anchor=swh:1:rel:ad19678c36a258e13eee43c8f5fa\n                   5ff2d9e4047f;path=mmann1123-pytidycensus-27d849c\n                  },\n}\n```\n\n[![GWU Geography \u0026 Environment](docs/static/GWU_GE.png)](https://geography.columbian.gwu.edu/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmmann1123%2Fpytidycensus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmmann1123%2Fpytidycensus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmmann1123%2Fpytidycensus/lists"}