chekos · chekos · Mar 9, 2026 · Mar 9, 2026 · Mar 9, 2026
diff --git a/.gitignore b/.gitignore
@@ -1,6 +1,7 @@
 venv/
 .venv/
 .vscode/
+.claude/launch.json
 
 # Created by https://www.gitignore.io/api/osx,python,pycharm,windows,visualstudio,visualstudiocode
 # Edit at https://www.gitignore.io/?templates=osx,python,pycharm,windows,visualstudio,visualstudiocode

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -34,4 +34,4 @@ Before submitting your code please do the following steps:
 
 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.
 
-See the full [contributing guide](https://chekos.github.io/pypums/about/contributing/) for more details.
+See the full [contributing guide](https://pypums.readthedocs.io/about/contributing/) for more details.
diff --git a/README.md b/README.md
@@ -66,13 +66,13 @@ pums.head()
 ## Installation
 
 ```bash
-pip install pypums
+uv add pypums
 ```
 
 For spatial/mapping support:
 
 ```bash
-pip install "pypums[spatial]"
+uv add "pypums[spatial]"
 ```
 
 ## Census API Key
@@ -92,7 +92,7 @@ pypums.census_api_key("your-key-here")
 
 ## Documentation
 
-Full documentation: [https://chekos.github.io/pypums](https://chekos.github.io/pypums)
+Full documentation: [https://pypums.readthedocs.io](https://pypums.readthedocs.io)
 
 ## Development
 

diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md
@@ -7,17 +7,9 @@
 
 ## Install PyPUMS
 
-=== "pip"
-
-    ```bash
-    pip install pypums
-    ```
-
-=== "uv"
-
-    ```bash
-    uv add pypums
-    ```
+```bash
+uv add pypums
+```
 
 This installs PyPUMS and its core dependencies:
 
@@ -34,17 +26,9 @@ This installs PyPUMS and its core dependencies:
 
 If you plan to work with shapefiles, choropleths, or any geometry (the `geometry=True` parameter), install the spatial extras:
 
-=== "pip"
-
-    ```bash
-    pip install "pypums[spatial]"
-    ```
-
-=== "uv"
-
-    ```bash
-    uv add "pypums[spatial]"
-    ```
+```bash
+uv add "pypums[spatial]"
+```
 
 This adds [`geopandas`](https://geopandas.org/) and its dependencies (`shapely`, `pyproj`, `fiona`), which enable PyPUMS to fetch TIGER/Line shapefiles and return `GeoDataFrame` objects.
 
@@ -163,13 +147,13 @@ If this prints your key without raising an error, you are ready to go.
     running. Check with:
 
     ```bash
-    pip show pypums
+    uv pip show pypums
     ```
 
     If nothing is printed, install it again:
 
     ```bash
-    pip install pypums
+    uv add pypums
     ```
 
 ??? question "I get `ValueError: No Census API key found`"
@@ -186,7 +170,7 @@ If this prints your key without raising an error, you are ready to go.
     You need the spatial extras. Install them with:
 
     ```bash
-    pip install "pypums[spatial]"
+    uv add "pypums[spatial]"
     ```
 
 ## Next steps

diff --git a/docs/getting-started/quickstart.md b/docs/getting-started/quickstart.md
@@ -59,7 +59,7 @@ print(ca_income.head())
 
 ## 2. Make a map -- Tract-level choropleth
 
-Fetch tract-level poverty rates for Los Angeles County and plot a choropleth. This requires the `spatial` extras (`pip install "pypums[spatial]"`).
+Fetch tract-level poverty rates for Los Angeles County and plot a choropleth. This requires the `spatial` extras (`uv add "pypums[spatial]"`).
 
 ```python
 import pypums

diff --git a/docs/guides/acs-data.md b/docs/guides/acs-data.md
@@ -388,7 +388,7 @@ ca_counties_geo.plot(column="estimate", legend=True)
 
 !!! note "Optional dependency"
     `geometry=True` requires `geopandas`. Install it with
-    `pip install pypums[spatial]` or `pip install geopandas`.
+    `uv add "pypums[spatial]"`.
 
 ---
 
@@ -614,7 +614,7 @@ See the [Finding Variables](variables.md) guide for full details.
 **`ImportError: geopandas`**
 
 :   Geometry support requires the spatial extras. Install them with
-    `pip install "pypums[spatial]"`.
+    `uv add "pypums[spatial]"`.
 
 **`moe_level must be one of [90, 95, 99]`**
 

diff --git a/docs/guides/decennial-data.md b/docs/guides/decennial-data.md
@@ -230,7 +230,7 @@ county_geo.plot(column="value", legend=True)
 
 !!! note "Optional dependency"
     `geometry=True` requires `geopandas`. Install with
-    `pip install pypums[spatial]` or `pip install geopandas`.
+    `uv add "pypums[spatial]"`.
 
 ---
 

diff --git a/docs/guides/migration-flows.md b/docs/guides/migration-flows.md
@@ -223,7 +223,7 @@ ca_flows_geo.plot(column="estimate", legend=True)
     The `geometry=True` option requires `geopandas` to be installed:
 
     ```shell
-    pip install pypums[spatial]
+    uv add "pypums[spatial]"
     ```
 
 ## Caching

diff --git a/docs/guides/multi-year.md b/docs/guides/multi-year.md
@@ -51,16 +51,17 @@ years = range(2018, 2023)
 frames = []
 
 for year in years:
-    df = pypums.get_acs(
-        geography="state",
-        variables="B01001_001",
-        state=states,
-        year=year,
-        survey="acs5",
-        cache_table=True,  # cache to avoid re-fetching
-    )
-    df["year"] = year
-    frames.append(df)
+    for st in states:  # get_acs() accepts one state at a time
+        df = pypums.get_acs(
+            geography="state",
+            variables="B01001_001",
+            state=st,
+            year=year,
+            survey="acs5",
+            cache_table=True,  # cache to avoid re-fetching
+        )
+        df["year"] = year
+        frames.append(df)
 
 trend = pd.concat(frames, ignore_index=True)
 

diff --git a/docs/guides/population-estimates.md b/docs/guides/population-estimates.md
@@ -198,8 +198,14 @@ print(labeled[["NAME", "AGEGROUP", "AGEGROUP_label", "SEX", "SEX_label"]].head()
     | 10 | Age 18 to 64 years |
     | 11 | Age 18 years and over |
     | 12 | Age 65 years and over |
+    | 13 | Under 18 years |
+    | 14 | 5 to 13 years |
+    | 15 | 14 to 17 years |
+    | 16 | 18 to 64 years |
+    | 17 | 16 years and over |
     | 18 | Under 5 years |
     | 29 | Age 0 to 14 years |
+    | 30 | Age 15 to 44 years |
     | 31 | Age 16 years and over |
 
 === "SEX"
@@ -223,9 +229,9 @@ print(labeled[["NAME", "AGEGROUP", "AGEGROUP_label", "SEX", "SEX_label"]].head()
     | 6 | Two or more races |
     | 7 | White alone or in combination |
     | 8 | Black alone or in combination |
-    | 9 | AIAN alone or in combination |
+    | 9 | American Indian and Alaska Native alone or in combination |
     | 10 | Asian alone or in combination |
-    | 11 | NHPI alone or in combination |
+    | 11 | Native Hawaiian and Other Pacific Islander alone or in combination |
 
 === "HISP"
 
@@ -393,7 +399,7 @@ pop_geo.plot(column="value", legend=True, cmap="Blues")
 
 !!! note "Optional dependency"
     `geometry=True` requires `geopandas`. Install with
-    `pip install pypums[spatial]` or `pip install geopandas`.
+    `uv add "pypums[spatial]"`.
 
 ---
 

diff --git a/docs/guides/pums-microdata.md b/docs/guides/pums-microdata.md
@@ -531,7 +531,7 @@ print(summary.to_string(index=False))
 **`variables_filter` not reducing rows**
 :   Filters apply server-side but only to the variables you specify. If a
     variable name is misspelled, the API silently ignores it. Use
-    `pums_variables()` to confirm the exact variable codes.
+    `pypums.datasets.pums_variables()` to confirm the exact variable codes.
 
 **"PWGTP" or weight columns missing**
 :   The base weight `PWGTP` (person) or `WGTP` (housing) is always included
@@ -548,5 +548,5 @@ print(summary.to_string(index=False))
 
 - [Survey Design & Weights](survey-design.md) — Using replicate weights and the `SurveyDesign` class for standard errors
 - [API Reference](../reference/api.md) — Full `get_pums()` function signature
-- [Finding Variables](variables.md) — Browsing PUMS variable codes with `pums_variables()`
+- [Finding Variables](variables.md) — Browsing PUMS variable codes with `pypums.datasets.pums_variables()`
 - [Coming from Census FTP](../migration/from-census-ftp.md) — Migration guide for users switching from direct FTP downloads
diff --git a/docs/guides/spatial.md b/docs/guides/spatial.md
@@ -8,17 +8,9 @@ geospatial analysis.
     Geometry features depend on **geopandas** and its dependencies (`shapely`,
     `pyproj`, `fiona`). Install them with:
 
-    === "pip"
-
-        ```bash
-        pip install "pypums[spatial]"
-        ```
-
-    === "uv"
-
-        ```bash
-        uv add "pypums[spatial]"
-        ```
+    ```bash
+    uv add "pypums[spatial]"
+    ```
 
 ---
 
@@ -416,9 +408,8 @@ memory. A few tips for working with large datasets:
 ## Troubleshooting
 
 **`ImportError: geopandas is required for spatial operations`**
-:   Install the spatial extra: `pip install "pypums[spatial]"` (or
-    `uv add "pypums[spatial]"`). This pulls in `geopandas`, `shapely`, and
-    `pyproj`.
+:   Install the spatial extra: `uv add "pypums[spatial]"`. This pulls in
+    `geopandas`, `shapely`, and `pyproj`.
 
 **Geometry column is all `None`**
 :   The Census TIGER/Line server may not have shapefiles for the geography
@@ -439,9 +430,10 @@ memory. A few tips for working with large datasets:
     after dropping unneeded columns.
 
 **Dot-density map is slow or crashes**
-:   `as_dot_density()` generates one point per `n` people. For large areas,
-    increase `n` (e.g., `n=100` instead of `n=1`) or subset to a single
-    county before generating dots.
+:   `as_dot_density()` generates one point per `dots_per_value` people. For
+    large areas, increase `dots_per_value` (e.g., `dots_per_value=100`
+    instead of `dots_per_value=1`) or subset to a single county before
+    generating dots.
 
 ---
 

diff --git a/docs/guides/variables.md b/docs/guides/variables.md
@@ -5,8 +5,8 @@ alphanumeric string like `B19013_001` that points to a specific table, row,
 and measurement. Before you can pull data with `get_acs()` or
 `get_decennial()`, you need to know the right variable codes.
 
-PyPUMS provides `load_variables()` to search and browse the full Census
-variable catalog, plus `pums_variables()` for PUMS microdata fields.
+PyPUMS provides `pypums.load_variables()` to search and browse the full Census
+variable catalog, plus `pypums.datasets.pums_variables()` for PUMS microdata fields.
 
 ## What is a Census variable?
 

diff --git a/docs/index.md b/docs/index.md
@@ -77,13 +77,13 @@ df = pypums.get_acs(
 ## Quick Install
 
 ```bash
-pip install pypums
+uv add pypums
 ```
 
 For spatial/mapping support:
 
 ```bash
-pip install "pypums[spatial]"
+uv add "pypums[spatial]"
 ```
 
 You'll need a free [Census API key](https://api.census.gov/data/key_signup.html).

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -1,6 +1,6 @@
 site_name: PyPUMS
 site_description: Python interface to the US Census Bureau API
-site_url: https://chekos.github.io/pypums
+site_url: https://pypums.readthedocs.io
 repo_url: https://github.com/chekos/pypums
 repo_name: chekos/pypums
 
@@ -95,6 +95,9 @@ markdown_extensions:
           format: !!python/name:pymdownx.superfences.fence_code_format ''
   - pymdownx.tabbed:
       alternate_style: true
+  - pymdownx.emoji:
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
   - attr_list
   - md_in_html
   - tables

diff --git a/pyproject.toml b/pyproject.toml
@@ -21,6 +21,7 @@ dependencies = [
 
 [project.urls]
 Homepage = "https://github.com/chekos/pypums"
+Documentation = "https://pypums.readthedocs.io"
 Issues = "https://github.com/chekos/pypums/issues"
 CI = "https://github.com/chekos/pypums/actions"
 Changelog = "https://github.com/chekos/pypums/releases"
Original file line number	Diff line number	Diff line change
Expand Up		@@ -34,4 +34,4 @@ Before submitting your code please do the following steps:

		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.

		See the full [contributing guide](https://chekos.github.io/pypums/about/contributing/) for more details.
		See the full [contributing guide](https://pypums.readthedocs.io/about/contributing/) for more details.