Skip to content
EN

Create a Science Dataset

The Science panel reads a single file: a science dataset (comap.science-dataset/v1), stored in the room’s settings. It holds pre-computed sums per zone, which the panel adds up in the browser for whatever zones a viewer picks. Nobody writes it by hand: an offline builder produces it from the source data, together with a QA receipt that checks the result.

To chart the room’s own raster layers at a point a reader picks, write a Science configuration instead: see Configure the Science Panel.

Setting up a room takes four steps:

  1. Build the dataset file and review its QA receipt.
  2. Upload the zoning polygons to the room as map layers.
  3. Load the file in Room settings → Science panel, and link each zoning to its layer.
  4. Check the panel in the room.
Input What it is In the public room
Species map A GeoTIFF with one probability band per species, on the Swiss grid (EPSG:2056) 30 m cells, 11 bands: spruce, fir, pine, larch, Arolla pine, beech, maple, ash, oak, chestnut, other
Dead trees One GeoPackage of detected dead trees per flight year, each with its area in an Area field 2017 to 2024 — the same files as the room’s Mortality layers
Zonings Polygon shapefiles, each with a key field, and optionally a parent zoning to drill down from Cantons (KANTONSNUM), Districts (UUID, inside cantons), Forest ecoregions (Code)
QA references Used only to check the result The 10 m deadwood raster, the published dead-tree shares, and the flight coverage layer

A build config names all of these and adds what the panel displays: the dataset ID and its title in each language, the species labels and groups, the flight years with their expected row counts, and each zoning’s key, name, code, and parent fields. The public room’s config is python-geo-service/science/configs/public-room-v1.json in the app repository.

The builder is python-geo-service/science/ in the app repository. Run it inside the geo-service image, with the inputs mounted read-only:

Terminal window
docker run --rm \
-v "$PWD:/work:ro" \
-v "$PWD/data:/science-input:ro" \
-v "<manifest.json>:/manifest/MANIFEST.json:ro" \
-v "<output dir>:/science-output" \
-w /work/python-geo-service --entrypoint python3 <image> \
-m science.build_dataset --config science/configs/public-room-v1.json \
--input-root /science-input --output-dir /science-output --expect-manifest /manifest/MANIFEST.json
  • Every path in the config is relative to --input-root and may not leave it.
  • --expect-manifest checks the dead-tree files byte for byte against the manifest of the dataset the room’s layers were loaded from.

The builder hashes every input and writes three files, named after the dataset ID:

  • Directoryscience-output/
    • public-forest-v1.json the dataset you load in the room
    • public-forest-v1.qa.json the QA receipt, for tools
    • public-forest-v1.qa.md the same receipt, to read

It exits with status 0 only if every must-pass check passed:

  • the inputs did not change during the build;
  • each flight year has the expected number of dead-tree objects;
  • each object’s stored Area equals the area of its geometry;
  • the dead-tree files match the room’s dataset manifest (with --expect-manifest);
  • for each zoning, the zones plus the unzoned remainder add up to the whole grid.

The receipt also reports, without failing the build, whether any cell is claimed by two zones. Per zone, it compares the dead-tree share from the objects with the aligned 10 m deadwood raster and with the published share, and it shows how often the inferred latest flight agrees with the year in the coverage layer. Read the .qa.md file: near the top, it gives the overall result, PASSED or FAILED.

The panel draws each zoning from a polygon layer in the room. That layer’s features must carry the zoning’s key field — for cantons, KANTONSNUM — with the values the dataset uses. The surest way is to upload the very shapefiles the dataset was built from.

python -m science.room_layers uploads each zoning of a dataset as a polygon layer through the public API, then proves through the same API that the Science panel can use it. It needs only the Python standard library (Python 3.12 or newer) and a room API token.

  1. Mint a token. On My Rooms, click the room’s API Tokens (key) button and create a token with the Read and Upload permissions that expires after one day. Save the secret to a file that only you can read (chmod 600): the tool refuses any other file and never prints the token. See Room API Tokens.

  2. Run the tool from python-geo-service/, one step after the other, as shown below. --api is the app’s origin and --room the ID of the room to fill; put in your own for both. apply runs only once you pass it the plan digest that preflight printed.

  3. Revoke the token when you are done.

Terminal window
ARGS=(--config science/configs/public-room-v1.json --dataset ../data/science/public-forest-v1.json
--input-root ../data --api <app-origin> --room <room-id>)
python -m science.room_layers plan "${ARGS[@]}" # offline
python -m science.room_layers preflight "${ARGS[@]}" --token-file <file> # read-only; prints the plan digest
python -m science.room_layers apply "${ARGS[@]}" --token-file <file> --expect-plan <digest>
python -m science.room_layers verify "${ARGS[@]}" --token-file <file> # read-only, any time

Each step checks something before the next one may run:

Step Checks
plan Each zoning’s shapefile parts have the SHA-256s the dataset recorded, its key values equal the dataset’s zones, and the ZIP fits in one upload request. Prints the plan digest.
preflight Read-only. The token can read the room, the API’s token gate refuses GET /api/account (fail-closed), and no layer in the room already has one of the names — layer names are unique per room.
apply Runs only the plan whose digest you approved: uploads the layers one by one, waits for processing, then runs verify.
verify Read-only. One layer per name, the right feature count and polygon type, the vector tiles baked, and the tiles carrying exactly the dataset’s zone keys — the only way the panel can find a zone on the map.

The summary it prints (and writes to a file with --receipt <file>) lists the new layer IDs per zoning. Its exit status says how it ended: 0 passed, 2 a local check failed, 3 the API refused (token, permission, name taken, quota), 4 server or network failure, 5 verification failed.

  • The layers stay hidden in the legend unless you add --visible: the panel draws their outlines itself while it is open.
  • A token cannot delete layers. To undo an upload, the room owner deletes the layer in the room.
  • Each upload adds an Add layer entry to the room’s timeline, made by api-token:<name>.

You can also upload a zoning yourself, as a zipped shapefile, from the Upload Layer tab — see Upload a Shapefile. Use the same shapefile the dataset was built from, so that the features carry the key field with the same values. Nothing checks this for you: if the keys do not match, the panel still shows its figures but cannot draw or pick those zones on the map.

  1. In the room, click the gear — Room settings — at the right of the top bar. The Science panel section is shown to owners and editors only. (The same settings are also under Menu → Settings in the left rail.)

  2. Click Load dataset (.json) and choose the dataset file. The section shows its title and ID — for the public room, Forest species and dead trees · public-forest-v1. A file that is not a valid dataset is refused with Not a valid science dataset: and the reason.

  3. Under Map layer for Cantons, Map layer for Districts, and so on, choose the layer that draws each zoning. A layer whose name mentions the zoning is pre-selected, so layers named after their zonings link themselves. No map layer leaves a zoning without outlines.

  4. Optionally, choose the Default zones and the Default view the panel opens with for everyone. Left at —, it opens on the first zoning that has no parent, in Composition.

  5. Click Save. Saved for everyone in the room. confirms it, and the Science button appears in the map toolbar for everyone.

  • Loading a file only fills in the form: nothing changes for anyone until you Save. Loading a file also resets the layer links to the suggestions and clears the defaults, so check them before you save.
  • If another owner or editor saves while you are editing, your unsaved changes are replaced by theirs.
  • Remove dataset takes the panel out of the room for everyone.
  • When the dataset changes, every viewer’s panel starts again from the room’s defaults.

Open the Science panel in the room, then:

  • switch between the zonings — each one should draw its outlines on the map;
  • click a zone on the map — it should be selected in the list;
  • open How to read — the sources and the build date should match the QA receipt.

If a zoning shows its figures but no outlines, its layer is not linked, or the layer’s features lack the key field.

  • 512 KB. The room keeps the dataset, with its layer links, in its settings, up to 512 KB. A larger dataset is refused, never truncated: This dataset is too large to store in the room.
  • Zonings are fixed when the dataset is built. A new zoning, or new boundaries, means rebuilding the dataset. Analysing an uploaded or drawn polygon is not available.
  • Re-link after cloning. Cloning or exporting a room copies the dataset, but its zoning links still point at the original room’s layers. Re-link them in Room settings → Science panel in the copy — see Export & Import a Room.
  • A strict format. The app accepts at most 16 species, 6 zonings, 600 zones per zoning, 16 flight years, and 64 sources, with labels of up to 120 characters in up to 8 languages.
  • Not in Presentation mode. The presentation view does not show the panel.

The app repository documents the rest:

  • docs/features/science-panel.md — the design, the dataset contract, and the metrics;
  • python-geo-service/science/README.md — the builder and upload commands, and how to run their tests;
  • python-geo-service/science/configs/public-room-v1.json — the public room’s build config;
  • app/lib/science/science-dataset.ts — the parser that enforces the format.