The Data Directory¶

Decision Theatre reads all of its content from a data directory, passed with --data-dir and defaulting to ./data. This page describes exactly what the application looks for there, cross-referenced to the code that reads it, so an administrator can tell what is required, what is optional, and what does not belong.

Every path below was verified against the Go source. Where a filename is hardcoded, that is stated — those files cannot be renamed.

nix run .#check-data          # or: dt check-data

Required for the application to work¶

mv data/mbtiles/africa-002.mbtiles data/mbtiles/africa.mbtiles

GeoPackage structure¶

datapack.gpkg must contain:

Optional, enabling whisker bounds in charts: scenario_current_lower, scenario_current_upper, scenario_reference_lower, scenario_reference_upper.

metadata.csv and column-name matching¶

metadata.csv is keyed on ColumnName, and the lookup is an exact string match against the column names in the GeoPackage scenario tables. A row whose ColumnName does not match a real column is silently ignored, and the corresponding indicator will:

• render with its raw column name,
• have no colour, units or axis label,
• have no chart-type detection, and
• not appear in the map or chart selectors at all, because the MapthisYN and graphthisYN lookups miss.

For the full column-by-column reference, see Datapack Format.

Runtime directories¶

These are written to while the application runs. They are created on demand, but their parent must be writable.

Optional content¶

Each walkthrough file's name must equal the id field inside it, and both must match an entry in frontend/src/constants/walkthroughSites.ts. All three are checked by the validator.

Data pipeline inputs¶

These are consumed by scripts/build-geopackage.sh to produce datapack.gpkg. They are not read at runtime and do not need to be shipped in a distributed data pack — they account for roughly 2 GB.

Keeping them alongside the runtime data is reasonable on a workstation that rebuilds the GeoPackage. Omit them when packaging for distribution — see Data Preparation.

What should not be in the data directory¶

The validator reports these as warnings. None of them break the application; they inflate the directory and confuse its purpose.

Directory layout at a glance¶

data/
├── datapack.gpkg                  # REQUIRED — hardcoded filename
├── metadata.csv                   # REQUIRED — indicator metadata, keyed on ColumnName
├── NPP_by_treecover.csv           # REQUIRED — lookup, needs catchID
├── deltaSOC_bytcc_Mgha.csv        # REQUIRED — lookup, needs catchID
├── herb_traits_ready.csv          # REQUIRED — herbivore traits
├── mbtiles/
│   ├── africa.mbtiles             # REQUIRED — must be named "africa"
│   └── style.json                 # map style, served via /data/style.json
├── sites/                         # runtime: site JSON (desktop runtime)
├── images/                        # runtime: site thumbnails
├── walkthroughs/*.json            # optional: demo sites for the guided tours
├── demo/                          # optional: tour assets
│
├── catchments.gpkg                # pipeline input — not read at runtime
├── current*.csv                   # pipeline input — not read at runtime
├── reference*.csv                 # pipeline input — not read at runtime
│
└── R scripts/                     # DOES NOT BELONG — move to version control

Related¶

• Validating the Data Directory — the automated checks
• Data Setup — installing a data pack as an end user
• Data Preparation — building a data pack
• Datapack Format — the distributable archive format