Skip to content

Commit bb34d5f

Browse files
chekosclaude
chekos
and
claude
authored
Complete documentation overhaul (#301)
* Complete documentation overhaul with 25 new/rewritten pages (#301) Rewrites the entire documentation site from scratch to match the current library capabilities (get_acs, get_pums, get_decennial, get_estimates, get_flows, MOE utilities, spatial support, survey design, caching, CLI). - Upgrade to mkdocs-material theme with tabs, code copy, admonitions - Rewrite README with hero examples, badges, and feature overview - Add Getting Started section: installation, quickstart, Census 101 - Add 12 topic guides: ACS, Decennial, PUMS, Estimates, Flows, Variables, Geography, MOE, Spatial, Survey Design, Caching, Multi-year - Add API reference with mkdocstrings, CLI reference, datasets reference - Add 3 migration guides: from tidycensus, from old PyPUMS, from FTP - Add troubleshooting sections across guides - Add cross-links between all guides and references - Remove outdated user-guide/, history.md, surveys.md Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Address all PR review feedback - Add content.code.annotate feature flag to mkdocs.yml (critical) - Add mkdocs-autorefs as explicit docs dependency in pyproject.toml - Update pyproject.toml description to reflect current library scope - Align example years from 2022 to 2023 in index.md and README.md - Add lookup_fips() tip in from-tidycensus.md for county FIPS lookup - Add info admonition explaining NaN moe values in acs-data.md Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
1 parent b1b3d23 commit bb34d5f

34 files changed

+7141
-351
lines changed

‎CONTRIBUTING.md‎

Lines changed: 24 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -1,33 +1,37 @@
1-
# How to contribute
2-
To contribute to this library, first checkout the code. Then create a new virtual environment:
1+
# How to Contribute
32

4-
cd pypums
5-
python -m venv venv
6-
source venv/bin/activate
3+
To contribute to this library, first checkout the code. Then install [uv](https://docs.astral.sh/uv/) and set up the project:
74

8-
Or if you are using `pipenv`:
5+
```bash
6+
cd pypums
7+
uv sync --extra test
8+
```
99

10-
pipenv shell
11-
12-
Now install the dependencies and test dependencies:
10+
To run the tests:
1311

14-
pip install -e '.[test]'
12+
```bash
13+
uv run pytest
14+
```
1515

16-
To run the tests:
16+
To run the linter:
1717

18-
pytest
18+
```bash
19+
uvx ruff check .
20+
uvx ruff format --check .
21+
```
1922

20-
### Before submitting
23+
## Before Submitting
2124

2225
Before submitting your code please do the following steps:
2326

2427
1. Add any changes you want
25-
1. Add tests for the new changes
26-
1. Edit documentation if you have changed something significant
28+
2. Add tests for the new changes
29+
3. Edit documentation if you have changed something significant
30+
4. Make sure all tests pass with `uv run pytest`
31+
5. Make sure code style is clean with `uvx ruff check .`
32+
33+
## Other Help
2734

28-
## Other help
35+
You can contribute by spreading a word about this library. It would also be a huge contribution to write a short article on how you are using this project. You can also share your best practices with us.
2936

30-
You can contribute by spreading a word about this library.
31-
It would also be a huge contribution to write
32-
a short article on how you are using this project.
33-
You can also share your best practices with us.
37+
See the full [contributing guide](https://chekos.github.io/pypums/about/contributing/) for more details.

‎README.md‎

Lines changed: 96 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -1,56 +1,128 @@
1-
[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/chekos/pypums/HEAD?labpath=examples%2Fnb-example.ipynb)
1+
# PyPUMS
22

3-
# pypums
3+
**Python interface to the US Census Bureau API** — American Community Survey, Decennial Census, PUMS microdata, population estimates, and migration flows.
44

5-
[![Build status](https://github.com/chekos/pypums/workflows/build/badge.svg?branch=master&event=push)](https://github.com/chekos/pypums/actions?query=workflow%3Abuild)
6-
[![Changelog](https://img.shields.io/github/v/release/chekos/pypums?include_prereleases&label=changelog)](https://github.com/chekos/pypums/releases)
7-
[![License](https://img.shields.io/github/license/chekos/pypums)](https://github.com/chekos/pypums/blob/master/LICENSE)
5+
[![PyPI version](https://img.shields.io/pypi/v/pypums)](https://pypi.org/project/pypums/)
6+
[![Python versions](https://img.shields.io/pypi/pyversions/pypums)](https://pypi.org/project/pypums/)
7+
[![License](https://img.shields.io/github/license/chekos/pypums)](https://github.com/chekos/pypums/blob/main/LICENSE)
8+
[![Build status](https://github.com/chekos/pypums/workflows/build/badge.svg)](https://github.com/chekos/pypums/actions?query=workflow%3Abuild)
89

9-
Download Public Use Micro Sample (PUMS) data files from the US Census Bureau's FTP server.
10+
## Quick Start
1011

11-
## Usage
12+
Get county-level median household income for California:
1213

13-
To use PyPUMS in a project:
14+
```python
15+
import pypums
1416

15-
![on a jupyter notebook](https://github.com/chekos/pypums/blob/main/docs/static/usage.gif?raw=true)
17+
df = pypums.get_acs(
18+
geography="county",
19+
variables=["B19013_001"],
20+
state="CA",
21+
year=2023,
22+
)
23+
df.head()
24+
```
25+
26+
Make a map with tract-level data:
27+
28+
```python
29+
df = pypums.get_acs(
30+
geography="tract",
31+
variables=["B19013_001"],
32+
state="CA",
33+
county="037",
34+
year=2023,
35+
geometry=True, # returns a GeoDataFrame
36+
)
37+
df.plot(column="estimate", legend=True, figsize=(12, 8))
38+
```
39+
40+
Work with PUMS microdata:
41+
42+
```python
43+
pums = pypums.get_pums(
44+
variables=["AGEP", "SEX", "WAGP"],
45+
state="CA",
46+
year=2023,
47+
recode=True, # adds human-readable labels
48+
)
49+
pums.head()
50+
```
1651

17-
or as a CLI
52+
## Features
1853

19-
![as a CLI](https://github.com/chekos/pypums/blob/main/docs/static/cli.gif?raw=true)
54+
- **`get_acs()`** — American Community Survey data (1-year and 5-year)
55+
- **`get_decennial()`** — Decennial Census data (2000, 2010, 2020)
56+
- **`get_pums()`** — PUMS microdata with replicate weight support
57+
- **`get_estimates()`** — Population Estimates Program data
58+
- **`get_flows()`** — ACS migration flows (county and MSA level)
59+
- **`load_variables()`** — Search and browse Census variable codes
60+
- **MOE functions** — `moe_sum()`, `moe_ratio()`, `moe_prop()`, `moe_product()`, `significance()`
61+
- **Spatial support** — Attach TIGER/Line geometries, returns GeoDataFrames
62+
- **Survey design** — `SurveyDesign` class with successive difference replication
63+
- **Caching** — File-based caching with configurable TTL
64+
- **CLI** — Command-line access to all data functions
2065

2166
## Installation
2267

23-
Install this library using `pip`:
68+
```bash
69+
pip install pypums
70+
```
2471

25-
pip install pypums
72+
For spatial/mapping support:
2673

27-
## Usage
74+
```bash
75+
pip install "pypums[spatial]"
76+
```
2877

29-
Usage instructions go here.
78+
## Census API Key
79+
80+
You need a free Census API key. [Request one here](https://api.census.gov/data/key_signup.html), then:
81+
82+
```bash
83+
export CENSUS_API_KEY="your-key-here"
84+
```
85+
86+
Or set it in Python:
87+
88+
```python
89+
import pypums
90+
pypums.census_api_key("your-key-here")
91+
```
92+
93+
## Documentation
94+
95+
Full documentation: [https://chekos.github.io/pypums](https://chekos.github.io/pypums)
3096

3197
## Development
3298

3399
To contribute to this library, first checkout the code. Then install [uv](https://docs.astral.sh/uv/) and set up the project:
34100

35-
cd pypums
36-
uv sync --extra test
101+
```bash
102+
cd pypums
103+
uv sync --extra test
104+
```
37105

38106
To run the tests:
39107

40-
uv run pytest
108+
```bash
109+
uv run pytest
110+
```
41111

42112
To run the linter:
43113

44-
uvx ruff check .
45-
uvx ruff format --check .
114+
```bash
115+
uvx ruff check .
116+
uvx ruff format --check .
117+
```
46118

47-
## 📃 Citation
119+
## Citation
48120

49121
```
50122
@misc{pypums,
51-
author = {chekos},
52-
title = {Download Public Use Micro Sample (PUMS) data files from the US Census Bureau's FTP server.},
53-
year = {2020},
123+
author = {Sergio Sanchez Zavala},
124+
title = {PyPUMS: Python interface to the US Census Bureau API},
125+
year = {2019},
54126
publisher = {GitHub},
55127
journal = {GitHub repository},
56128
howpublished = {\url{https://github.com/chekos/pypums}}

‎docs/about/authors.md‎

Lines changed: 5 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,9 @@
1-
Credits
2-
=======
1+
# Authors
32

4-
Development Lead
5-
----------------
3+
## Development Lead
64

7-
- Sergio Sánchez Zavala <<sergio@cimarron.io>>
5+
- **Sergio Sanchez Zavala** — [github.com/chekos](https://github.com/chekos)
86

9-
Contributors
10-
------------
7+
## Contributors
118

12-
None yet. Why not be the first?
9+
- [@yonran](https://github.com/yonran) — Bug fixes and improvements (v0.0.7)

0 commit comments

Comments
 (0)