#!/usr/bin/env python3 # SPDX-License-Identifier: MIT # Copyright (c) 2026 Canopulse # Licensed under the MIT License. The full text is in LICENSE.md in this package. """Score California UCRI CA_2026.10 from tract-level input tables. Standard library only (Python 3.8+, no numpy or pandas). Canopulse, 2026. This is the scoring logic that produced the released values in ucri_ca_2026_10_tracts.csv, with every input path taken from the command line. In the release the logic ran in two places, and this script keeps the two steps apart: Step 1, component percentiles (Canopulse's pipeline scoring script, written with pandas; translated here to the standard library with identical results): Tracts that are water-only (land area 0 and water area above 0) are left out. For every other tract the raw values are CDS raw = 100 minus mean tree canopy cover (%) HES raw = mean summer land-surface temperature (degrees F) ISS raw = mean fractional impervious surface (%) SVS raw = CDC/ATSDR SVI 2022 overall percentile RPL_THEMES (0 to 1; -999 means missing) and each is ranked statewide: percentile = average rank / n * 100, where ties share the average of the ranks they span and n is the number of non-water tracts with a value for that layer (pandas Series.rank(pct=True, method="average") * 100). Each percentile is then rounded to one decimal the way pandas Series.round(1) does it (the value times 10 is rounded half to even, then divided by 10). The raw canopy, impervious and temperature values are rounded the same way for output. Step 2, release assembly (Canopulse's release builder, written in JavaScript; translated here): EBS = CalEnviroScreen 5.0 PollutionP for the same 2020 tract GEOID, rounded half up to one decimal. It is OEHHA's published percentile and is not re-ranked. Score kind: "frozen" (fully scored) when all five components are present, "none" when none is, "provisional" otherwise. UCRI = 0.25 CDS + 0.25 HES + 0.15 ISS + 0.20 SVS + 0.15 EBS, using the rounded components, added left to right in that order, rounded half up to one decimal. Fully scored tracts only. Provisional estimate = (sum of available weighted components) / (sum of available weights), rounded half up to one decimal. Thresholds = 20th, 40th, 60th and 80th percentiles of the fully scored UCRI values (linear interpolation between closest ranks), rounded half up to one decimal. A fully scored tract takes the highest class whose threshold its UCRI meets or exceeds: Very Low, Low, Moderate, High, Extreme (stored values; Canopulse displays Extreme as "Very high screening priority"). Ranks: fully scored tracts by UCRI descending, ties by GEOID ascending, statewide, within each county, and within each place part (a place that spans two counties is ranked separately in each). Position percentile within the group = (rank minus 1) / (n minus 1) * 100, rounded half up to one decimal (0 when the group has one tract). Confidence label: "Moderate" for fully scored tracts, "Insufficient" for the rest. "Rounded half up" means JavaScript Math.round((x + Number.EPSILON) * 10) / 10. Inputs (CSV files with a header row; GEOID is the 11-digit 2020 tract code): --tracts the 2020 tract list: GEOID plus is_water_only (True/False), or GEOID plus TIGER/Line ALAND and AWATER (or aland_m2 and awater_m2), from which water-only is derived. Every row is scored; tracts missing from the other tables get no value for that layer. --canopy GEOID, canopy_pct: tract mean NLCD Tree Canopy Cover 2025. --impervious GEOID, impervious_pct: tract mean Annual NLCD Fractional Impervious Surface 2025. --lst GEOID, lst_mean_F: tract mean of the summer 2026 Landsat 8/9 land-surface temperature composite, degrees F. --svi the CDC/ATSDR SVI 2022 California tract CSV (FIPS, RPL_THEMES), or any table with GEOID and RPL_THEMES. --ces the CalEnviroScreen 5.0 CSV published by OEHHA (tract, PollutionP). --places optional: GEOID, placeFips (blank when the tract is assigned to no place). Needed only for place ranks. The canopy, impervious and land-surface temperature tables are tract summaries of raster layers. They come from Canopulse's raster pipeline, which is not published, and they are not in this package (the CSV in this package carries those raw values rounded to 0.1, which is not enough to rerun step 1 exactly). METHOD.md section 2 describes how they were made. reproduce.py is the check that runs on this package alone. Usage: python3 compute_ucri.py --tracts tracts.csv --canopy canopy.csv \\ --impervious impervious.csv --lst lst.csv --svi SVI_2022_California.csv \\ --ces calenviroscreen50.csv [--places places.csv] [--out ucri_computed.csv] \\ [--check ucri_ca_2026_10_tracts.csv] --out writes one row per tract. --check compares the result with a released tract CSV column by column and exits with code 1 on any difference. """ import argparse import csv import math import re import sys WEIGHTS = {"cds": 0.25, "hes": 0.25, "iss": 0.15, "svs": 0.20, "ebs": 0.15} COMPONENTS = list(WEIGHTS) CLASSES = (("Low", 0.2), ("Moderate", 0.4), ("High", 0.6), ("Extreme", 0.8)) EPSILON = 2.220446049250313e-16 # JavaScript Number.EPSILON # Strings pandas.read_csv reads as missing by default. NA_STRINGS = {"", "#N/A", "#N/A N/A", "#NA", "-1.#IND", "-1.#QNAN", "-NaN", "-nan", "1.#IND", "1.#QNAN", "", "N/A", "NA", "NULL", "NaN", "None", "n/a", "nan", "null"} OUTPUT_COLUMNS = [ "geoid", "score_kind", "cds", "hes", "iss", "svs", "ebs", "ucri", "ucri_provisional", "priority", "confidence", "state_rank", "state_pctl", "county_rank", "county_pctl", "place_rank", "place_pctl", "canopy_pct", "summer_lst_f", "impervious_pct", "cdc_svi_rpl_themes", "ces5_pollution_burden_pctl", ] # ---------------------------------------------------------------- helpers def js_round(y): """JavaScript Math.round: nearest integer, halves toward +infinity.""" r = math.floor(y) return r + 1 if y - r >= 0.5 else r def round_half_up(value): """The release builder's rounding: Math.round((x + Number.EPSILON) * 10) / 10.""" return js_round((value + EPSILON) * 10) / 10 def round_pandas(value): """pandas Series.round(1) (numpy.around): round(x * 10) half to even, / 10.""" return round(value * 10) / 10 def number(text): text = (text or "").strip() return None if text in NA_STRINGS else float(text) def geoid_of(text): digits = re.sub(r"\D", "", (text or "").strip()) if not digits: return None return digits.zfill(11) def read_table(path, id_columns): with open(path, newline="", encoding="utf-8-sig") as handle: rows = list(csv.DictReader(handle)) if not rows: raise SystemExit(f"{path}: no rows") id_column = next((c for c in id_columns if c in rows[0]), None) if id_column is None: raise SystemExit(f"{path}: needs one of the columns {', '.join(id_columns)}") table = {} for row in rows: geoid = geoid_of(row[id_column]) if geoid is None: continue if geoid in table: raise SystemExit(f"{path}: duplicate tract {geoid}") table[geoid] = row return table def column(table, path, name): first = next(iter(table.values())) if name not in first: raise SystemExit(f"{path}: missing column {name}") return {geoid: number(row[name]) for geoid, row in table.items()} def is_true(text): return (text or "").strip().lower() in ("true", "1", "yes") def average_rank_percentile(values): """{key: value or None} -> {key: average rank / n * 100} over non-missing values.""" items = sorted((v, k) for k, v in values.items() if v is not None) n = len(items) out = {} i = 0 while i < n: j = i while j + 1 < n and items[j + 1][0] == items[i][0]: j += 1 rank_sum = 0.0 for position in range(i, j + 1): rank_sum += position + 1 average_rank = rank_sum / (j - i + 1) for position in range(i, j + 1): out[items[position][1]] = average_rank / n * 100 i = j + 1 return out def quantile(sorted_values, q): """Linear interpolation between closest ranks (numpy and pandas default).""" index = (len(sorted_values) - 1) * q lower, upper = math.floor(index), math.ceil(index) return sorted_values[lower] + (sorted_values[upper] - sorted_values[lower]) * (index - lower) def priority_for(score, thresholds): for label in ("Extreme", "High", "Moderate", "Low"): if score >= thresholds[label]: return label return "Very Low" def normalize_place(value): """The release builder's place code rule: digits only, 1 to 5 of them, zero padded.""" if value is None: return None digits = re.sub(r"\D", "", re.sub(r"\.0$", "", value.strip())) return digits.zfill(5) if 1 <= len(digits) <= 5 else None def assign_ranks(records, group_of, rank_key, pctl_key): groups = {} for record in records: if record["score_kind"] != "frozen": continue key = group_of(record) if key is None: continue groups.setdefault(key, []).append(record) for group in groups.values(): group.sort(key=lambda r: (-r["ucri"], r["geoid"])) for index, record in enumerate(group): record[rank_key] = index + 1 record[pctl_key] = 0 if len(group) == 1 else round_half_up(index / (len(group) - 1) * 100) # ---------------------------------------------------------------- scoring def load_inputs(args): tracts = read_table(args.tracts, ("GEOID",)) first = next(iter(tracts.values())) if "is_water_only" in first: water = {g: is_true(r["is_water_only"]) for g, r in tracts.items()} else: land_col = "ALAND" if "ALAND" in first else "aland_m2" water_col = "AWATER" if "AWATER" in first else "awater_m2" if land_col not in first or water_col not in first: raise SystemExit(f"{args.tracts}: needs is_water_only, or ALAND and AWATER") water = {} for g, r in tracts.items(): land, area = number(r[land_col]), number(r[water_col]) water[g] = land == 0 and area is not None and area > 0 canopy = column(read_table(args.canopy, ("GEOID",)), args.canopy, "canopy_pct") imperv = column(read_table(args.impervious, ("GEOID",)), args.impervious, "impervious_pct") lst = column(read_table(args.lst, ("GEOID",)), args.lst, "lst_mean_F") svi = column(read_table(args.svi, ("GEOID", "FIPS")), args.svi, "RPL_THEMES") svi = {g: (None if v is None or v == -999 else v) for g, v in svi.items()} ces_table = read_table(args.ces, ("tract",)) ces = column(ces_table, args.ces, "PollutionP") for geoid, value in ces.items(): if not re.fullmatch(r"06\d{9}", geoid): raise SystemExit(f"{args.ces}: invalid tract identifier {geoid}") if value is None or not 0 <= value <= 100: raise SystemExit(f"{args.ces}: invalid PollutionP for {geoid}") places = {} if args.places: place_table = read_table(args.places, ("GEOID",)) if "placeFips" not in next(iter(place_table.values())): raise SystemExit(f"{args.places}: missing column placeFips") places = {g: (r["placeFips"].strip() or None) for g, r in place_table.items()} return sorted(tracts), water, canopy, imperv, lst, svi, ces, places def score(args): geoids, water, canopy, imperv, lst, svi, ces, places = load_inputs(args) # Step 1: statewide percentile ranks over non-water tracts. land = [g for g in geoids if not water[g]] raw = { "cds": {g: (None if canopy.get(g) is None else 100.0 - canopy[g]) for g in land}, "hes": {g: lst.get(g) for g in land}, "iss": {g: imperv.get(g) for g in land}, "svs": {g: svi.get(g) for g in land}, } pct = {c: average_rank_percentile(values) for c, values in raw.items()} records = [] for g in geoids: comp = {c: (round_pandas(pct[c][g]) if g in pct[c] else None) for c in ("cds", "hes", "iss", "svs")} # Step 2: release assembly. comp["ebs"] = round_half_up(ces[g]) if g in ces else None available = [c for c in COMPONENTS if comp[c] is not None] kind = "frozen" if len(available) == 5 else "none" if not available else "provisional" weighted = 0.0 weight = 0.0 for c in available: weighted += comp[c] * WEIGHTS[c] for c in available: weight += WEIGHTS[c] record = {"geoid": g, "score_kind": kind, **comp, "ucri": round_half_up(weighted) if kind == "frozen" else None, "ucri_provisional": round_half_up(weighted / weight) if kind == "provisional" else None, "priority": "", "confidence": "Moderate" if kind == "frozen" else "Insufficient", "state_rank": None, "state_pctl": None, "county_rank": None, "county_pctl": None, "place_rank": None, "place_pctl": None, "canopy_pct": None if canopy.get(g) is None else round_pandas(canopy[g]), "summer_lst_f": None if lst.get(g) is None else round_pandas(lst[g]), "impervious_pct": None if imperv.get(g) is None else round_pandas(imperv[g]), "cdc_svi_rpl_themes": None if svi.get(g) is None else round(svi[g], 1), "ces5_pollution_burden_pctl": comp["ebs"], "_place": normalize_place(places.get(g))} records.append(record) scores = sorted(r["ucri"] for r in records if r["score_kind"] == "frozen") thresholds = {label: round_half_up(quantile(scores, q)) for label, q in CLASSES} for r in records: if r["score_kind"] == "frozen": r["priority"] = priority_for(r["ucri"], thresholds) assign_ranks(records, lambda r: "California", "state_rank", "state_pctl") assign_ranks(records, lambda r: r["geoid"][2:5], "county_rank", "county_pctl") if places: assign_ranks(records, lambda r: None if r["_place"] is None else r["geoid"][2:5] + ":" + r["_place"], "place_rank", "place_pctl") return records, thresholds # ---------------------------------------------------------------- output def fmt(value): if value is None: return "" if isinstance(value, float): text = repr(value) return text[:-2] if text.endswith(".0") else text return str(value) def write_csv(records, path): with open(path, "w", newline="", encoding="utf-8") as handle: writer = csv.writer(handle, lineterminator="\n") writer.writerow(OUTPUT_COLUMNS) for r in records: writer.writerow([fmt(r[c]) for c in OUTPUT_COLUMNS]) def check(records, path): """Compare with a released tract CSV; returns the number of differing cells.""" with open(path, newline="", encoding="utf-8") as handle: released = {row["geoid"]: row for row in csv.DictReader(handle)} columns = [c for c in OUTPUT_COLUMNS if c in next(iter(released.values()))] ours = {r["geoid"]: r for r in records} differences = 0 missing = sorted(set(released) ^ set(ours)) if missing: print(f" tracts in only one of the two files: {len(missing)}") differences += len(missing) for column_name in columns: bad = 0 for geoid in sorted(set(released) & set(ours)): a = released[geoid][column_name] b = fmt(ours[geoid][column_name]) if a == b: continue try: same = a != "" and b != "" and float(a) == float(b) except ValueError: same = False bad += not same print(f" {column_name}: {bad} differences") differences += bad return differences def main(argv=None): parser = argparse.ArgumentParser(description="Score California UCRI CA_2026.10 from tract input tables.") for name in ("tracts", "canopy", "impervious", "lst", "svi", "ces"): parser.add_argument(f"--{name}", required=True) parser.add_argument("--places") parser.add_argument("--out") parser.add_argument("--check") args = parser.parse_args(argv) records, thresholds = score(args) counts = {k: sum(r["score_kind"] == k for r in records) for k in ("frozen", "provisional", "none")} print(f"tracts: {len(records):,}; fully scored {counts['frozen']:,}, provisional {counts['provisional']:,}, " f"unscored {counts['none']:,}") print(f"thresholds: {thresholds}") print("classes: " + ", ".join( f"{label} {sum(r['priority'] == label for r in records):,}" for label in ("Very Low", "Low", "Moderate", "High", "Extreme"))) if args.out: write_csv(records, args.out) print(f"wrote {args.out}") if args.check: print(f"comparison with {args.check}:") differences = check(records, args.check) print("RESULT:", "PASS, identical to the released values" if differences == 0 else "FAIL") return 0 if differences == 0 else 1 return 0 if __name__ == "__main__": sys.exit(main())