From a2d295c3e490d78ccb5791143e54a79861162de2 Mon Sep 17 00:00:00 2001 From: Evan Murray Date: Thu, 29 Oct 2026 17:11:03 -0400 Subject: [PATCH 1/3] Redesign frontend UI & actually use backend data --- .streamlit/config.toml | 9 +- app.py | 422 +++++++++++------------------------------ dashboard/__init__.py | 0 dashboard/charts.py | 218 +++++++++++++++++++++ dashboard/data.py | 103 ++++++++++ scripts/build_site.py | 3 + 6 files changed, 447 insertions(+), 308 deletions(-) create mode 100644 dashboard/__init__.py create mode 100644 dashboard/charts.py create mode 100644 dashboard/data.py diff --git a/.streamlit/config.toml b/.streamlit/config.toml index 7357e68..8c2ec47 100644 --- a/.streamlit/config.toml +++ b/.streamlit/config.toml @@ -1,3 +1,10 @@ [theme] base = "light" -primaryColor = "#1a73e8" +primaryColor = "#2a78d6" +backgroundColor = "#f9f9f7" +secondaryBackgroundColor = "#f0efec" +textColor = "#0b0b0b" +font = "sans-serif" + +[client] +toolbarMode = "minimal" diff --git a/app.py b/app.py index 5c9965f..227d8ce 100644 --- a/app.py +++ b/app.py @@ -1,335 +1,143 @@ -"""Mableton communication-needs frontend. Run: uv run streamlit run app.py. +"""The Streamlit app. Run with `uv run streamlit run app.py`. -Boundary polygons and 2020 population come from committed data/ GeoJSON. -Demographic rates are DEMONSTRATION ONLY until a validated CSV is supplied. +It reads only files committed in data/, so it needs no keys or secrets to run. +Fetching and preparing data happens in backend/ and scripts/, ahead of time. +The pieces live in dashboard/: data.py (loading, measure wording) and charts.py (figures). """ -import json -from pathlib import Path - -import pandas as pd -import plotly.express as px -import pydeck as pdk import streamlit as st -BASE = Path(__file__).resolve().parent -BOUNDARIES = BASE / "data" / "mableton-council-districts.geojson" -METRICS_CSV = BASE / "data" / "district_metrics.csv" -METRICS = { - "Language other than English at home": "language_pct", - "Residents age 65+": "age65_pct", - "Households without internet": "no_internet_pct", -} -COLORS = { - "Language other than English at home": "#6366f1", - "Residents age 65+": "#0891b2", - "Households without internet": "#e07a39", -} - -st.set_page_config( - page_title="Mableton | Communication Needs", page_icon="🗺️", layout="wide" +from dashboard.charts import district_bars, district_map +from dashboard.data import ( + CITY, + MEASURES, + area_name, + city_totals, + in_words, + load_boundaries, + load_districts, ) -st.markdown( - """""", - unsafe_allow_html=True, -) - - -@st.cache_data -def load_boundaries(): - with BOUNDARIES.open(encoding="utf-8") as f: - geo = json.load(f) - features = geo.get("features", []) - if len(features) != 6: - raise ValueError("Expected six council district polygons") - rows = [] - for feature in features: - props = feature["properties"] - number = int(props["district"]) - rows.append({"district": number, "population": int(props["population"])}) - return geo, pd.DataFrame(rows).sort_values("district").reset_index(drop=True) - - -def polygon_center(feature): - """Area-weighted polygon-ring centroid for 3D column positioning.""" - geometry = feature["geometry"] - polygon = ( - geometry["coordinates"][0] - if geometry["type"] == "Polygon" - else geometry["coordinates"][0][0] - ) - twice_area = 0.0 - sx = sy = 0.0 - for (x1, y1), (x2, y2) in zip(polygon, polygon[1:] + polygon[:1]): - cross = x1 * y2 - x2 * y1 - twice_area += cross - sx += (x1 + x2) * cross - sy += (y1 + y2) * cross - if abs(twice_area) > 1e-12: - return sx / (3 * twice_area), sy / (3 * twice_area) - return ( - sum(p[0] for p in polygon) / len(polygon), - sum(p[1] for p in polygon) / len(polygon), - ) +st.set_page_config(page_title="Mableton Communication Needs", layout="wide") -def load_metrics(): - if METRICS_CSV.exists(): - frame = pd.read_csv(METRICS_CSV) - required = ["district", *METRICS.values()] - missing = [name for name in required if name not in frame.columns] - if missing: - st.error("district_metrics.csv is missing columns: " + ", ".join(missing)) - st.stop() - frame = frame[required].copy() - for name in required: - frame[name] = pd.to_numeric(frame[name], errors="coerce") - if frame[required].isna().any().any() or frame["district"].duplicated().any(): - st.error("CSV has missing, nonnumeric, or duplicate district values.") - st.stop() - if not frame["district"].between(1, 6).all() or set(frame["district"]) != set( - range(1, 7) - ): - st.error("CSV must contain exactly one row for each district, 1 through 6.") - st.stop() - if not all(frame[c].between(0, 100).all() for c in METRICS.values()): - st.error("Demographic percentages must be between 0 and 100.") - st.stop() - return frame, False - # Fictional values ONLY to demonstrate the interface. Not Census estimates. - return pd.DataFrame( - { - "district": [1, 2, 3, 4, 5, 6], - "language_pct": [31, 22, 27, 18, 25, 34], - "age65_pct": [15, 19, 24, 21, 17, 13], - "no_internet_pct": [12, 16, 11, 20, 18, 14], - } - ), True +districts = load_districts() +boundaries = load_boundaries() +city = city_totals(districts) +AREAS = [CITY] + [area_name(d) for d in districts.index] -try: - geojson, population = load_boundaries() -except (OSError, ValueError, KeyError, json.JSONDecodeError) as exc: - st.error(f"Cannot read the official district boundary file: {exc}") - st.stop() +def pick_from_map(): + """Clicking a district on the map selects it, like the buttons above.""" + points = st.session_state["map"].selection.points + if points and "location" in points[0]: + st.session_state["area"] = area_name(int(points[0]["location"])) -rates, demo_mode = load_metrics() -df = population.merge(rates, on="district", how="left", validate="one_to_one") -if df[list(METRICS.values())].isna().any().any(): - st.error("Some districts are missing demographic data") - st.stop() -st.sidebar.markdown("### Map controls") -district = st.sidebar.selectbox( - "Council district", df["district"].tolist(), format_func=lambda x: f"District {x}" -) -metric_label = st.sidebar.radio("Color / column height", list(METRICS)) -map_style = st.sidebar.radio( - "Map display", ["District boundaries", "3D columns"], horizontal=False +st.title("Mableton Communication Needs") +st.markdown( + "Who might miss city news, and why? This shows where residents speak " + "other languages, are 65 or older, or have no internet at home, so outreach " + "can reach everyone." ) -metric = METRICS[metric_label] -selected = df.loc[df["district"] == district].iloc[0] -st.title("Mableton Communication-needs Map") -st.caption( - "Georgia 311 Challenge · Reach Every Resident · Six Mableton council districts" +area = st.segmented_control( + "Show numbers for", AREAS, default=CITY, required=True, key="area" ) -if demo_mode: - st.warning( - "DEMO DATA: Language, age 65+, and internet percentages are fictional placeholders. The district shapes and 2020 populations are real. Add data/district_metrics.csv to use prepared statistics." - ) -else: - st.info( - "Showing the team's prepared district_metrics.csv. Verify data source, year, denominator, and district aggregation before presenting figures as official." - ) - -st.subheader(f"District {district} overview") -a, b, c, d = st.columns(4) -a.metric("2020 population", f"{int(selected['population']):,}") -b.metric("Other language at home", f"{selected['language_pct']:.1f}%") -c.metric("Age 65+", f"{selected['age65_pct']:.1f}%") -d.metric("No internet", f"{selected['no_internet_pct']:.1f}%") - -st.subheader("District map") -st.caption( - "Choose a district in the sidebar. Hover over a district or column to inspect its information." -) - -# Attach all three metrics to each official district polygon, enabling tooltips. -for feature in geojson["features"]: - props = feature["properties"] - num = int(props["district"]) - item = df.loc[df["district"] == num].iloc[0] - props.update( - { - "district_name": f"District {num}", - "language_pct": float(item["language_pct"]), - "age65_pct": float(item["age65_pct"]), - "no_internet_pct": float(item["no_internet_pct"]), - "metric_value": float(item[metric]), - "fill_color": [37, 99, 235, 185] - if num == district - else [99, 102, 241, 65 + int(item[metric] * 3)], - } - ) +selected = None if area == CITY else int(area.removeprefix("District ")) +row = city if selected is None else districts.loc[selected] -# Map uses official GeoJSON geometry rather than approximate district markers. -polygon_layer = pdk.Layer( - "GeoJsonLayer", - data=geojson, - pickable=True, - auto_highlight=True, - filled=True, - stroked=True, - get_fill_color="properties.fill_color", - get_line_color=[255, 255, 255, 220], - get_line_width=120, - line_width_min_pixels=2, +# --- Headline numbers for the chosen area ------------------------------------------- +st.header(area, divider="blue") +st.markdown( + f"About **{row['population']:,.0f}** residents and **{row['households']:,.0f}** " + "households." ) -layers = [polygon_layer] -if map_style == "3D columns": - column_rows = [] - for feature in geojson["features"]: - props = feature["properties"] - lng, lat = polygon_center(feature) - column_rows.append( - { - "district": int(props["district"]), - "lng": lng, - "lat": lat, - "population": int(props["population"]), - "language_pct": props["language_pct"], - "age65_pct": props["age65_pct"], - "no_internet_pct": props["no_internet_pct"], - "metric_value": props["metric_value"], - "fill_color": [37, 99, 235, 230] - if props["district"] == district - else [224, 122, 57, 190], - } +for column, m in zip(st.columns(len(MEASURES)), MEASURES): + with column.container(border=True, height="stretch"): + delta = None + if selected is not None: + points = (row[m.rate] - city[m.rate]) * 100 + delta = f"{points:+.1f} points vs. all of Mableton" + st.markdown(f"**{m.title}**") + st.metric( + m.title, + f"{row[m.rate]:.1%}", + delta, + delta_color="off", + label_visibility="collapsed", ) - layers.append( - pdk.Layer( - "ColumnLayer", - data=pd.DataFrame(column_rows), - get_position="[lng, lat]", - get_elevation="metric_value", - elevation_scale=130, - radius=430, - get_fill_color="fill_color", - pickable=True, - auto_highlight=True, - extruded=True, + st.markdown( + f"{in_words(row[m.rate]).capitalize()} {m.base_label} {m.sentence} " + f"({row[m.count]:,.0f} of {row[m.base]:,.0f})." ) - ) - -view = pdk.ViewState( - latitude=33.82, - longitude=-84.57, - zoom=10.8, - pitch=52 if map_style == "3D columns" else 0, - bearing=20 if map_style == "3D columns" else 0, + st.caption(f"Why it matters: {m.why}") + +# --- Compare the districts ---------------------------------------------------------- +st.header("Compare the districts", divider="blue") +short = st.segmented_control( + "Measure", + [m.short for m in MEASURES], + default=MEASURES[0].short, + required=True, + key="measure", ) -tooltip = { - "html": "District {district}
Other language: {language_pct}%
Age 65+: {age65_pct}%
No internet: {no_internet_pct}%
2020 population: {population}", - "style": {"backgroundColor": "#172033", "color": "white"}, -} -st.pydeck_chart( - pdk.Deck( - layers=layers, - initial_view_state=view, - tooltip=tooltip, - map_style="https://basemaps.cartocdn.com/gl/positron-gl-style/style.json", - ), - width="stretch", - height=490, +measure = next(m for m in MEASURES if m.short == short) + +rates = districts[measure.rate] +st.markdown( + f"**{measure.title}:** highest in **District {rates.idxmax()}** " + f"({rates.max():.1%}), lowest in **District {rates.idxmin()}** ({rates.min():.1%}). " + f"Across Mableton it's {city[measure.rate]:.1%}." ) -left, right = st.columns([1.1, 1]) -with left: - st.subheader("Compare all districts") - chart = px.bar( - df, - x="district", - y=metric, - text_auto=".1f", - labels={"district": "Council district", metric: "Percent (%)"}, - color_discrete_sequence=[COLORS[metric_label]], - ) - chart.update_layout( - yaxis_range=[0, 100], showlegend=False, margin={"l": 0, "r": 0, "t": 10, "b": 0} - ) - st.plotly_chart(chart, width="stretch") -with right: - st.subheader(f"District {district}: three measures") - breakdown = pd.DataFrame( - { - "Measure": list(METRICS), - "Percent": [float(selected[col]) for col in METRICS.values()], - } - ) - fig = px.bar( - breakdown, - x="Percent", - y="Measure", - orientation="h", - text_auto=".1f", - color="Measure", - color_discrete_map=COLORS, +map_column, bar_column = st.columns([3, 2], gap="large") +with map_column: + st.plotly_chart( + district_map(districts, boundaries, measure, selected), + key="map", + on_select=pick_from_map, + selection_mode="points", + theme=None, + config={"displayModeBar": False, "scrollZoom": False}, ) - fig.update_layout( - xaxis_range=[0, 100], showlegend=False, margin={"l": 0, "r": 0, "t": 10, "b": 0} + st.caption("Darker districts have a higher share. Point at a district for details.") +with bar_column: + st.plotly_chart( + district_bars(districts, city[measure.rate], measure, selected), + theme=None, + config={"displayModeBar": False}, ) - st.plotly_chart(fig, width="stretch") -st.subheader("Possible outreach considerations") -notes = [] -if selected["language_pct"] >= 30: - notes.append( - "Explore multilingual notices and partnerships with trusted community organizations." +# --- Details -------------------------------------------------------------------------- +with st.expander("See all the numbers"): + table = districts.copy() + table.loc[CITY] = city + table.index = [area_name(d) if d != CITY else CITY for d in table.index] + columns = {"population": "Residents", "households": "Households"} + for m in MEASURES: + columns[m.rate] = f"{m.short} (%)" + columns[m.count] = f"{m.short} (count)" + table = table[list(columns)].rename(columns=columns) + st.dataframe( + table.style.format( + {c: "{:.1%}" if c.endswith("(%)") else "{:,.0f}" for c in table.columns} + ), + width="stretch", ) -if selected["age65_pct"] >= 20: - notes.append( - "Consider accessible print materials and outreach through senior/community centers." - ) -if selected["no_internet_pct"] >= 18: - notes.append( - "Include offline options such as mailed notices, flyers, and in-person announcements." - ) -if not notes: - notes.append( - "Consider combining digital updates with community partnerships and accessible print notices." - ) -for note in notes: - st.write("• " + note) -st.caption( - "These are illustrative suggestions, not measured outreach preferences. Thresholds are design rules, not research findings." -) -st.subheader("District data") -st.dataframe( - df.rename( - columns={ - "district": "District", - "population": "2020 population", - "language_pct": "Other language (%)", - "age65_pct": "Age 65+ (%)", - "no_internet_pct": "No internet (%)", - } - ), - hide_index=True, - width="stretch", -) -st.download_button( - "Download displayed data (CSV)", - data=df.to_csv(index=False), - file_name="mableton_district_dashboard_data.csv", - mime="text/csv", -) -st.caption( - "Boundary and 2020 population source: Mableton council district GeoJSON committed in the team's data/ directory." -) +with st.expander("Where these numbers come from"): + st.markdown( + """ +- **Source:** U.S. Census Bureau, American Community Survey 5-year estimates + (2020–2024). The survey asks a sample of homes, so every number is an estimate. +- **Districts:** the Census doesn't report by council district. Its small areas + (block groups) were split across districts by land area, which assumes people + are spread evenly within each one, so a district's totals can be off by up to + about 10%. +- **Language** counts residents age 5 and over. "Less than very well" is how + people described their own English. +- **No internet** means a household has no internet access at all, including + cell phone data. +""" + ) diff --git a/dashboard/__init__.py b/dashboard/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/dashboard/charts.py b/dashboard/charts.py new file mode 100644 index 0000000..b65f3dc --- /dev/null +++ b/dashboard/charts.py @@ -0,0 +1,218 @@ +"""The map and the district comparison chart (Plotly figures).""" + +import itertools + +import pandas as pd +import plotly.graph_objects as go + +from dashboard.data import Measure + +# One blue, light to dark: more of the measure is darker. +BLUES = ["#cde2fb", "#9ec5f4", "#6da7ec", "#3987e5", "#256abf", "#184f95"] +ACCENT = "#2a78d6" +MUTED = "#c3c2b7" +INK = "#0b0b0b" +INK_2 = "#52514e" +GRID = "#e1e0d9" +FONT = {"family": 'system-ui, -apple-system, "Segoe UI", sans-serif', "color": INK} + + +def _hover(measure: Measure) -> str: + return ( + "%{customdata[0]}
" + f"{measure.title}: %{{customdata[1]:.1%}}
" + f"%{{customdata[2]:,}} of %{{customdata[3]:,}} {measure.base_label}" + "" + ) + + +def _customdata(districts: pd.DataFrame, measure: Measure) -> list: + return [ + [f"District {d}", row[measure.rate], row[measure.count], row[measure.base]] + for d, row in districts.iterrows() + ] + + +def _percent_format(rates: pd.Series) -> str: + """Whole percents, or one decimal when the range is too narrow to tell ticks apart.""" + return ".1%" if rates.max() - rates.min() < 0.05 else ".0%" + + +def _rings(geometry: dict) -> list: + """The outer boundary of each polygon in a GeoJSON geometry.""" + if geometry["type"] == "Polygon": + return [geometry["coordinates"][0]] + return [polygon[0] for polygon in geometry["coordinates"]] + + +def _label_point(geometry: dict) -> tuple[float, float]: + """Center of the largest polygon (area-weighted centroid), as (lon, lat).""" + + def centroid(ring): + area = cx = cy = 0.0 + for (x0, y0), (x1, y1) in itertools.pairwise(ring): + cross = x0 * y1 - x1 * y0 + area += cross + cx += (x0 + x1) * cross + cy += (y0 + y1) * cross + return abs(area), cx / (3 * area), cy / (3 * area) + + _, lon, lat = max(centroid(ring) for ring in _rings(geometry)) + return lon, lat + + +def district_map( + districts: pd.DataFrame, boundaries: dict, measure: Measure, selected: int | None +) -> go.Figure: + fig = go.Figure( + go.Choroplethmap( + geojson=boundaries, + featureidkey="properties.district", + locations=districts.index, + z=districts[measure.rate], + colorscale=[[i / (len(BLUES) - 1), c] for i, c in enumerate(BLUES)], + marker={"opacity": 0.85, "line": {"color": "white", "width": 1.5}}, + customdata=_customdata(districts, measure), + hovertemplate=_hover(measure), + colorbar={ + "tickformat": _percent_format(districts[measure.rate]), + "thickness": 12, + "len": 0.7, + "outlinewidth": 0, + "title": {"text": measure.short, "side": "right", "font": FONT}, + "tickfont": FONT, + }, + ) + ) + features = {f["properties"]["district"]: f for f in boundaries["features"]} + + if selected is not None: + lons, lats = [], [] + for ring in _rings(features[selected]["geometry"]): + lons += [x for x, _ in ring] + [None] + lats += [y for _, y in ring] + [None] + fig.add_trace( + go.Scattermap( + lon=lons, + lat=lats, + mode="lines", + line={"color": INK, "width": 3}, + hoverinfo="skip", + ) + ) + + # A white badge with the district number in the middle of each district. + points = [_label_point(features[d]["geometry"]) for d in districts.index] + fig.add_trace( + go.Scattermap( + lon=[lon for lon, _ in points], + lat=[lat for _, lat in points], + mode="markers+text", + text=[str(d) for d in districts.index], + marker={"size": 24, "color": "white"}, + textfont={"size": 13, "color": INK, "weight": "bold"}, + hoverinfo="skip", + ) + ) + + all_lons = [ + x for f in boundaries["features"] for r in _rings(f["geometry"]) for x, _ in r + ] + all_lats = [ + y for f in boundaries["features"] for r in _rings(f["geometry"]) for _, y in r + ] + center = { + "lon": (min(all_lons) + max(all_lons)) / 2, + "lat": (min(all_lats) + max(all_lats)) / 2, + } + zoom = 10.75 + fig.update_layout( + map={"style": "carto-positron", "center": center, "zoom": zoom}, + # A button on the map that puts it back where it started. + updatemenus=[ + { + "type": "buttons", + "showactive": False, + "buttons": [ + { + "label": "⟲ Recenter map", + "method": "relayout", + "args": [{"map.center": center, "map.zoom": zoom}], + } + ], + "x": 0.01, + "y": 0.99, + "xanchor": "left", + "yanchor": "top", + "pad": {"l": 4, "t": 4}, + "bgcolor": "white", + "bordercolor": MUTED, + "font": {**FONT, "size": 13}, + } + ], + margin={"l": 0, "r": 0, "t": 0, "b": 0}, + height=480, + showlegend=False, + font=FONT, + paper_bgcolor="rgba(0,0,0,0)", + ) + return fig + + +def district_bars( + districts: pd.DataFrame, city_rate: float, measure: Measure, selected: int | None +) -> go.Figure: + """Each district's share side by side, with the selected one highlighted.""" + colors = [ + ACCENT if selected is None or d == selected else MUTED for d in districts.index + ] + rates = districts[measure.rate] + fig = go.Figure( + go.Bar( + y=[f"District {d}" for d in districts.index], + x=rates, + orientation="h", + marker={"color": colors, "line": {"width": 0}}, + text=[f"{r:.1%}" for r in rates], + textposition="outside", + textfont={"color": INK, "size": 13}, + cliponaxis=False, + customdata=_customdata(districts, measure), + hovertemplate=_hover(measure), + ) + ) + fig.add_vline( + x=city_rate, + line={"color": INK_2, "width": 1.5, "dash": "dash"}, + annotation={ + "text": f"Mableton overall: {city_rate:.1%}", + "font": {"color": INK_2, "size": 12}, + "yanchor": "bottom", + }, + annotation_position="top", + ) + fig.update_layout( + height=480, + margin={"l": 8, "r": 16, "t": 36, "b": 40}, + bargap=0.45, + barcornerradius=4, + font=FONT, + plot_bgcolor="rgba(0,0,0,0)", + paper_bgcolor="rgba(0,0,0,0)", + xaxis={ + "tickformat": ".0%", + "range": [0, rates.max() * 1.25], + "gridcolor": GRID, + "zeroline": True, + "zerolinecolor": MUTED, + "tickfont": {"color": INK_2}, + }, + yaxis={ + "autorange": "reversed", + "automargin": True, + "ticksuffix": " ", + "tickfont": {"size": 14}, + }, + hoverlabel={"bgcolor": "white", "font": FONT}, + ) + return fig diff --git a/dashboard/data.py b/dashboard/data.py new file mode 100644 index 0000000..49fc285 --- /dev/null +++ b/dashboard/data.py @@ -0,0 +1,103 @@ +"""Loads the committed data and describes each measure in plain language.""" + +import json +from dataclasses import dataclass +from pathlib import Path + +import pandas as pd + +DATA = Path(__file__).parent.parent / "data" +CITY = "All of Mableton" + + +@dataclass(frozen=True) +class Measure: + title: str # what the share means, as a heading + short: str # a few words, for buttons and axis titles + count: str # column with the number of people or homes + base: str # column with the number it's a share of + base_label: str # what `base` counts, in words + rate: str # column with the share, 0 to 1 + sentence: str # finishes "About 3 in 10 residents ..." + why: str # why it matters for reaching residents + + +MEASURES = [ + Measure( + title="Speak a language other than English at home", + short="Other language at home", + count="non_english", + base="population_5_plus", + base_label="residents age 5 and over", + rate="non_english_pct", + sentence="speak a language other than English at home", + why="City news may need to go out in more than one language.", + ), + Measure( + title="Speak English less than “very well”", + short="Limited English", + count="limited_english", + base="population_5_plus", + base_label="residents age 5 and over", + rate="limited_english_pct", + sentence="speak English less than “very well”", + why="These residents may need translated materials or an interpreter.", + ), + Measure( + title="Age 65 and over", + short="Age 65+", + count="age_65_plus", + base="population", + base_label="residents", + rate="age_65_plus_pct", + sentence="are age 65 or older", + why="Older residents often rely on mail, phone calls and in-person events.", + ), + Measure( + title="Homes with no internet access", + short="No internet at home", + count="households_no_internet", + base="households", + base_label="households", + rate="no_internet_pct", + sentence="have no internet access at home", + why="These homes won't see website or social media posts.", + ), +] + +COUNTS = [ + "population", + "population_5_plus", + "households", + *dict.fromkeys(m.count for m in MEASURES), +] + + +def load_districts() -> pd.DataFrame: + """One row per district (1–6), from data/district-needs.csv.""" + return pd.read_csv(DATA / "district-needs.csv").set_index("district") + + +def city_totals(districts: pd.DataFrame) -> pd.Series: + """All six districts together: summed counts, with shares recomputed from them.""" + totals = districts[COUNTS].sum() + for m in MEASURES: + totals[m.rate] = totals[m.count] / totals[m.base] + return totals + + +def load_boundaries() -> dict: + return json.loads( + (DATA / "mableton-council-districts.geojson").read_text(encoding="utf-8") + ) + + +def area_name(district: int | None) -> str: + return CITY if district is None else f"District {district}" + + +def in_words(share: float) -> str: + """A share as a phrase people can picture, like "about 3 in 10" or "about 4 in 100".""" + if share >= 0.095: + return f"about {round(share * 10)} in 10" + return f"about {max(round(share * 100), 1)} in 100" diff --git a/scripts/build_site.py b/scripts/build_site.py index b09c78c..df25bd7 100644 --- a/scripts/build_site.py +++ b/scripts/build_site.py @@ -27,6 +27,9 @@ shutil.rmtree(SITE, ignore_errors=True) shutil.copytree(ROOT / "data", SITE / "data") shutil.copy(ROOT / "app.py", SITE / "app.py") +shutil.copytree( + ROOT / "dashboard", SITE / "dashboard", ignore=shutil.ignore_patterns("__pycache__") +) if (ROOT / ".streamlit" / "config.toml").exists(): shutil.copytree( ROOT / ".streamlit", From b30ce2681a4973a77a764cd842d40719710a95d6 Mon Sep 17 00:00:00 2001 From: Evan Murray Date: Thu, 29 Oct 2026 17:26:53 -0400 Subject: [PATCH 2/3] Add themes and dark mode --- .streamlit/config.toml | 3 +- app.py | 33 ++++++++--- dashboard/charts.py | 72 +++++++++++++---------- dashboard/theme.py | 130 +++++++++++++++++++++++++++++++++++++++++ 4 files changed, 198 insertions(+), 40 deletions(-) create mode 100644 dashboard/theme.py diff --git a/.streamlit/config.toml b/.streamlit/config.toml index 8c2ec47..d38e307 100644 --- a/.streamlit/config.toml +++ b/.streamlit/config.toml @@ -1,6 +1,7 @@ [theme] base = "light" -primaryColor = "#2a78d6" +primaryColor = "#297e47" +greenColor = "#297e47" backgroundColor = "#f9f9f7" secondaryBackgroundColor = "#f0efec" textColor = "#0b0b0b" diff --git a/app.py b/app.py index 227d8ce..8708392 100644 --- a/app.py +++ b/app.py @@ -2,7 +2,8 @@ It reads only files committed in data/, so it needs no keys or secrets to run. Fetching and preparing data happens in backend/ and scripts/, ahead of time. -The pieces live in dashboard/: data.py (loading, measure wording) and charts.py (figures). +The pieces live in dashboard/: data.py (loading, measure wording), charts.py (figures) +and theme.py (color schemes, dark mode). """ import streamlit as st @@ -17,6 +18,7 @@ load_boundaries, load_districts, ) +from dashboard.theme import SCHEMES, apply, palette st.set_page_config(page_title="Mableton Communication Needs", layout="wide") @@ -33,7 +35,21 @@ def pick_from_map(): st.session_state["area"] = area_name(int(points[0]["location"])) -st.title("Mableton Communication Needs") +title_column, settings_column = st.columns([3, 2], vertical_alignment="center") +with settings_column.container( + horizontal=True, + horizontal_alignment="right", + vertical_alignment="center", + gap="medium", +): + dark = st.toggle("Dark mode", key="dark", width="content") + scheme = st.selectbox( + "Colors", list(SCHEMES), key="scheme", label_visibility="collapsed", width=170 + ) +p = palette(dark, scheme) +apply(p) + +title_column.title("Mableton Communication Needs") st.markdown( "Who might miss city news, and why? This shows where residents speak " "other languages, are 65 or older, or have no internet at home, so outreach " @@ -47,7 +63,7 @@ def pick_from_map(): row = city if selected is None else districts.loc[selected] # --- Headline numbers for the chosen area ------------------------------------------- -st.header(area, divider="blue") +st.header(area, divider=p.divider) st.markdown( f"About **{row['population']:,.0f}** residents and **{row['households']:,.0f}** " "households." @@ -74,7 +90,7 @@ def pick_from_map(): st.caption(f"Why it matters: {m.why}") # --- Compare the districts ---------------------------------------------------------- -st.header("Compare the districts", divider="blue") +st.header("Compare the districts", divider=p.divider) short = st.segmented_control( "Measure", [m.short for m in MEASURES], @@ -94,17 +110,20 @@ def pick_from_map(): map_column, bar_column = st.columns([3, 2], gap="large") with map_column: st.plotly_chart( - district_map(districts, boundaries, measure, selected), + district_map(districts, boundaries, measure, selected, p), key="map", on_select=pick_from_map, selection_mode="points", theme=None, config={"displayModeBar": False, "scrollZoom": False}, ) - st.caption("Darker districts have a higher share. Point at a district for details.") + shade = "Brighter" if p.dark else "Darker" + st.caption( + f"{shade} districts have a higher share. Point at a district for details." + ) with bar_column: st.plotly_chart( - district_bars(districts, city[measure.rate], measure, selected), + district_bars(districts, city[measure.rate], measure, selected, p), theme=None, config={"displayModeBar": False}, ) diff --git a/dashboard/charts.py b/dashboard/charts.py index b65f3dc..a1d14fd 100644 --- a/dashboard/charts.py +++ b/dashboard/charts.py @@ -6,15 +6,13 @@ import plotly.graph_objects as go from dashboard.data import Measure +from dashboard.theme import Palette -# One blue, light to dark: more of the measure is darker. -BLUES = ["#cde2fb", "#9ec5f4", "#6da7ec", "#3987e5", "#256abf", "#184f95"] -ACCENT = "#2a78d6" -MUTED = "#c3c2b7" -INK = "#0b0b0b" -INK_2 = "#52514e" -GRID = "#e1e0d9" -FONT = {"family": 'system-ui, -apple-system, "Segoe UI", sans-serif', "color": INK} +FAMILY = 'system-ui, -apple-system, "Segoe UI", sans-serif' + + +def _font(p: Palette, **extra) -> dict: + return {"family": FAMILY, "color": p.ink, **extra} def _hover(measure: Measure) -> str: @@ -62,7 +60,11 @@ def centroid(ring): def district_map( - districts: pd.DataFrame, boundaries: dict, measure: Measure, selected: int | None + districts: pd.DataFrame, + boundaries: dict, + measure: Measure, + selected: int | None, + p: Palette, ) -> go.Figure: fig = go.Figure( go.Choroplethmap( @@ -70,8 +72,8 @@ def district_map( featureidkey="properties.district", locations=districts.index, z=districts[measure.rate], - colorscale=[[i / (len(BLUES) - 1), c] for i, c in enumerate(BLUES)], - marker={"opacity": 0.85, "line": {"color": "white", "width": 1.5}}, + colorscale=[[i / (len(p.ramp) - 1), c] for i, c in enumerate(p.ramp)], + marker={"opacity": 0.85, "line": {"color": p.page, "width": 1.5}}, customdata=_customdata(districts, measure), hovertemplate=_hover(measure), colorbar={ @@ -79,8 +81,8 @@ def district_map( "thickness": 12, "len": 0.7, "outlinewidth": 0, - "title": {"text": measure.short, "side": "right", "font": FONT}, - "tickfont": FONT, + "title": {"text": measure.short, "side": "right", "font": _font(p)}, + "tickfont": _font(p), }, ) ) @@ -96,12 +98,13 @@ def district_map( lon=lons, lat=lats, mode="lines", - line={"color": INK, "width": 3}, + line={"color": p.ink, "width": 3}, hoverinfo="skip", ) ) - # A white badge with the district number in the middle of each district. + # A white badge with the district number in the middle of each district (white in + # both modes, so it reads on any fill). points = [_label_point(features[d]["geometry"]) for d in districts.index] fig.add_trace( go.Scattermap( @@ -110,7 +113,7 @@ def district_map( mode="markers+text", text=[str(d) for d in districts.index], marker={"size": 24, "color": "white"}, - textfont={"size": 13, "color": INK, "weight": "bold"}, + textfont={"size": 13, "color": "#0b0b0b", "weight": "bold"}, hoverinfo="skip", ) ) @@ -127,7 +130,7 @@ def district_map( } zoom = 10.75 fig.update_layout( - map={"style": "carto-positron", "center": center, "zoom": zoom}, + map={"style": p.basemap, "center": center, "zoom": zoom}, # A button on the map that puts it back where it started. updatemenus=[ { @@ -145,26 +148,31 @@ def district_map( "xanchor": "left", "yanchor": "top", "pad": {"l": 4, "t": 4}, - "bgcolor": "white", - "bordercolor": MUTED, - "font": {**FONT, "size": 13}, + "bgcolor": p.surface, + "bordercolor": p.muted, + "font": _font(p, size=13), } ], margin={"l": 0, "r": 0, "t": 0, "b": 0}, height=480, showlegend=False, - font=FONT, + font=_font(p), paper_bgcolor="rgba(0,0,0,0)", ) return fig def district_bars( - districts: pd.DataFrame, city_rate: float, measure: Measure, selected: int | None + districts: pd.DataFrame, + city_rate: float, + measure: Measure, + selected: int | None, + p: Palette, ) -> go.Figure: """Each district's share side by side, with the selected one highlighted.""" colors = [ - ACCENT if selected is None or d == selected else MUTED for d in districts.index + p.accent if selected is None or d == selected else p.muted + for d in districts.index ] rates = districts[measure.rate] fig = go.Figure( @@ -175,7 +183,7 @@ def district_bars( marker={"color": colors, "line": {"width": 0}}, text=[f"{r:.1%}" for r in rates], textposition="outside", - textfont={"color": INK, "size": 13}, + textfont=_font(p, size=13), cliponaxis=False, customdata=_customdata(districts, measure), hovertemplate=_hover(measure), @@ -183,10 +191,10 @@ def district_bars( ) fig.add_vline( x=city_rate, - line={"color": INK_2, "width": 1.5, "dash": "dash"}, + line={"color": p.ink_2, "width": 1.5, "dash": "dash"}, annotation={ "text": f"Mableton overall: {city_rate:.1%}", - "font": {"color": INK_2, "size": 12}, + "font": _font(p, color=p.ink_2, size=12), "yanchor": "bottom", }, annotation_position="top", @@ -196,23 +204,23 @@ def district_bars( margin={"l": 8, "r": 16, "t": 36, "b": 40}, bargap=0.45, barcornerradius=4, - font=FONT, + font=_font(p), plot_bgcolor="rgba(0,0,0,0)", paper_bgcolor="rgba(0,0,0,0)", xaxis={ "tickformat": ".0%", "range": [0, rates.max() * 1.25], - "gridcolor": GRID, + "gridcolor": p.grid, "zeroline": True, - "zerolinecolor": MUTED, - "tickfont": {"color": INK_2}, + "zerolinecolor": p.muted, + "tickfont": {"color": p.ink_2}, }, yaxis={ "autorange": "reversed", "automargin": True, "ticksuffix": " ", - "tickfont": {"size": 14}, + "tickfont": _font(p, size=14), }, - hoverlabel={"bgcolor": "white", "font": FONT}, + hoverlabel={"bgcolor": p.surface, "font": _font(p)}, ) return fig diff --git a/dashboard/theme.py b/dashboard/theme.py new file mode 100644 index 0000000..4562309 --- /dev/null +++ b/dashboard/theme.py @@ -0,0 +1,130 @@ +"""Color schemes and light/dark mode, for the page (Streamlit's theme) and the charts.""" + +from dataclasses import dataclass + +import streamlit as st +from streamlit import config + + +def _ramp(low: str, mid: str, high: str, steps: int = 6) -> list[str]: + """Evenly spaced colors from low through mid to high (for "less" to "more").""" + + def rgb(hex_color): + return [int(hex_color[i : i + 2], 16) for i in (1, 3, 5)] + + def mix(a, b, t): + return "#" + "".join(f"{round(x + (y - x) * t):02x}" for x, y in zip(a, b)) + + a, b, c = rgb(low), rgb(mid), rgb(high) + colors = [] + for i in range(steps): + t = 2 * i / (steps - 1) + colors.append(mix(a, b, t) if t <= 1 else mix(b, c, t - 1)) + return colors + + +@dataclass(frozen=True) +class Scheme: + divider: str # Streamlit's name for the closest heading-underline color + light_accent: str + light_ramp: tuple[str, str, str] # low, middle, high on a light map + dark_accent: str + dark_ramp: tuple[str, str, str] # low, middle, high on a dark map + + +SCHEMES = { + # The city's brand green, #297e47, with lighter and darker steps of the same hue. + "Mableton green": Scheme( + divider="green", + light_accent="#297e47", + light_ramp=("#ddefe3", "#297e47", "#0f3a20"), + dark_accent="#3fa866", # the brand green lifted so it reads on a dark page + dark_ramp=("#1b4229", "#297e47", "#a3d9b5"), + ), + "Blue": Scheme( + divider="blue", + light_accent="#2a78d6", + light_ramp=("#cde2fb", "#3987e5", "#104281"), + dark_accent="#3987e5", + dark_ramp=("#163a66", "#3987e5", "#b7d3f6"), + ), + "Purple": Scheme( + divider="violet", + light_accent="#6250d6", + light_ramp=("#e6e2fb", "#7a6ae0", "#2e2380"), + dark_accent="#9085e9", + dark_ramp=("#2f2766", "#7a6ae0", "#d3cdf8"), + ), +} + + +@dataclass(frozen=True) +class Palette: + dark: bool + divider: str + accent: str # the selected district, buttons + ramp: list[str] # map colors, less to more + page: str + raised: str # widget and card backgrounds + surface: str # tooltips and the map's button + ink: str + ink_2: str + muted: str # unselected bars, borders + grid: str + basemap: str + + +def palette(dark: bool, scheme_name: str) -> Palette: + scheme = SCHEMES[scheme_name] + if dark: + return Palette( + dark=True, + divider=scheme.divider, + accent=scheme.dark_accent, + ramp=_ramp(*scheme.dark_ramp), + page="#121211", + raised="#1f1f1d", + surface="#262624", + ink="#f0efec", + ink_2="#c3c2b7", + muted="#4a4944", + grid="#2c2c2a", + basemap="carto-darkmatter", + ) + return Palette( + dark=False, + divider=scheme.divider, + accent=scheme.light_accent, + ramp=_ramp(*scheme.light_ramp), + page="#f9f9f7", + raised="#f0efec", + surface="#ffffff", + ink="#0b0b0b", + ink_2="#52514e", + muted="#c3c2b7", + grid="#e1e0d9", + basemap="carto-positron", + ) + + +def apply(p: Palette) -> None: + """Points Streamlit's theme at this palette. + + Streamlit only has one theme setting per server, which it sends to the browser at the + start of each run. So if it isn't this visitor's choice yet, set it and run again. + (On Firebase each visitor has their own in-browser server; on a shared server a visitor + may get one extra rerun after someone else changes it.) + """ + wanted = { + "theme.base": "dark" if p.dark else "light", + "theme.primaryColor": p.accent, + "theme.backgroundColor": p.page, + "theme.secondaryBackgroundColor": p.raised, + "theme.textColor": p.ink, + # Heading underlines use a named color; make that name the scheme's accent. + f"theme.{p.divider}Color": p.accent, + } + if any(config.get_option(key) != value for key, value in wanted.items()): + for key, value in wanted.items(): + config.set_option(key, value) + st.rerun() From 8baa3b5113965924a76b0c8f2a3588a85ca17408 Mon Sep 17 00:00:00 2001 From: Evan Murray Date: Thu, 29 Oct 2026 17:27:00 -0400 Subject: [PATCH 3/3] Add frontend tests --- tests/test_app.py | 24 +++++++++++++++++++++++- 1 file changed, 23 insertions(+), 1 deletion(-) diff --git a/tests/test_app.py b/tests/test_app.py index 2112943..5481ac8 100644 --- a/tests/test_app.py +++ b/tests/test_app.py @@ -6,5 +6,27 @@ def test_app_runs(): - app = AppTest.from_file(APP, default_timeout=30).run() + app = AppTest.from_file(APP).run() + assert not app.exception + + +def test_every_area_and_measure(): + app = AppTest.from_file(APP).run() + for area in ["District 1", "District 6", "All of Mableton"]: + app.button_group(key="area").set_value(area).run() + assert not app.exception + assert app.header[0].value == area + for measure in ["Limited English", "Age 65+", "No internet at home"]: + app.button_group(key="measure").set_value(measure).run() + assert not app.exception + + +def test_dark_mode_and_color_schemes(): + app = AppTest.from_file(APP).run() + app.toggle(key="dark").set_value(True).run() + assert not app.exception + for scheme in ["Blue", "Purple", "Mableton green"]: + app.selectbox(key="scheme").set_value(scheme).run() + assert not app.exception + app.toggle(key="dark").set_value(False).run() assert not app.exception