ziptrend 0.1.0__tar.gz

ziptrend-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sam Oliver
+
+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.

ziptrend-0.1.0/PKG-INFO

@@ -0,0 +1,131 @@
+Metadata-Version: 2.4
+Name: ziptrend
+Version: 0.1.0
+Summary: Explore US ZIP-code observations across geography and time
+Author: Sam Oliver
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/samoliver3/ziptrend
+Project-URL: Source, https://github.com/samoliver3/ziptrend
+Project-URL: Issues, https://github.com/samoliver3/ziptrend/issues
+Keywords: zip code,geospatial,time series,dashboard,census
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: GIS
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pandas<4,>=2.2
+Requires-Dist: numpy>=1.26
+Requires-Dist: pgeocode<0.6,>=0.5
+Requires-Dist: openpyxl>=3.1
+Requires-Dist: xlrd>=2.0
+Provides-Extra: app
+Requires-Dist: plotly<8,>=5.24; extra == "app"
+Requires-Dist: streamlit<2,>=1.53; extra == "app"
+Provides-Extra: dev
+Requires-Dist: ziptrend[app]; extra == "dev"
+Requires-Dist: pytest>=8.2; extra == "dev"
+Requires-Dist: build>=1; extra == "dev"
+Dynamic: license-file
+
+# ZIPtrend
+
+A Python package and local browser dashboard for exploring numeric observations by U.S. ZIP code and time.
+
+![ZIPtrend dashboard showing Colorado ZIP markers, population summary metrics, and the monthly map timeline in dark mode](https://raw.githubusercontent.com/samoliver3/ziptrend/master/docs/images/dashboard.png)
+
+*Colorado demo view for May 2025, using fictional population data. Move the timeline to explore changes over time.*
+
+## Install
+
+Requires Python 3.11 or later.
+
+```powershell
+pip install "ziptrend[app]"   # data API plus the browser dashboard
+pip install ziptrend          # data API only, without Streamlit or Plotly
+```
+
+## Run the dashboard
+
+```powershell
+ziptrend
+```
+
+The dashboard opens at http://localhost:8501. It binds to localhost by default. A fictional 36-month sample is included, with offline geography. Upload your own file or download the sample CSV from the sidebar.
+
+## Explore
+
+- Import CSV, TSV, delimited UTF-8 TXT, Excel XLS/XLSX (select a worksheet), JSON arrays, or JSON Lines.
+- Map arbitrary column names to ZIP, date, and numeric measure. Select a different measure at any time.
+- Select states, then search ZIPs by typing or paste a comma-, space-, or newline-separated list. Include selected ZIPs or exclude them from the entire dashboard.
+- Use **Map timeline**, directly below the map, to step through days, months, or years according to **Time interval**. The map and its totals show only that interval. Optional date-range limits live in a collapsed sidebar section and narrow the timeline, trend charts, and exports.
+- Select a state to frame its full Census outline instead of zooming to the cluster of ZIP centroids. Color scales use the filtered geography and displayed interval; enable **Keep color scale fixed over time** to compare intervals against one scale within those same geography filters.
+- Switch between a cool-to-warm concentration heatmap and individually selectable ZIP markers. Click markers to add ZIPs to the searchable **Inspect ZIP codes** multiselect, or paste a list to compare several histories. Inspector selections only affect that comparison; sidebar ZIP filters affect the whole dashboard.
+- Compare ZIP or state trends, view top ZIPs, and export observations or a map summary.
+
+Example input:
+
+```csv
+zip,date,population
+02108,2024-01-01,4500
+02108,2024-02-01,4520
+80202,2024-01-01,15000
+80202,2024-02-01,15060
+```
+
+ZIPs retain leading zeros, Excel numeric ZIPs are padded, and ZIP+4 is reduced to five digits. Dates should preferably be ISO `YYYY-MM-DD`; years work too. Automatic ambiguous dates use month-first interpretation. Supply `%d/%m/%Y` for day-first dates. Numeric Excel serial dates must be converted to dates first. Values may contain thousands commas. Invalid rows and duplicate ZIP/date observations require correction or an explicit duplicate aggregation choice; records are not silently discarded.
+
+## Aggregation and geography
+
+`latest` (default) takes the final observation for each ZIP within each time interval on maps and trend charts. Use this for population snapshots. `mean` averages observations within the interval; `sum` adds them, appropriate for flows such as transactions. State curves sum the resulting ZIP values. Summing rates, percentages, or ZIP averages may not be meaningful; the package does not infer weights or denominators. State totals cover only uploaded ZIPs, and changing coverage can affect trends. Empty calendar intervals are included on the map timeline and display no values; no observations are carried forward. Optional date limits can clip a month/year. Exported map summaries correspond to the displayed interval; observation exports include the entire filtered range.
+
+The concentration map blends values at ZIP centroids. It does **not** show ZIP boundaries or population per unit land area. Heatmap intensity depends on nearby points and zoom; marker colors scale to the map's aggregated values. With automatic scaling, the same color can mean different values in different intervals: read the legend or use the fixed-scale option. Signed values use marker views. Geographic ZIP attribution uses a representative state; postal ZIPs are not Census ZCTAs and may cross boundaries. ZIP boundary choropleths and land-area-normalized density remain future extensions.
+
+Bundled state outlines are from the [U.S. Census Bureau's cartographic boundary files](https://www.census.gov/geographies/mapping-files/time-series/geo/carto-boundary-file.html), 2024, at 1:20,000,000 scale. They are simplified display boundaries, not survey boundaries. See `SOURCES.md` in the package's `assets` folder for the exact source and conversion details. State framing stays consistent across time bins even when the available ZIPs change. Basemap context outside a state's outline remains visible.
+
+Default ZIP geography comes from [GeoNames](https://www.geonames.org/) through [pgeocode](https://pgeocode.readthedocs.io/en/latest/), with GeoNames attribution under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). First use downloads a U.S. reference file; subsequent lookups use its local cache. Values in uploaded files are processed locally and are not sent to GeoNames. Basemap tiles come from CARTO/OpenStreetMap and require internet. Upload a CSV containing `zip,state,latitude,longitude` to use your own lookup without a reference download. Use two-letter state abbreviations. Missing geography is reported and retained for ZIP trends/exports.
+
+## Python API
+
+The data functions need only the base install; map charts (`ziptrend.charts`) need the `app` extra.
+
+```python
+from ziptrend import read_data, prepare_data, locate, summarize, trends
+
+raw = read_data("population.xlsx", sheet_name=0)
+data = prepare_data(raw, zip_column="zip", date_column="date",
+                    value_column="population", duplicate="error")
+data = locate(data)  # or locate(data, your_lookup_dataframe)
+colorado = data[data.state.eq("CO")]
+monthly = trends(colorado, frequency="month", method="latest")
+state_monthly = trends(colorado, frequency="month", group="state")
+snapshot = summarize(colorado, method="latest")
+```
+
+`summarize` aggregates the full input window; filter dates before calling it for a specific snapshot. Canonical columns are `zip,date,value`, plus `state,latitude,longitude` after `locate`.
+
+## Develop
+
+From a clone of this repository:
+
+```powershell
+py -3.12 -m venv .venv
+.\.venv\Scripts\python -m pip install -e ".[dev]"
+.\.venv\Scripts\python -m pytest
+.\.venv\Scripts\python -m build
+```
+
+Run tests with the virtual environment's `python -m pytest`, not a global `pytest`, so they use the project's dependencies. Dashboard and chart tests skip automatically when Streamlit or Plotly is not installed.
+
+The implementation uses [Streamlit chart selections](https://docs.streamlit.io/develop/api-reference/charts/st.plotly_chart) and [Plotly MapLibre maps](https://plotly.com/python/tile-map-layers/). Tests cover imports, ZIP normalization, invalid input, duplicate handling, aggregation semantics, missing geography, chart construction, and dashboard filters. The UI tests do not verify actual browser map clicks or external map tiles.
+
+## License
+
+MIT. See the `LICENSE` file.

ziptrend-0.1.0/README.md

@@ -0,0 +1,94 @@
+# ZIPtrend
+
+A Python package and local browser dashboard for exploring numeric observations by U.S. ZIP code and time.
+
+![ZIPtrend dashboard showing Colorado ZIP markers, population summary metrics, and the monthly map timeline in dark mode](https://raw.githubusercontent.com/samoliver3/ziptrend/master/docs/images/dashboard.png)
+
+*Colorado demo view for May 2025, using fictional population data. Move the timeline to explore changes over time.*
+
+## Install
+
+Requires Python 3.11 or later.
+
+```powershell
+pip install "ziptrend[app]"   # data API plus the browser dashboard
+pip install ziptrend          # data API only, without Streamlit or Plotly
+```
+
+## Run the dashboard
+
+```powershell
+ziptrend
+```
+
+The dashboard opens at http://localhost:8501. It binds to localhost by default. A fictional 36-month sample is included, with offline geography. Upload your own file or download the sample CSV from the sidebar.
+
+## Explore
+
+- Import CSV, TSV, delimited UTF-8 TXT, Excel XLS/XLSX (select a worksheet), JSON arrays, or JSON Lines.
+- Map arbitrary column names to ZIP, date, and numeric measure. Select a different measure at any time.
+- Select states, then search ZIPs by typing or paste a comma-, space-, or newline-separated list. Include selected ZIPs or exclude them from the entire dashboard.
+- Use **Map timeline**, directly below the map, to step through days, months, or years according to **Time interval**. The map and its totals show only that interval. Optional date-range limits live in a collapsed sidebar section and narrow the timeline, trend charts, and exports.
+- Select a state to frame its full Census outline instead of zooming to the cluster of ZIP centroids. Color scales use the filtered geography and displayed interval; enable **Keep color scale fixed over time** to compare intervals against one scale within those same geography filters.
+- Switch between a cool-to-warm concentration heatmap and individually selectable ZIP markers. Click markers to add ZIPs to the searchable **Inspect ZIP codes** multiselect, or paste a list to compare several histories. Inspector selections only affect that comparison; sidebar ZIP filters affect the whole dashboard.
+- Compare ZIP or state trends, view top ZIPs, and export observations or a map summary.
+
+Example input:
+
+```csv
+zip,date,population
+02108,2024-01-01,4500
+02108,2024-02-01,4520
+80202,2024-01-01,15000
+80202,2024-02-01,15060
+```
+
+ZIPs retain leading zeros, Excel numeric ZIPs are padded, and ZIP+4 is reduced to five digits. Dates should preferably be ISO `YYYY-MM-DD`; years work too. Automatic ambiguous dates use month-first interpretation. Supply `%d/%m/%Y` for day-first dates. Numeric Excel serial dates must be converted to dates first. Values may contain thousands commas. Invalid rows and duplicate ZIP/date observations require correction or an explicit duplicate aggregation choice; records are not silently discarded.
+
+## Aggregation and geography
+
+`latest` (default) takes the final observation for each ZIP within each time interval on maps and trend charts. Use this for population snapshots. `mean` averages observations within the interval; `sum` adds them, appropriate for flows such as transactions. State curves sum the resulting ZIP values. Summing rates, percentages, or ZIP averages may not be meaningful; the package does not infer weights or denominators. State totals cover only uploaded ZIPs, and changing coverage can affect trends. Empty calendar intervals are included on the map timeline and display no values; no observations are carried forward. Optional date limits can clip a month/year. Exported map summaries correspond to the displayed interval; observation exports include the entire filtered range.
+
+The concentration map blends values at ZIP centroids. It does **not** show ZIP boundaries or population per unit land area. Heatmap intensity depends on nearby points and zoom; marker colors scale to the map's aggregated values. With automatic scaling, the same color can mean different values in different intervals: read the legend or use the fixed-scale option. Signed values use marker views. Geographic ZIP attribution uses a representative state; postal ZIPs are not Census ZCTAs and may cross boundaries. ZIP boundary choropleths and land-area-normalized density remain future extensions.
+
+Bundled state outlines are from the [U.S. Census Bureau's cartographic boundary files](https://www.census.gov/geographies/mapping-files/time-series/geo/carto-boundary-file.html), 2024, at 1:20,000,000 scale. They are simplified display boundaries, not survey boundaries. See `SOURCES.md` in the package's `assets` folder for the exact source and conversion details. State framing stays consistent across time bins even when the available ZIPs change. Basemap context outside a state's outline remains visible.
+
+Default ZIP geography comes from [GeoNames](https://www.geonames.org/) through [pgeocode](https://pgeocode.readthedocs.io/en/latest/), with GeoNames attribution under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). First use downloads a U.S. reference file; subsequent lookups use its local cache. Values in uploaded files are processed locally and are not sent to GeoNames. Basemap tiles come from CARTO/OpenStreetMap and require internet. Upload a CSV containing `zip,state,latitude,longitude` to use your own lookup without a reference download. Use two-letter state abbreviations. Missing geography is reported and retained for ZIP trends/exports.
+
+## Python API
+
+The data functions need only the base install; map charts (`ziptrend.charts`) need the `app` extra.
+
+```python
+from ziptrend import read_data, prepare_data, locate, summarize, trends
+
+raw = read_data("population.xlsx", sheet_name=0)
+data = prepare_data(raw, zip_column="zip", date_column="date",
+                    value_column="population", duplicate="error")
+data = locate(data)  # or locate(data, your_lookup_dataframe)
+colorado = data[data.state.eq("CO")]
+monthly = trends(colorado, frequency="month", method="latest")
+state_monthly = trends(colorado, frequency="month", group="state")
+snapshot = summarize(colorado, method="latest")
+```
+
+`summarize` aggregates the full input window; filter dates before calling it for a specific snapshot. Canonical columns are `zip,date,value`, plus `state,latitude,longitude` after `locate`.
+
+## Develop
+
+From a clone of this repository:
+
+```powershell
+py -3.12 -m venv .venv
+.\.venv\Scripts\python -m pip install -e ".[dev]"
+.\.venv\Scripts\python -m pytest
+.\.venv\Scripts\python -m build
+```
+
+Run tests with the virtual environment's `python -m pytest`, not a global `pytest`, so they use the project's dependencies. Dashboard and chart tests skip automatically when Streamlit or Plotly is not installed.
+
+The implementation uses [Streamlit chart selections](https://docs.streamlit.io/develop/api-reference/charts/st.plotly_chart) and [Plotly MapLibre maps](https://plotly.com/python/tile-map-layers/). Tests cover imports, ZIP normalization, invalid input, duplicate handling, aggregation semantics, missing geography, chart construction, and dashboard filters. The UI tests do not verify actual browser map clicks or external map tiles.
+
+## License
+
+MIT. See the `LICENSE` file.

ziptrend-0.1.0/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ziptrend"
+version = "0.1.0"
+description = "Explore US ZIP-code observations across geography and time"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Sam Oliver" }]
+requires-python = ">=3.11"
+dependencies = ["pandas>=2.2,<4", "numpy>=1.26", "pgeocode>=0.5,<0.6", "openpyxl>=3.1", "xlrd>=2.0"]
+keywords = ["zip code", "geospatial", "time series", "dashboard", "census"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Scientific/Engineering :: GIS",
+    "Topic :: Scientific/Engineering :: Visualization",
+]
+
+[project.urls]
+Homepage = "https://github.com/samoliver3/ziptrend"
+Source = "https://github.com/samoliver3/ziptrend"
+Issues = "https://github.com/samoliver3/ziptrend/issues"
+
+[project.optional-dependencies]
+# The dashboard and map charts; the data API works without them.
+app = ["plotly>=5.24,<8", "streamlit>=1.53,<2"]
+dev = ["ziptrend[app]", "pytest>=8.2", "build>=1"]
+
+[project.scripts]
+ziptrend = "ziptrend.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+ziptrend = ["assets/*.geojson", "assets/*.md"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]
+

ziptrend-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ziptrend-0.1.0/src/ziptrend/__init__.py

@@ -0,0 +1,4 @@
+"""Data preparation and aggregation for US ZIP-code exploration."""
+from .data import read_data, prepare_data, summarize, trends, locate
+
+__all__ = ["read_data", "prepare_data", "summarize", "trends", "locate"]

ziptrend-0.1.0/src/ziptrend/app.py

@@ -0,0 +1,212 @@
+"""Streamlit entry point, also installed with the package."""
+import hashlib
+import pandas as pd
+import plotly.express as px
+import streamlit as st
+from ziptrend.data import read_data, prepare_data, locate, trends, time_bins, period_snapshot
+from ziptrend.demo import demo_data
+from ziptrend.charts import map_chart, COLORS
+from ziptrend.selection import parse_zip_list
+
+st.set_page_config(page_title="ZIPtrend · Geography over time", page_icon="◈", layout="wide")
+# Let Streamlit pair foregrounds and surfaces for the active light/dark theme.
+# Fixed light surfaces break contrast when the browser selects a dark theme.
+st.markdown("""<style>
+h1 {letter-spacing: -1.5px;}
+[data-testid="stMetric"] {
+    padding:18px;
+    border:1px solid currentColor;
+    border-color:color-mix(in srgb, currentColor 25%, transparent);
+    border-radius:14px;
+}
+[data-testid="stCaptionContainer"] {color:inherit; opacity:1;}
+/* A timeline selects one bin, not a cumulative range. Keep its rail neutral. */
+[data-testid="stSlider"]:has(input[aria-label="Map timeline"])
+    [data-rac][data-orientation="horizontal"] > div:first-child:not([data-rac]) {
+    background:color-mix(in srgb, currentColor 25%, transparent) !important;
+}
+</style>""", unsafe_allow_html=True)
+st.caption("ZIPTREND  /  U.S. DATA EXPLORER")
+st.write("Explore where values concentrate and how they change over time.")
+
+
+@st.cache_data(show_spinner=False)
+def resolve_geography(data):
+    return locate(data)
+
+
+def guess(columns, names):
+    return next((i for i, c in enumerate(columns) if str(c).lower() in names), 0)
+
+
+def zip_picker(label, options, key):
+    """Searchable selection with bulk entry and a predictable clear action."""
+    st.session_state[key] = [z for z in st.session_state.get(key, []) if z in options]
+    with st.expander("Paste a ZIP list", expanded=False):
+        pasted = st.text_area("ZIPs separated by commas, spaces, or newlines", key=f"{key}_paste",
+                              placeholder="02108, 80202, 80203")
+        if st.button("Add ZIP list", key=f"{key}_add"):
+            accepted, rejected = parse_zip_list(pasted, options)
+            st.session_state[key] = list(dict.fromkeys(st.session_state[key] + accepted))
+            if rejected:
+                st.warning("Not available in the current filters or invalid: " + ", ".join(rejected[:20]))
+            if accepted:
+                st.success(f"Added {len(accepted)} matching ZIP(s).")
+    if st.button("Clear ZIP selection", key=f"{key}_clear"):
+        st.session_state[key] = []
+    selected = st.multiselect(label, options, key=key, placeholder="Type a ZIP or prefix to search…",
+                              help="Type to narrow the list; select multiple ZIPs. Use Paste a ZIP list for bulk entry.")
+    st.caption(f"{len(selected):,} selected · {len(options):,} available")
+    return selected
+
+
+with st.sidebar:
+    st.header("Your data")
+    uploaded = st.file_uploader("Upload observations", type=["csv", "tsv", "txt", "xlsx", "xls", "json", "jsonl"])
+    raw_demo, demo_lookup = demo_data()
+    st.download_button("Download sample CSV", raw_demo.to_csv(index=False), "sample_population.csv", "text/csv")
+    lookup_file = st.file_uploader("Optional offline ZIP lookup", type=["csv"], help="Columns: zip, state (two-letter code), latitude, longitude. One row per ZIP.")
+    try:
+        if uploaded is None:
+            raw = raw_demo
+            source_key = "demo"
+            st.info("Showing fictional sample population, 2023–2025.")
+        else:
+            source_key = hashlib.sha256(uploaded.getvalue()).hexdigest()[:12]
+            sheet = 0
+            delimiter = None
+            if uploaded.name.lower().endswith((".xlsx", ".xls")):
+                sheet = st.selectbox("Worksheet", pd.ExcelFile(uploaded).sheet_names)
+            if uploaded.name.lower().endswith((".txt", ".csv")):
+                delimiter = {"Auto": None, "Comma": ",", "Tab": "\t", "Semicolon": ";", "Pipe": "|"}[st.selectbox("Delimiter", ["Auto", "Comma", "Tab", "Semicolon", "Pipe"])]
+            raw = read_data(uploaded, sheet_name=sheet, delimiter=delimiter)
+        columns = list(raw.columns)
+        if len(columns) < 3:
+            st.error("Provide at least a ZIP, date, and numeric value column.")
+            st.stop()
+        zip_col = st.selectbox("ZIP column", columns, index=guess(columns, {"zip", "zipcode", "zip_code", "postal_code"}), key=f"zip_{source_key}")
+        date_col = st.selectbox("Date column", columns, index=guess(columns, {"date", "month", "year"}), key=f"date_{source_key}")
+        val_col = st.selectbox("Measure", columns, index=guess(columns, {"population", "value", "count"}), key=f"value_{source_key}")
+        date_format = st.text_input("Date format (optional)", placeholder="%m/%d/%Y", help="Use %Y for years. ISO YYYY-MM-DD is recommended; otherwise automatic parsing uses month-first dates.")
+        duplicates = st.selectbox("Repeated ZIP/date rows", ["error", "sum", "mean", "last"])
+        data = prepare_data(raw, zip_column=zip_col, date_column=date_col, value_column=val_col,
+                            date_format=date_format or None, duplicate=duplicates)
+        if lookup_file:
+            data = locate(data, read_data(lookup_file))
+        elif uploaded is None:
+            data = locate(data, demo_lookup)
+        else:
+            with st.spinner("Finding ZIP geography…"):
+                data = resolve_geography(data)
+    except Exception as exc:
+        st.error(f"Unable to load data: {exc}")
+        st.caption("ZIP lookup needs internet on first use. Upload an offline lookup if unavailable.")
+        st.stop()
+    st.divider()
+    st.header("Explore")
+    states = st.multiselect("States · empty means all", sorted(data.state.dropna().unique()), key=f"states_{source_key}")
+    regional = data[data.state.isin(states)] if states else data
+    zip_mode = st.selectbox("ZIP filter", ["Include selected ZIPs", "Exclude selected ZIPs"])
+    zips = zip_picker("ZIP codes · empty means all", sorted(regional.zip.unique()), f"zips_{source_key}")
+    if zips:
+        matches = regional.zip.isin(zips)
+        regional = regional[matches if zip_mode == "Include selected ZIPs" else ~matches]
+    frequency = st.selectbox("Time interval", ["month", "year", "day"])
+    method = st.selectbox("Aggregation", ["latest", "mean", "sum"], help="Aggregate observations per ZIP within each time interval. Latest is suitable for population snapshots; sum for additive observations such as transactions.")
+    st.caption("State totals represent only ZIPs in your data. Missing periods are not filled.")
+
+if regional.empty:
+    st.info("No observations match these filters.")
+    st.stop()
+unknown = regional.loc[regional[["latitude", "longitude", "state"]].isna().any(axis=1), "zip"].unique()
+if len(unknown):
+    st.warning(f"{len(unknown)} ZIP(s) lack complete geography: {', '.join(unknown[:15])}. They remain in ZIP trends and exports; missing coordinates cannot appear on the map.")
+
+dates = sorted(regional.date.dt.date.unique())
+window = (dates[0], dates[-1])
+with st.sidebar.expander("Optional date-range filter"):
+    limit_dates = st.checkbox("Limit date range", value=False)
+    if limit_dates and len(dates) > 1:
+        window = st.select_slider("Date range", options=dates, value=window,
+                                  key=f"range_{source_key}_{','.join(states)}_{','.join(zips)}_{zip_mode}")
+    st.caption("Limits the timeline, trend charts, and exports. Use the slider below the map to step through time.")
+filtered = regional[regional.date.dt.date.between(*window)]
+series = trends(filtered, frequency, method)
+
+map_tab, trends_tab, table_tab = st.tabs(["Geography", "Trends & comparison", "Data & export"])
+with map_tab:
+    mode = st.radio("Map style", ["ZIP markers", "Concentration heatmap"], horizontal=True)
+    fixed_scale = st.checkbox("Keep color scale fixed over time", value=False,
+                              help="Off: rescale to the current filtered interval. On: use all intervals within the current state/ZIP filters for easier time comparisons.")
+    summary_area = st.container()
+    map_area = st.container()
+    periods = [value.to_pydatetime() for value in time_bins(filtered, frequency)]
+    timeline_key = "timeline_" + hashlib.sha256(str((source_key, frequency, window, states, zips, zip_mode)).encode()).hexdigest()[:16]
+    period_label = lambda value: value.strftime({"month": "%B %Y", "year": "%Y", "day": "%b %d, %Y"}[frequency])
+    if len(periods) > 1:
+        period = st.select_slider("Map timeline", options=periods, value=periods[-1],
+                                  format_func=period_label, key=timeline_key,
+                                  help=f"Each step shows one {frequency}. Empty intervals remain visible; missing observations are never carried forward.")
+    else:
+        period = periods[0]
+        st.caption(f"Map timeline: {period_label(period)} — only one interval available.")
+    snapshot = period_snapshot(filtered, period, frequency, method)
+    with summary_area:
+        st.subheader(f"{' · '.join(states) if states else 'United States'} · {period_label(period)}")
+        metrics = st.columns(3)
+        metrics[0].metric("ZIPs in this interval", f"{snapshot.zip.nunique():,}")
+        metrics[1].metric(f"{val_col} · sum across ZIPs", f"{snapshot.value.sum():,.0f}" if not snapshot.empty else "No data")
+        metrics[2].metric("Aggregation", method.title())
+        st.caption(f"{method.title()} per ZIP within this {frequency}. Cool blue → warm pink/red means lower → higher values. Select markers to add ZIPs to the comparison.")
+    mapped = snapshot.dropna(subset=["latitude", "longitude"])
+    options = sorted(filtered.zip.unique())
+    focus_key = f"inspect_{source_key}"
+    map_key = "map_" + hashlib.sha256(str((source_key, mode, period, window, method, options, states)).encode()).hexdigest()[:16]
+
+    def add_map_selection():
+        points = st.session_state[map_key].selection.points
+        selected = [point["customdata"][0] for point in points if point.get("customdata")]
+        st.session_state[focus_key] = list(dict.fromkeys(st.session_state.get(focus_key, []) + selected))
+
+    with map_area:
+        render_mode = mode
+        if snapshot.empty:
+            st.info("No observations in this interval. Move the timeline to another interval.")
+        elif mapped.empty:
+            st.info("No coordinates available in this interval. Trends remain available.")
+        if mode == "Concentration heatmap" and (mapped.value < 0).any():
+            st.info("This interval contains negative values; showing ZIP markers instead of a concentration heatmap.")
+            render_mode = "ZIP markers"
+        scale_values = series[series.zip.isin(filtered.dropna(subset=["latitude", "longitude"]).zip)].value if fixed_scale else mapped.value
+        limits = (float(scale_values.min()), float(scale_values.max())) if not scale_values.empty else None
+        if limits and limits[0] == limits[1]:
+            padding = abs(limits[0]) * 0.05 or 1
+            limits = (limits[0] - padding, limits[1] + padding)
+        fig = map_chart(mapped, render_mode, limits, states=states, view_data=filtered)
+        st.plotly_chart(fig, width="stretch", on_select=add_map_selection if mode == "ZIP markers" else "ignore",
+                        selection_mode="points", key=map_key)
+    st.caption("Colors use only the current state/ZIP filters" + (" across all timeline intervals." if fixed_scale else " and the displayed interval; the scale can change as you slide.") + " Heatmap intensity blends nearby values and varies with zoom; it is not population per unit area. Empty intervals show no values.")
+    st.caption("State outlines: U.S. Census Bureau, 2024 (generalized). ZIP boundaries are not included. Basemap © OpenStreetMap contributors © CARTO. ZIP centroids: GeoNames via pgeocode (CC BY 4.0).")
+    st.subheader("Inspect ZIP codes")
+    st.caption("Search or paste ZIPs to compare their histories. Clicking map markers adds ZIPs here. This selection affects only the comparison below; use the sidebar ZIP filter to filter the whole dashboard.")
+    focus = zip_picker("Inspect ZIP codes", options, focus_key)
+    if focus:
+        focus_data = series[series.zip.isin(focus)]
+        st.plotly_chart(px.line(focus_data, x="period", y="value", color="zip", markers=True, title=f"Selected ZIPs · {val_col}", labels={"value": str(val_col), "period": "Date", "zip": "ZIP"}), width="stretch")
+    else:
+        st.info("Select ZIP codes above or click map markers to compare their trends.")
+
+with trends_tab:
+    group = st.radio("Compare", ["zip", "state"], horizontal=True)
+    lines = trends(filtered, frequency, method, group)
+    st.plotly_chart(px.line(lines, x="period", y="value", color=group, markers=True,
+                            labels={"value": str(val_col), "period": "Date"}), width="stretch")
+    st.caption("Lines connect available observations; gaps do not mean zero. State curves sum the available ZIP values in each period; coverage can vary.")
+    st.plotly_chart(px.bar(snapshot.sort_values("value", ascending=False).head(25), x="zip", y="value", color="value",
+                           color_continuous_scale=COLORS, title=f"Top ZIPs · {period_label(period)}" ).update_xaxes(type="category"), width="stretch")
+with table_tab:
+    st.write("Observations in selected date range")
+    st.dataframe(filtered, hide_index=True, width="stretch")
+    st.download_button("Export filtered observations", filtered.to_csv(index=False), "ziptrend_observations.csv", "text/csv")
+    st.download_button("Export displayed map interval", snapshot.to_csv(index=False), f"ziptrend_{period:%Y-%m-%d}.csv", "text/csv")
+

ziptrend-0.1.0/src/ziptrend/assets/SOURCES.md

@@ -0,0 +1,12 @@
+# State outlines
+
+U.S. Census Bureau, 2024 cartographic boundary files, 1:20,000,000 scale.
+Source: https://www2.census.gov/geo/tiger/GENZ2024/shp/cb_2024_us_state_20m.zip
+Documentation: https://www.census.gov/geographies/mapping-files/time-series/geo/carto-boundary-file.html
+
+Converted from the Census shapefile to GeoJSON with `tools/convert_states.py`.
+Only state abbreviation/name and geometry are retained. These are generalized
+cartographic outlines for visualization, not legal or survey boundaries.
+Coordinates are NAD83 geographic coordinates, displayed on the web basemap as
+longitude/latitude; datum differences are negligible at this display scale.
+U.S. federal government geographic data; attribution: U.S. Census Bureau.