OrcaCast is a static React + TypeScript application for exploring weekly, H3-indexed, relative likelihood surfaces for reported orca sightings in the Pacific Northwest. It is designed for transparent spatial analysis workflows where temporal integrity, data provenance, and reproducibility are first-class concerns.
Live app: orcacast-app.pages.dev
Important interpretation note
OrcaCast forecasts where sightings are more likely to be reported relative to other cells in the same week. It is not real-time whale tracking, presence/absence ground truth, or navigational guidance.
npm install
npm run devpython3 -m venv .venv
source .venv/bin/activate
python -m pip install -e .
python -m src.cli --help- 1. Product Overview
- 2. Key Capabilities
- 3. Application Pages + Screenshot Gallery
- 4. Architecture at a Glance
- 5. Data Contracts and Folder Layout
- 6. Forecast Payload Formats
- 7. Temporal / Spatial / Evaluation Integrity
- 8. Local Development
- 9. Configuration Reference
- 10. Testing and Validation Checklist
- 11. Deployment
- 12. Troubleshooting
- 13. Project Structure
- 14. Contributing Guidance
- 15. License / Credits
This application combines:
- H3 forecast layers at multiple resolutions (
H4,H5,H6) - Model Compare (single swipe and dual-map comparison)
- User controls for map theme, layer mode, and view preferences
- Supporting pages for About, Data provenance, Model catalog, and Model Explainability
The app is fully static and client-rendered; no backend runtime is required to serve the core experience. This is to reduce operational costs at the drawback of slower load times on client side.
- Browse weekly forecast periods loaded from
public/data/periods.json - Switch grid resolution (
H4,H5,H6) to trade detail for regional context - Toggle observed/forecast displays and optional map overlays
- Open tool drawers and modals for additional exploration workflows
- Compare outputs across models, periods, and resolutions
- Use swipe or dual-map interactions for side-by-side interpretation
- Inspect relative differences without changing source datasets
- Compare actuals to model outputs
- About: interpretation guidance, caveats, and responsible use
- Data: lineage diagrams, dynamic/static coverage views, and provider context
- Models: model catalog cards and performance metrics (currently in progress state)
- Explainability: model diagnostics area (currently in progress state)
OrcaCast routes are configured in src/App.tsx:
/→ Map/about→ About/models→ Models/explainability→ Explainability/data→ Data
Interactive forecast map with resolution controls, model/period selection, and compare workflows.
Interpretation guidance, grid-size explanations, limitations, and responsible-use messaging.
Model catalog interface with card/carousel presentation and model metadata.
Model diagnostics section scaffold
Data lineage, coverage matrix, source acknowledgements, and rendering/provider context.
- App bootstraps providers and routes in
src/App.tsx MapPageorchestrates state, data loading, compare logic, and modal workflowsForecastMapowns rendering lifecycle (MapLibre + deck.gl)- Data loaders in
src/datafetch grids, forecast payloads, periods, and related inputs - UI state is shared via
MapStateContextandMenuContext
- React 18 + TypeScript
- Vite (
rolldown-vite) - MapLibre GL
- deck.gl
- React Router
- Driver.js (guided tour)
All runtime data is expected under public/data.
-
public/data/periods.json
Array of forecast periods:[{ "year": 2025, "stat_week": 34, "label": "optional" }] -
public/data/grids/H4.geojson,H5.geojson,H6.geojson
GeoJSON feature collections keyed by H3 cell identifier (properties.h3). -
public/data/forecasts/latest/weekly/<year>_<week>_<Hn>.json
Weekly forecast payload files for each period/resolution. -
public/data/last_week_sightings/last_week_sightings_<year>-W<week>.geojson(optional)
Observed overlay points for selected weeks. -
public/data/activity/activity_by_decade_week_SRKW_<Hn>.json
Time-series modal data. -
public/data/places_of_interest.json
Marker definitions for POI overlays.
public/data/forecasts/latest/weekly_blurred/<year>_<week>_<Hn>_CONTOUR.geojson
Used when blurred contour layers are enabled.
The loader supports multiple JSON payload variants.
{
"values": {
"8928308280fffff": 0.018,
"89283082813ffff": 0.024
}
}{
"models": [
{ "id": "model_a", "values": { "8928308280fffff": 0.02 } },
{ "id": "model_b", "values": { "8928308280fffff": 0.03 } }
]
}{
"valuesByModel": {
"model_a": { "8928308280fffff": 0.02 },
"model_b": { "8928308280fffff": 0.03 }
}
}When multiple models are present, the app can surface a synthetic consensus option (mean by cell). Note: this is not a valid verified forecast but can be helpful to see where all models agree.
Guard against silent drift in these areas:
- Ensure forecast period indexing remains ISO-week consistent
- Verify week-shift logic and period-fill logic do not leak future context
- Confirm train/eval assumptions in model documentation remain causal
- Validate H3 level (
H4/H5/H6) remains consistent across joins/overlays - Confirm no CRS or coordinate-order drift when ingesting GeoJSON
- Re-check any pruning/smoothing process that could alter hotspot geometry
- Ensure metrics are computed on intended populations, at intended time windows
- Keep reporting-effort caveats explicit in interpretation text
- Treat “forecast likelihood” as relative ranking, not absolute probability of presence
- Prefer config-driven behavior over ad-hoc constants
- Keep file naming deterministic (
<year>_<week>_<Hn>) for reproducible loads - Document any behavior-changing config updates in changelogs/PR notes
- Node.js 18+ (Node 20 recommended)
- npm
- Python 3.10+ for the utility modules in
src/cli,src/explainability,src/io, andsrc/visualization
npm installnpm run devThe Python utilities use the packaging metadata in pyproject.toml, so the supported setup path is editable install plus python -m execution.
python3 -m venv .venv
source .venv/bin/activatepython -m pip install -e .Run the CLI either as a module or through the installed console script:
python -m src.cli --help
orcacast-cli --helpCurrent supported subcommands include:
python -m src.cli explainability build --helppython -m src.cli explainability build \
--run-id latest \
--model-id composite_linear_logit \
--target sighting_likelihood \
--resolution H4 \
--source-shap-dir public/data/forecasts/latest/shap \
--output-root artifacts/explainabilityThis writes artifact bundles under artifacts/explainability/<run-id>/<model-id>/<target>/.
If you want short aliases for the most common Python commands:
make py-install
make py-cli-help
make py-exp-helpnpm run buildnpm run previewnpm run lint
npm run test
npm run typecheckPrimary runtime configuration:
- default forecast period
- best/default model identifier
- KDE folder/run ids
- geometry-pruning and rendering thresholds
Path builders for:
- grids
- weekly forecasts
- actuals/sightings paths
Build/serve base path is currently /. If deploying under a subpath, adjust base accordingly.
Before merging behavior-changing updates:
- Route sanity: verify all routed pages load (
/,/about,/models,/explainability,/data) - Forecast load sanity: select multiple periods/resolutions and confirm map layers render
- Overlay sanity: toggle last-week sightings and KDE contours on/off
- Compare sanity: test compare mode for at least one period pair and model pair
- Data integrity spot-check: open one forecast JSON and validate H3 keys align with target grid
- Build/lint: run
npm run buildandnpm run lint
Explainability artifact builder CLI:
python3 -m src.cli explainability build --run-id ... --model-id ... --target ... --sample-n 50000 --top-k-interactions 50
These are not required to run the frontend app, but can be used in preprocessing workflows.
- Build command:
npm run build - Output directory:
dist - Node version: 18+
Because OrcaCast is an SPA, ensure host-level fallback routing is configured so deep links resolve to index.html.
- Confirm required files exist for selected period/resolution
- Check browser console for GeoJSON or JSON parse errors
- Validate H3 keys and geometry properties are present
- Confirm matching
<year>_<week>_<Hn>.jsonexists for each configured period - Verify model id selection exists in multi-model payloads
- Re-check config defaults and local storage flags
- Verify data refresh did not silently remove a period or model
src/
App.tsx
components/
ForecastMap.tsx
SideDrawer.tsx
ToolDrawer.tsx
...
config/
appConfig.ts
dataPaths.ts
attribution.ts
core/
time/
data/
forecastIO.ts
periods.ts
expectedCount.ts
features/
models/
analysis/
map/
pages/
MapPage.tsx
AboutPage.tsx
ModelsPage.tsx
ExplainabilityPage.tsx
DataPage.tsx
SettingsPage.tsx
state/
MapStateContext.tsx
MenuContext.tsx
tour/
When making model/data-facing changes:
- Prefer minimal diffs that preserve behavior unless behavior change is intended
- Document whether outputs change and under what conditions
- Keep temporal/spatial assumptions explicit in code comments and PR notes
- Avoid broad refactors that complicate traceability for review
When changing UI-only behavior:
- Update screenshots under
docs/screenshots - Ensure route-level README gallery links remain valid
- Basemap and rendering acknowledgements are surfaced in the Data page.
- OrcaCast is intended for educational and planning use with wildlife-safe practices.




