Skip to content

README.md

Latest commit

 

History

History
140 lines (99 loc) · 4.56 KB

README.md

File metadata and controls

140 lines (99 loc) · 4.56 KB

CoRE Stack Notebook Apps

marimo-native notebooks and deployable web apps for exploring CoRE Stack public geospatial data.

This repo is being rebuilt around the current CoRE Stack public surface:

  • discover active geographies through GET /api/v1/get_active_locations/
  • inspect generated vector and raster layers through GET /api/v1/get_generated_layer_urls/
  • fetch stable MWS and village geometries
  • join analytical tables through the watershed uid
  • expose the workflow as reproducible marimo notebooks, scripts, and app views

Why marimo

marimo notebooks are Python files, reactive apps, and executable scripts at the same time. That matters here because CoRE Stack analysis wants all three:

  • a contributor can edit notebooks as normal Python
  • a user can run the notebook as an app without seeing implementation code
  • the same file can be checked, tested, exported, and embedded in docs

Current Shape

.
├── notebooks/
│   ├── 01_public_data_browser.py
│   ├── 02_exploratory_layer_studio.py
│   ├── 03_mws_deep_dive.py
│   ├── 04_action_planner.py
│   └── 05_guided_map_tour.py
├── scripts/
│   └── build_pages.py
├── src/corestack_notebook_apps/
│   ├── config.py
│   ├── geo.py
│   └── public_api.py
├── docs/
│   └── architecture.md
└── .archive/
    ├── README.md
    └── legacy-2026-05-17/

Quickstart

Use uv for everything.

uv sync
uv run marimo run notebooks/01_public_data_browser.py

For editing:

uv run marimo edit --watch notebooks/01_public_data_browser.py

For validation:

uv run marimo check notebooks/01_public_data_browser.py
uv run marimo check notebooks/02_exploratory_layer_studio.py
uv run marimo check notebooks/03_mws_deep_dive.py
uv run marimo check notebooks/04_action_planner.py
uv run marimo check notebooks/05_guided_map_tour.py
uv run notebooks/01_public_data_browser.py

API Credentials

The app reads credentials from .env without displaying them in the notebook.

Preferred key:

PUBLIC_API_X_API_KEY=...

The current local .env also has the legacy key name corestsack-api-key, which is supported for compatibility.

Notebook Apps

notebooks/01_public_data_browser.py is the seed app. It lets a user:

  • choose an active state, district, and tehsil
  • inspect published layer inventory by dataset and layer type
  • load MWS and village geometries
  • preview those geometries on a lightweight map
  • select one MWS and fetch its time series plus KYL indicator row

notebooks/02_exploratory_layer_studio.py is a layer catalog workbench for filtering datasets, inspecting public URLs, previewing geography, and copying a reusable manifest.

notebooks/03_mws_deep_dive.py turns one micro-watershed into a compact analytical brief with water balance signals, vegetation time series, KYL indicators, map context, and a report link.

notebooks/04_action_planner.py scans candidate micro-watersheds, lets users adjust planning weights, ranks the candidates, maps the top set, and creates a field-check brief.

notebooks/05_guided_map_tour.py teaches users how to move from map orientation to evidence layers, time-series reading, indicator interpretation, and a self-arranged dashboard.

This is intentionally the narrow waist of the repo. Future notebooks should reuse common request and GeoJSON logic where possible, while staying WebAssembly-safe for static export.

Deploy To GitHub Pages

The repo is configured to deploy the notebook suite as marimo WebAssembly exports through GitHub Actions.

In GitHub, set Pages to use GitHub Actions:

Settings -> Pages -> Build and deployment -> Source -> GitHub Actions

Then push to dev or main, or run the Deploy GitHub Pages workflow manually.

GitHub Pages is static, so the public app does not include a private API key. Users paste their CoRE Stack API key into the app at runtime.

For a local static preview:

uv run python scripts/build_pages.py
uv run python -m http.server --directory site 8010

See docs/deployment.md for the workflow details.

Archive

The previous exploratory files are preserved under .archive/legacy-2026-05-17/. See .archive/README.md for a map of what moved and when to use it.

References