Configure the Science Panel
A Science configuration turns a room’s raster layers into charts. A reader picks a point on the
map, and the Science panel shows how a measure runs there:
along years or months, or compared across scenarios or periods. The configuration is a JSON file
(comap.science/2) that says what each layer is. The panel works out the rest, so the file never
wires a chart to particular layers.
- Prepare the layers: upload the rasters, with unique names and band descriptions.
- Write the configuration: the measures, the dimensions, one source per layer, and the views.
- Load it in Room settings, or with a script.
- Check it: pick a few points.
What it can do
Section titled “What it can do”| Now | Later | |
|---|---|---|
| Data | Raster layers: one value per cell, or bands along years or months | Category and class rasters, map objects, tables per zone |
| Places | A point: the stored cell under a click | Zones, a drawn area, everything |
| Summaries | Value, series (along years or months), comparison (across scenarios or periods) | Composition, distribution, ranking |
Some things are left out by design: formulas or derived layers, interpolation, more than four series in one chart, and free colours. A missing value is always a gap, never a zero.
Prepare the layers
Section titled “Prepare the layers”- Upload each raster as its own layer (Upload a GeoTIFF). Give each a unique, stable name: the configuration finds layers by name.
- A stack of years or months is one multi-band GeoTIFF with one band per year or month. Write the
year (
2020) or the month in each band’s description: its name in English, German, French or Italian (June,Juni,juin,giugno), or its number (6). The panel reads the axis from them. A stack without descriptions can give a start year instead (see Sources). - Set the nodata value in the GeoTIFF, so that empty cells read as no data rather than as numbers.
Write the configuration
Section titled “Write the configuration”This example charts hot days per year, observed and under one climate scenario, against the mean of a reference period:
{ "schema": "comap.science/2", "id": "summer-heat", "title": { "en": "Summer heat", "de": "Sommerhitze", "fr": "Chaleur estivale", "it": "Caldo estivo" }, "measures": [ { "key": "hot_days", "label": { "en": "Hot days" }, "unit": { "en": "days" }, "decimals": 0, "direction": "higher-worse", "zero": true } ], "dimensions": [ { "key": "scenario", "kind": "categorical", "label": { "en": "Scenario" }, "values": [ { "key": "obs", "label": { "en": "Observed" }, "slot": 1 }, { "key": "rcp85", "label": { "en": "RCP8.5" }, "slot": 4 } ] }, { "key": "period", "kind": "interval", "label": { "en": "Period" }, "values": [ { "key": "1991-2020", "label": { "en": "1991–2020" }, "start": 1991, "end": 2020 } ] }, { "key": "year", "kind": "year", "label": { "en": "Year" } } ], "sources": [ { "key": "obs-yearly", "kind": "raster", "layer": { "name": "Hot days · yearly · observed" }, "measure": "hot_days", "at": { "scenario": "obs" }, "bands": { "dim": "year", "from": "descriptions" } }, { "key": "rcp85-yearly", "kind": "raster", "layer": { "name": "Hot days · yearly · RCP8.5" }, "measure": "hot_days", "at": { "scenario": "rcp85" }, "bands": { "dim": "year", "from": "descriptions" } }, { "key": "obs-mean", "kind": "raster", "layer": { "name": "Hot days · 1991–2020 mean" }, "measure": "hot_days", "at": { "scenario": "obs", "period": "1991-2020" } } ], "views": [ { "key": "yearly", "label": { "en": "Year by year" }, "summary": "series", "places": ["point"], "x": "year", "series": "scenario", "reference": { "at": { "scenario": "obs", "period": "1991-2020" }, "label": { "en": "1991–2020 mean" }, "modes": ["overlay", "difference"] } } ], "defaults": { "view": "yearly", "measure": "hot_days" }, "info": { "en": "Hot days: days with a maximum above 30 °C, counted per year." }}Every label is plain text keyed by language (en, de, fr, it, and so on, at most eight). The
panel shows the reader’s language, then English. A plain string counts as English.
Measures
Section titled “Measures”What is measured. unit is shown beside the values, and decimals (0–6) rounds them. direction
(higher-worse, lower-worse or neutral) records how to read them. zero: true starts the value
axis at zero, which suits counts and sums.
Dimensions
Section titled “Dimensions”How the data is cut:
kind |
Values | Used for |
|---|---|---|
categorical |
Listed; slot 1–4 picks a series’ colour and dash |
A facet such as the scenario, and a chart’s series |
interval |
Listed, each with start and end |
A facet such as the period, and a comparison’s axis |
year |
Read from the data | The bands of a stack, and the x axis of a series |
month |
1–12, read from the data | The bands of a stack, and the x axis of a series |
Sources
Section titled “Sources”One per room layer. A source names its layer by its exact name. It also gives its measure,
the facets it stands for (at: one value per categorical or interval dimension), and, for a stack,
how its bands run:
"bands": { "dim": "year", "from": "descriptions" }reads each band’s year (or month) from its description;"from": "start"with"start": 1981(and"step", 1 by default) counts years from the first band;"from": "values"lists one year or month per band.
Without bands, a source is one value per cell, read from band 1, or from the band that band names.
Two such sources with the same measure and facets are refused: one cell, one value.
What the panel offers, in this order. Each view has a summary, the places it works for (point
for now), the measures it shows (all of them by default), and its dimensions:
summary |
x |
Chart |
|---|---|---|
series |
A year or month dimension | One line per series, gaps at missing values |
comparison |
A categorical or interval dimension | Grouped bars |
value |
None | The value of each series, as a table |
seriesnames a categorical dimension of at most four values: one line or bar per value.controlslet the reader choose one value of another dimension, for example[{ "dim": "period", "default": "2070-2099" }]for the period a month profile shows.referenceis the slice drawn for comparison: a level line when it is a single value, or a dashed series when its bands run alongx. With"modes": ["overlay", "difference"], the panel also offers Difference to the reference.
defaults names the view and the measure the panel opens with, and info holds the text of How to
read in each language (plain text, at most 8,000 characters per language).
How a view finds its layers
Section titled “How a view finds its layers”You never list a view’s layers. For a series, every source of the chosen measure whose bands run
along x adds one point per band, to the series its facets put it in. For a comparison, every
single-value source with a facet on x adds a bar. A view’s controls narrow the sources first; a
source without a facet on a control’s dimension does not vary along it and stays in. Adding a layer to
a series is therefore one more source, with no change to the view.
Limits
Section titled “Limits”At most 16 measures, 8 dimensions, 128 sources and 16 views, four series in a chart, labels of 120 characters, and 512 KB for the whole file.
Load it
Section titled “Load it”In Room settings
Section titled “In Room settings”-
In the room, click the gear — Room settings — at the right of the top bar. The Science configuration section is shown to owners and editors only, above the Science panel section of a science dataset.
-
Click Load configuration (.json) and choose the file. The file holds the configuration itself, or
{ "config": …, "bindings": … }. -
A valid file is saved at once: Saved for everyone in the room. The section then shows its title and ID, and how many of its layers it found (3 of 3 layers found in this room.). A source that found no layer, or more than one, is listed below.
If the file has problems, nothing is saved: Not saved: 2 problems in the configuration., followed
by each problem with its place in the file, for example sources[3].measure: unknown_measure. The
room keeps its previous configuration until a valid one is loaded. Remove configuration removes it
for everyone. While a room has a configuration, the Science panel section of a science dataset is
hidden.
With a script
Section titled “With a script”A room token with the write permission stores the configuration over HTTP. Check it first with
validate, which saves nothing:
curl -X POST "$API/api/rooms/$ROOM/science/validate" \ -H "Authorization: Bearer $COMAP_API_TOKEN" -H "Content-Type: application/json" \ -d "{\"config\": $(cat summer-heat.json)}"curl -X PUT "$API/api/rooms/$ROOM/science" \ -H "Authorization: Bearer $COMAP_API_TOKEN" -H "Content-Type: application/json" \ -d "{\"config\": $(cat summer-heat.json)}"An invalid configuration is refused whole, with 400 invalid_science_config and every problem’s
path. See Science Panel in the API reference.
Check it
Section titled “Check it”- Open the Science panel and pick a point inside the data. Each view should show its series, and How to read should list every source with its layer and bands, such as 80 bands, 2020–2099.
- A source without a layer reads no layer with this name in the room, and a stack whose band descriptions are not years or months reads band 2 cannot be read as a year or month.
- To compare one value with its source, read the same cell from the GeoTIFF, for example with
gdallocationinfo -wgs84 layer.tif LON LAT. The panel returns the stored value: nothing is interpolated.
Everyone who can view the room reads its configuration, anonymous visitors of a public room included. Keep names and e-mail addresses out of it.