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:
- Build the dataset file and review its QA receipt.
- Upload the zoning polygons to the room as map layers.
- Load the file in Room settings → Science panel, and link each zoning to its layer.
- Check the panel in the room.
What goes in
Section titled “What goes in”| 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.
Build the dataset
Section titled “Build the dataset”The builder is python-geo-service/science/ in the app repository. Run it inside the geo-service
image, with the inputs mounted read-only:
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-rootand may not leave it. --expect-manifestchecks 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
Areaequals 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.
Upload the zoning layers
Section titled “Upload the zoning layers”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.
With the upload tool (recommended)
Section titled “With the upload tool (recommended)”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.
-
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. -
Run the tool from
python-geo-service/, one step after the other, as shown below.--apiis the app’s origin and--roomthe ID of the room to fill; put in your own for both.applyruns only once you pass it the plan digest thatpreflightprinted. -
Revoke the token when you are done.
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[@]}" # offlinepython -m science.room_layers preflight "${ARGS[@]}" --token-file <file> # read-only; prints the plan digestpython -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 timeEach 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>.
With Upload Layer
Section titled “With Upload Layer”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.
Load the dataset and link the zonings
Section titled “Load the dataset and link the zonings”-
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.)
-
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.
-
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.
-
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.
-
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.
Check the panel
Section titled “Check the panel”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.
Limits
Section titled “Limits”- 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.
Engineering detail
Section titled “Engineering detail”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.