Skip to content

About

Strict, source-transparent solar/UV forecast + calibration stack — absolute melanogenic intensity vs local outdoor opportunity, published on a schedule.

Topics

Resources

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

SunStack TanScore

A strict, source-transparent solar/UV forecast and calibration stack.

forecast-run Python Live site

Live forecast · Getting started · Scores · Safety model · Contributing

SunStack estimates spectrally weighted delayed-pigmentation exposure from forecast atmospheric conditions, reports independent erythemal exposure, and separately evaluates outdoor usability. Strict mode fails loudly on missing/unverifiable inputs and labels its degraded Tier-C broadband backend explicitly; no gate-passing Tier-B emulator is wired yet. It fetches live Open-Meteo forecasts, full ensemble data, native HRRR sub-hourly radiation, CAMS air-quality data, direct Copernicus CAMS spectral/ozone forecasts, NASA POWER historical UVA/UVB, archived Open-Meteo forecasts, and previous runs for lead-time skill calibration.

Shipped v5 semantics

Contract Value
Schema / temporal support sunstack-output-v5 · interval-contract-v1
Exposure endpoint / action spectrum delayed-pigmentation-v2 · parrish-fda-3630-v1
Spectral backend Tier-C tierC-broadband-proxy-v2 in production (no gate-passing tierB-libradtran-emulator-v1 wired; strict publishes Tier-C labeled; tier A/B claims fail loudly)
Surface / fusion / confidence / ranking uv-surface-v1 · calibrated-uvi-fusion-v2 · best-match-headline-v1 (UVI headline is the best match; the fusion is published beside it) · heuristic-reliability-v1 (handwritten expected-error heuristic; not an empirically calibrated interval) · fixed-duration-dose-v2

How it works

flowchart LR
    A[Open-Meteo live + ensembles] --> D[Fetch + validate]
    B[Direct CAMS spectral/ozone] --> D
    C[NASA POWER + archives + skill] --> E[Calibrate]
    D --> F[Deterministic consensus]
    E --> G[UVA/UVB estimators]
    F --> G
    G --> H[Absolute vs local scoring]
    H --> I[30-min windows + blocks]
    I --> J[Static site + calendar]
Loading

Git history is the audit trail: every scheduled run commits its export, so any published number traces back to the exact inputs that produced it. Strict mode refuses to publish rather than score blind.

Scores

Every hour and 30-minute period exposes the components separately:

Score What it means
tan_score_absolute_0_100 Globally anchored delayed-pigmentation intensity: 100 * E_mel / fixed global reference. Not graded on a South Bend curve
local_tan_score_0_100 Percentile versus historical daylight around this location and season (serving-domain reference)
geometry_conditioned_transmission_percentile_0_100 Geometry-conditioned transmission percentile (conditional comparison, not causal isolation; legacy alias atmospheric_quality_percentile_0_100)
strong_sun_probability_0_100 Probability of useful sun (ensemble/DNI/GHI/cloud); product quantity, not confidence
outdoor_feasibility_0_100 Practical outdoor usability only (with outdoor_feasibility_complete + missing-field reasons)
overall_tan_opportunity_0_100 LEGACY composite (deprecated product heuristic); ranking uses fixed-duration delayed-pigmentation dose

Doses are reported separately from intensity (never ranked as intensity):

Dose What it means
tan_dose_*_j_m2 Model-defined melanogenic-effective cumulative exposure (NOT a standardized unit)
sed_* Independent erythemal channel; never increases TanScore or Opportunity
uva_dose_* / uvb_dose_* Diagnostic physical broadband doses, not biological endpoints

Overall formula (legacy composite, deprecated)

The unblocked composite is a weighted geometric mean — 70% Absolute, 15% Local, 5% Atmosphere, 10% Confidence — capped at Absolute+20, so local rarity can never turn weak physical UV into a fake elite score. Then it is multiplied by outdoor feasibility. It remains for migration only; the primary ranking is maximum expected 30-minute delayed-pigmentation dose (fixed-duration-dose-v2), with strongest vs best-usable variants.

Absolute    44
Local       97
Atmosphere  94
Confidence  91
Overall     ~60 before weather usability

That reads as excellent for South Bend but only moderate on an absolute terrestrial scale — both true at once.

Outdoor hard blocks and flags

Outdoor usability is deliberately separate from melanogenesis physics.

Default hard blocks (Overall = 0, Absolute untouched): active rain/drizzle/showers, active snow, thunderstorm, temperature < 50°F (configurable) or >= 110°F. Soft penalties: 50–68°F cold comfort, 100–110°F heat, precipitation probability, high wind, hot + humid.

A uv_input_disagree flag fires when broadband and UV inputs describe different skies (per-variable model stitching on convective days); it halves confidence and prints a visible note rather than hiding the disagreement. Thresholds in .env.example / environment variables.

Fitzpatrick skin type

Dashboard and CLI accept optional Fitzpatrick I–VI (uv run sunstack run --skin-type 2, or the UI selector). It is qualitative personal-response/risk context only — it never multiplies environmental TanScore, because measured MED/MMD overlaps substantially within Fitzpatrick groups.

For a measured or defensibly estimated personal MMD in melanogenic-effective J/m², uv run sunstack run --personal-mmd 12000 --personal-mmd-basis SUNSTACK_EFFECTIVE_DOSE_MEASURED adds personal_mmd_fraction (TanDose ÷ personal MMD) with its provenance label — still without touching environmental physics. The dashboard and CLI accept surface and skin-plane controls; /api/data, /api/refresh, and /api/calendar.ics accept surface, surface_extent, skin_tilt_deg, and skin_azimuth_deg (422 for a value outside the declared domain). CLI equivalents are --surface, --surface-extent, --skin-tilt-deg, and --skin-azimuth-deg. The shared calendar and persisted runs remain exposure_basis=environmental_horizontal; skin-plane fields are context.

Quick start

Prerequisites

  • Python 3.13
  • uv
  • Git
git clone https://github.com/carterlasalle/openmeteo-sunstack-tanscore.git
cd openmeteo-sunstack-tanscore
uv sync

1. Configure Copernicus ADS

Create a free Copernicus Atmosphere Data Store account, accept the CAMS dataset terms, and configure standard cdsapi credentials (~/.cdsapirc). Then verify everything (--probe makes real live Open-Meteo requests):

uv run sunstack doctor --probe

2. One-command full setup

uv run sunstack setup

Fetches NASA POWER UVA/UVB (2001+), Open-Meteo historical forecasts, previous runs, CAMS EAC4; trains UVA/UVB estimators; builds the local reference distribution and model/lead-time skill; then makes a fresh live run. Strict is the default: a missing critical source exits non-zero instead of inventing values. Troubleshooting only: uv run sunstack run --allow-degraded.

3. Daily use

uv run sunstack ui    # dashboard at http://127.0.0.1:8765
uv run sunstack run   # terminal run (live cache bypassed by default)

Architecture

src/sunstack/
  cli.py           run / setup / bootstrap / doctor / ui / export
  fetch.py         live Open-Meteo fan-out (deterministic, ensemble, HRRR-15min, air quality)
  history.py       NASA POWER, archives, previous runs, CAMS EAC4 + direct CAMS forecast
  normalize.py     per-source normalization
  derive.py        consensus, ensemble probabilities, solar diagnostics
  tanscore.py      UVA/UVB estimators, action-spectrum absolute scoring, UVI fusion
  photobiology.py  E_mel / TanDose / SED core, spectra validation, strict gates
  spectral.py      skin-plane spectral layer, tiers A-D, Tier-C broadband mapping
  doses.py         trapezoidal TanDose/SED/UVA/UVB integration with gap flags
  tan_response.py  future delayed-pigmentation response interface (not shipped)
  opportunity.py   30-min forecast, outdoor feasibility, daily summaries, Fitzpatrick context
  validation.py    strict gates (sources, CAMS fields, photobiology, score ranges)
  output.py        static-site + calendar export
  ui.py            dashboard, data + refresh + calendar APIs
  calibrate.py     training + serving-domain local reference + skill
data/
  latest/          current snapshot (summary, raw manifests, tables)
  runs/            every run, timestamped
  calibration/     models, reference distribution, skill
  research/action_spectra/  versioned action spectra + provenance metadata
docs/              published static site (each run republishes)

Safety model

SunStack intentionally makes silent degradation inconvenient:

  • Every normal run bypasses the live HTTP cache — forecasts represent real requests, not stale reads. (--cached-live only when deliberate.)
  • Strict mode validates Best Match, HRRR 15-min, air quality, minimum deterministic/ensemble counts, calibration artifacts, direct CAMS fields, and score ranges. Any critical failure exits 1 with the exact failure plus the path to data/logs/sunstack.log.
  • Historical data is cached (immutable decades shouldn't be redownloaded); --force refetches deliberately.
  • uv run sunstack debug prints the latest run summary and raw source manifest.

Data sources

Live (uncached by default): Best Match, HRRR, NBM, NAM, GFS/AI-GFS, ECMWF IFS/AIFS, ICON, GEM + HRDPS, UKMO, ACCESS, CMA GRAPES, full-member GEFS/AIGEFS/ECMWF ensembles, ensemble means, native HRRR 15-minute, CAMS air quality/AOD550, deep pressure profiles.

Direct CAMS/ADS (strict-required): AOD and absorption AOD at 340/355/380/400 nm, single-scattering albedo, asymmetry factor, total-column ozone and water vapour, cloud liquid/ice columns, forecast albedo, CAMS UV diagnostics. Group requests first, per-variable retry on rejection, exact failures in raw/cams_forecast/manifest.json.

30-minute semantics

Near-term periods use native HRRR radiation/weather at true sub-hourly timestamps; hourly UV is interpolated with a bounded HRRR broadband correction. Farther out, rows are labeled interpolated_hourly — calendar/UI usability, not fake independent forecasts.

Important interpretation

TanScore is an environmental/pigmentation-potential model, not a safe exposure-time recommendation. Tanning and erythema are both consequences of UV exposure; no skin type makes a UV dose harmless. The UI keeps radiation intensity, local context, weather feasibility, and personal skin-response context separate rather than synthesizing exposure-time advice.

Documentation

Document Purpose
CONTRIBUTING.md Development workflow and pull-request standards
SECURITY.md Supported versions and vulnerability reporting
AGENTS.md Repository-specific instructions for coding agents
RESEARCH_NOTES.md Dated calibration and incident evidence log
PHOTOBIOLOGY_MODEL.md v5 delayed-pigmentation model, equations, interaction-term evidence
TANDOSE.md TanDose definition (model-defined, not standardized)
ACTION_SPECTRA.md Spectrum provenance, tiers, interpolation rules
SPECTRAL_MODEL.md Spectral layer, tiers A-D, skin-plane physics
.env.example Every tunable threshold

Contributing

Solo-owner mode with required checks; read CONTRIBUTING.md before making changes. Run uv run pytest tests/ -q and uv run ruff check src tests before opening a pull request.

About

Strict, source-transparent solar/UV forecast + calibration stack — absolute melanogenic intensity vs local outdoor opportunity, published on a schedule.

Topics

Resources

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages