Configuration Reference
YAML files drive both embedding generation and analysis. Each config specifies the data source, model, extraction strategies, and analysis steps. Create YAML files with unique, descriptive names (e.g., configs/exp001_prithvi300.yaml).
See tests/fixtures/example_config.yaml for a minimal working example.
Full annotated config
# --- Metadata ---
experiment_name: "My Experiment" # used in plot titles
data_version: "v1.0" # subdirectory name for inputs/outputs
chip_tracker: "gelos_chip_tracker.geojson" # metadata file, relative to data_root
chip_id_column: "id" # column in chip tracker used to index chips
# --- Data ---
data:
class_path: gelos.gelosdatamodule.GELOSDataModule
init_args:
dataset_class: myproject.mydataset.MyGELOSDataSet # import path to your subclass
batch_size: 1
num_workers: 0
# bands to load for each sensor — keys must match sensors defined in your
# dataset class's all_band_names dict, and values must be subsets of the
# band names defined there. You can include any combination of sensors.
bands:
S2L2A: [blue, green, red, nir08, swir16, swir22]
DEM: [DEM]
# optional: repeat static (single-timestep) modalities along the temporal
# axis so all sensors have the same number of timesteps, as required by
# some models (e.g., Terramind expects matching temporal dimensions)
repeat_bands:
DEM: 4
# optional: add Gaussian noise to specific bands for ablation experiments.
# the float value controls the noise weight (0 = no noise, 1 = full noise)
# perturb_bands:
# S2L2A:
# blue: 0.1
# optional: disable z-score normalization entirely (default true). Set to
# false for backbones that apply their own pretraining normalization
# internally (e.g. OlmoEarth) so the model receives raw sensor values.
# normalize: false
# optional: convert linear-power bands to decibels at load time
# (10 * log10(clip(x, 1e-10))), e.g. for models pretrained on dB-scale S1.
# Do NOT combine with OlmoEarth's built-in normalization (see below).
# db_scale_bands:
# S1RTC: [VV, VH]
# optional: remap on-disk nodata pixels AFTER normalization, so the model
# receives set_nodata (not a normalized sentinel). Scalars apply to all
# modalities; dicts ({S2L2A: -999}) apply per modality. Must be set together;
# for recognized models (Prithvi, TerraMind, OlmoEarth) set_nodata is
# auto-filled with the model's default (0) whenever nodata_value is set.
# For OlmoEarth, nodata_value also drives the encoder's input mask: nodata
# patches are dropped from attention and pooling (see the OlmoEarth notes).
# nodata_value: -999
# set_nodata: 0
# albumentations / terratorch transforms applied to each chip.
# FlattenTemporalIntoChannels and UnflattenTemporalFromChannels are needed
# to apply spatial transforms across all timesteps.
transform:
- class_path: terratorch.datasets.transforms.FlattenTemporalIntoChannels
- class_path: albumentations.pytorch.transforms.ToTensorV2
- class_path: terratorch.datasets.transforms.UnflattenTemporalFromChannels
init_args:
n_timesteps: 4 # must match number of timesteps in your data
# --- Model ---
# See terratorch documentation for available models and their expected band names.
# Note: model band names may differ from your dataset band names (e.g., NIR_NARROW
# vs nir08) — the model_args bands must match what the model expects.
model:
class_path: terratorch.tasks.EmbeddingGenerationTask
init_args:
model: prithvi_eo_v2_300 # terratorch model identifier
model_args:
bands: [BLUE, GREEN, RED, NIR_NARROW, SWIR_1, SWIR_2]
pretrained: true
output_format: parquet
embed_file_key: filename
layers: [-1] # which transformer layers to extract; -1 = last
embedding_pooling: null # null keeps full token sequence
has_cls: true # whether the model produces a CLS token at position 0
# e.g., Prithvi EO V2 does, Terramind V1 does not
# --- Embedding Extraction Strategies ---
# Each key is a user-defined name for a strategy. This name is used in output
# file naming (e.g., "cls_token" → exp001_cls_token_layer-1_tsne.csv).
# You can define as many strategies as you like — each one slices the embedding
# differently and can run its own set of transforms, plots, and models.
#
# slice_args controls which tokens to extract from the embedding sequence.
# Each dict applies pyarrow list_slice(start, stop, step) then flattens.
# Multiple dicts are applied sequentially for nested structures.
embedding_extraction_strategies:
cls_token: # your name for this strategy
title: "CLS Token" # display title for plots
slice_args:
- start: 0 # extract only the first token (CLS)
stop: 1
step: 1
# Available transforms: tsne, pca, umap
transforms:
- type: tsne
- type: pca
params:
n_components: 2
# Available plots: scatter_2d
plots:
- type: scatter_2d
transform: umap # which transform result to plot
params:
axis_lim: 120 # optional plot params
# Available models: knn, linear_probe, random_forest
# "transform" selects input data — use "raw" for untransformed embeddings,
# or the name of a transform defined above (e.g., "pca")
models:
- type: knn
transform: raw
params:
n_neighbors: 5
# Available metrics: pca_ablation, knn_purity, knn_geo_distance
# Metrics run on the raw embeddings and write one CSV per metric that the
# comparison stage joins across experiments.
metrics:
- type: knn_geo_distance
params:
k_values: [1, 5, 10, 50]
# --- Style ---
# Maps category values to colors and labels for plotting.
# category_column must match a column in your chip tracker / metadata.
style:
category_column: "lulc"
colors:
"1": "#419bdf"
"2": "#397d49"
labels:
"1": "Water"
"2": "Trees"
Config sections
Metadata
| Field | Purpose |
|---|---|
experiment_name |
Human-readable name, shown in plot titles |
data_version |
Used as a subdirectory name to organize inputs and outputs (e.g., data/raw/v1.0/) |
chip_tracker |
Path to your metadata file, relative to data_root / data_version |
chip_id_column |
Column name in the chip tracker used to index chips and cross-reference with embeddings |
Data
| Field | Purpose |
|---|---|
dataset_class |
Python import path to your GELOSDataSet subclass |
bands |
Dict of {sensor: [band_names]}. Keys must match sensors in your class's all_band_names, values must be subsets of those band lists |
repeat_bands |
Optional. Repeat static modalities (e.g., DEM) along the temporal axis to match the number of timesteps of other sensors |
perturb_bands |
Optional. Add Gaussian noise for ablation experiments. Format: {sensor: {band: weight}} where weight ranges from 0 (no noise) to 1 (full noise) |
means / stds |
Optional. Per-modality/band normalization statistics: {sensor: {band: value}}. Resolution order per band: these explicit args → model-matched pretraining stats injected by gelos.generation (see below) → lowercase means/stds class attributes on the dataset class → uppercase MEANS/STDS class attributes → default (mean 0.0, std 1.0). If an entire modality resolves to the defaults, normalization is an identity and a loud warning is logged |
normalize |
Optional, default true. Set to false to skip z-score normalization entirely (identity aug) — for backbones that apply their own pretraining normalization internally, e.g. OlmoEarth (injected automatically for OlmoEarth models, see below) |
db_scale_bands |
Optional. Convert listed bands from linear power to decibels (10 * log10(clip(x, 1e-10))) at load time, e.g. {S1RTC: [VV, VH]}. Do not use together with OlmoEarth's built-in normalization, which already converts S1 to dB |
nodata_value |
Optional. On-disk nodata sentinel to detect, e.g. -999. A scalar applies to every modality; a {modality: value} dict (e.g. {S2L2A: -999}) masks only its listed modalities. Must be set together with set_nodata (auto-filled for recognized models, see below). Detection happens on the raw batch, before normalization; combining a masked modality with db_scale_bands or perturb_bands on the same bands corrupts the sentinel before detection and logs a warning. For OlmoEarth the detected mask is also passed to the encoder as an input mask (see the OlmoEarth notes) |
set_nodata |
Optional. Value the model receives at nodata positions, e.g. 0. Written AFTER normalization, so the model sees exactly this value (not a normalized sentinel). A scalar, or a {modality: value} dict covering every masked modality. Must be set together with nodata_value. For recognized models (gelos.normalization: Prithvi EO V2, TerraMind v1, OlmoEarth) the default 0 is injected automatically whenever nodata_value is set and set_nodata is not — after z-scoring 0 is the band mean; for OlmoEarth raw DN 0 is mapped in-range by its min-max normalizer and only matters for partially-nodata patches below the mask threshold. nodata_value itself is never injected (only the dataset knows its sentinel) |
Model-matched normalization defaults. For recognized backbones, gelos.generation
automatically fills any of means/stds/db_scale_bands/normalize you did not set,
using the model's own pretraining statistics (gelos.normalization): Prithvi EO V2 and
TerraMind v1 get their published pretraining means/stds (TerraMind's S1 stats are in dB, so
db_scale_bands: {S1RTC: [VV, VH]} is injected alongside), and OlmoEarth gets
normalize: false because its backbone normalizes internally. Rationale: frozen encoders
should see inputs distributed the way they were pretrained — dataset statistics are the
fallback for models without registered stats, and anything you set explicitly in the config
always wins. A registered model combined with a band it was not pretrained on (e.g. Prithvi
with COASTAL_AEROSOL) raises an error; override with explicit means/stds if intended.
| transform | Albumentations/TerraTorch transforms. Use FlattenTemporalIntoChannels/UnflattenTemporalFromChannels to apply spatial transforms across timesteps |
Model
| Field | Purpose |
|---|---|
model |
TerraTorch model identifier (e.g., prithvi_eo_v2_300, prithvi_eo_v2_600, prithvi_eo_v2_300_tl_coords (also tiny/100/600 TL siblings; see Prithvi TL below), terramind_v1_base, olmoearth_v1_2_base, olmoearth_v1_2_base_s1s2; the olmoearth_v1_* identifiers are deprecated) |
model_args.bands |
Band names as the model expects them (may differ from your dataset band names) |
model_args.bands_s1 |
S1 band names for OlmoEarth S1+S2 models (e.g., [VV, VH]). Omit or set to null to disable S1. |
model_args.mask_nodata |
OlmoEarth only. Default true: when data.init_args.nodata_value is set, nodata patches are masked out of the encoder (see Nodata masking below). Set false to feed set_nodata values through unmasked |
model_args.nodata_patch_threshold |
OlmoEarth only. Fraction in [0, 1] (default 0) of nodata pixels (any band, per timestep) at or above which a patch_size × patch_size patch is masked. 0 masks any patch touching nodata; 1.0 masks only fully-nodata patches |
layers |
Which transformer layers to extract embeddings from. -1 means the last layer |
embedding_pooling |
Set to null to keep the full token sequence |
has_cls |
Whether the model produces a CLS token at position 0 |
OlmoEarth (olmoearth_v1_2_base, olmoearth_v1_2_base_s1s2, and size variants)
Ai2's OlmoEarth is supported as a
terratorch-compatible backbone via a wrapper in gelos/backbones/olmoearth_backbone.py,
which registers itself automatically when gelos.generation is imported. No file
placement is required — install the extra and use the model identifiers directly.
The supported generation is v1.2, with sizes nano (D=128), tiny (D=192),
small (D=384), and base (D=768). Each size has a Sentinel-2-only variant and a
combined S2+S1 variant:
| Model identifier | Sensors | Hidden dim |
|---|---|---|
olmoearth_v1_2_nano |
S2 only | 128 |
olmoearth_v1_2_tiny |
S2 only | 192 |
olmoearth_v1_2_small |
S2 only | 384 |
olmoearth_v1_2_base |
S2 only | 768 |
olmoearth_v1_2_nano_s1s2 |
S2 + S1 | 128 |
olmoearth_v1_2_tiny_s1s2 |
S2 + S1 | 192 |
olmoearth_v1_2_small_s1s2 |
S2 + S1 | 384 |
olmoearth_v1_2_base_s1s2 |
S2 + S1 | 768 |
The earlier v1 generation (sizes nano, tiny, base, large D=1024; no
small) is deprecated: its factories still work for the full 12-band input but
emit a DeprecationWarning and will be removed in a future release. v1.2 reuses
v1's band order and pretraining normalization statistics unchanged, so switching
is a rename (olmoearth_v1_large* has no v1.2 counterpart; use olmoearth_v1_2_base*):
| Model identifier (deprecated) | Sensors | Hidden dim |
|---|---|---|
olmoearth_v1_nano |
S2 only | 128 |
olmoearth_v1_tiny |
S2 only | 192 |
olmoearth_v1_base |
S2 only | 768 |
olmoearth_v1_large |
S2 only | 1024 |
olmoearth_v1_nano_s1s2 |
S2 + S1 | 128 |
olmoearth_v1_tiny_s1s2 |
S2 + S1 | 192 |
olmoearth_v1_base_s1s2 |
S2 + S1 | 768 |
olmoearth_v1_large_s1s2 |
S2 + S1 | 1024 |
Notes and limitations:
- Included in core install. OlmoEarth support ships with gelos — no extra
install step required beyond
pip install gelos. - Sentinel-2 L2A bands; subsets are zero-filled (v1.2). The wrapper reorders
the input channels to OlmoEarth's expected 12-band S2L2A order
(
B02,B03,B04,B08,B05,B06,B07,B8A,B11,B12,B01,B09).model_args.bandslists the bands in the order the tensor presents them and must matchdata.bands.S2L2Aexactly (same names, same order); an unknown band name raises a clearValueError. With a v1.2 checkpointmodel_args.bandsmay be a subset of the 12 bands (e.g. a 10-band dataset withoutCOASTAL_AEROSOL/ B01 andWATER_VAPOR/ B09): each absent band's channel is set to exactly0after pretraining normalization, for the whole sample, which is what v1.2's pretraining band dropout fed the encoder, so it infers the missing bands from the present ones. Construction logs one warning naming the zero-filled bands, and a stronger one when more than 3 bands are absent (pretraining dropped about 10% of bands on average, so a 6-band subset is far outside that regime; it is never an error). Nodata masking is unaffected. Deprecated v1 checkpoints have no band dropout and still require all 12 bands (a subset raises). Seeconfigs/olmoearth_v1_2_base.yaml. - Sentinel-1 support (S1+S2 models). Pass
model_args.bands_s1: [VV, VH]and addS1RTC: [VV, VH]todata.bandsto enable S1. The S1 tensor is fused with the S2 embedding via equal-weight averaging. Backward compatibility: omittingbands_s1(or the S2-only model variants) requires no changes to existing configs. Seeconfigs/olmoearth_v1_2_base_s1s2.yaml. - Built-in pretraining normalization
(
model_args.apply_pretraining_normalization, defaulttrue). OlmoEarth's encoder performs no normalization itself — during pretraining its data loader normalized inputs. The wrapper replicates that exactly: S1 linear power is clipped at1e-10, converted to dB (10*log10), then min-max scaled per band overmean±2σ; S2 raw DN (0–10000) is min-max scaled per band overmean±2σ(no log). Stats come fromolmoearth_pretrain'scomputed.json. Inputs must therefore be RAW sensor scale (S1 linear-power gamma0, S2 L2A digital numbers): setnormalize: falseunderdata.init_argsand do not applydb_scale_bandsto S1, or values get double-transformed. Setapply_pretraining_normalization: falseonly if you pre-normalize inputs to OlmoEarth's pretraining scale yourself. - Temporal pooling (
model_args.temporal_pooling). The OlmoEarth encoder outputs one token per (spatial patch × timestep); the wrapper controls what happens to the time axis.mean(default) averages over timesteps, returning(B, H'*W', D).keeppreserves per-timestep tokens flattened time-major to(B, T*H'*W', D)— tokent*H'*W' + iis spatial patchiat timestept— so stridedslice_argscan extract single-timestep vs. all-timestep features, matching the Prithvi token layout. Note that withkeep, a single timestep's tokens still come from one joint space-time attention pass over all timesteps. - Spatial pooling (
model_args.spatial_pooling). Optional (default off). An integer factors: after encoding, theH'×W'token grid is average-pooled over non-overlappings×sneighborhoods, so each output token covers(s*patch_size)²input pixels. Use it to match the spatial footprint of larger-patch models — e.g.patch_size: 4, spatial_pooling: 4yields tokens covering 16×16 pixels whose grid and indices line up exactly with Prithvi/TerraMind's 16-pixel patches, so the sameslice_argsstrategies apply across models. The stringmean: the whole token grid is mean-pooled per timestep (over valid tokens only, see Nodata masking), so every sample yields the same-size vector regardless of its nodata footprint —(B, T, D)withtemporal_pooling: keep,(B, 1, D)withtemporal_pooling: mean. Encoding still runs at the finepatch_size; only the output tokens are aggregated. - Nodata masking (
model_args.mask_nodata, defaulttrue). Whendata.init_args.nodata_valueis set, the datamodule's raw-batch nodata mask is passed to the OlmoEarth backbone (asbatch["nodata_mask"], popped by the generation task). Eachpatch_size × patch_sizepatch whose fraction of nodata pixels — in any band, per timestep — is above zero (or at or abovemodel_args.nodata_patch_thresholdif set to a value in(0, 1]; default0, i.e. any nodata pixel) is flaggedMISSINGfor the encoder: those tokens are removed before attention (they neither attend nor are attended to) and excluded from every pooling mean (band-set, S1/S2 fusion — a patch valid in only one modality keeps that modality's token alone — spatial and temporal). Consequences to be aware of: masked positions in un-pooled grids come back as zero vectors (stridedslice_argsmay select them); a pooled position whose window has no valid token is a zero vector and logs a warning; a sample with no valid patch at all is encoded unmasked with a warning (the encoder cannot process an empty sequence); and a batch containing any masked patch runs the encoder without itsfast_passshortcut, which is slower. Minimal config:
yaml
data:
init_args:
nodata_value: -999 # set_nodata: 0 is auto-filled for OlmoEarth
model:
init_args:
model: olmoearth_v1_2_base
model_args:
spatial_pooling: mean # one vector per timestep, same size for every chip
temporal_pooling: keep
nodata_patch_threshold: 0 # any nodata pixel masks the patch
- Timestamps. Datasets opt in to real acquisition dates by overriding
GELOSDataSet._get_timestamps(index), returning a (T, 3) integer array of
canonical calendar dates [year, month, day] (month 1–12) — one row per
timestep of the primary temporal sensor (S2 for OlmoEarth). The value flows
automatically into batch["timestamps"] (B, T, 3) and from there into any
backbone exposing set_batch_timestamps. Each backbone converts internally
to its own layout — OlmoEarth reindexes to its [day, month_index, year]
packing at consumption time — so datasets never encode a backbone-specific
format. When the hook is not overridden (the default), OlmoEarth falls back
to the constant dummy date [15, 0, 2020] (day=15, month=Jan, year=2020;
unchanged behavior), and acquisition-date-dependent temporal encoding will
not reflect true seasonality. Timestamps whose shape does not match the
input's (B, T, 3) emit a warning and fall back to the constant date.
- Location. Datasets opt in to chip location by overriding
GELOSDataSet._get_location(index), returning a (2,) float array
[lat, lon] in decimal degrees (one footprint per chip). The value flows
into batch["location"] (B, 2) and is dispatched generically to any
backbone exposing set_batch_location. It is consumed by the Prithvi TL
wrapper (prithvi_eo_v2_*_tl_coords, see below), which feeds it to the
encoder as location_coords (B, 2) and raises if it is missing. When the
hook is not overridden the key is absent and behavior is unchanged for every
other backbone.
Prithvi TL (prithvi_eo_v2_*_tl_coords)
Prithvi EO v2 ships "TL" checkpoints whose encoder adds sinusoidal temporal
([year, day_of_year]) and location ([lat, lon]) embeddings to every patch
token, giving a comparison axis against plain Prithvi. gelos exposes them through
a wrapper in gelos/backbones/prithvi_tl_backbone.py (registered automatically
when gelos.generation is imported) under four identifiers:
| Model identifier | Checkpoint |
|---|---|
prithvi_eo_v2_tiny_tl_coords |
ibm-nasa-geospatial/Prithvi-EO-2.0-tiny-TL |
prithvi_eo_v2_100_tl_coords |
ibm-nasa-geospatial/Prithvi-EO-2.0-100M-TL |
prithvi_eo_v2_300_tl_coords |
ibm-nasa-geospatial/Prithvi-EO-2.0-300M-TL |
prithvi_eo_v2_600_tl_coords |
ibm-nasa-geospatial/Prithvi-EO-2.0-600M-TL |
Notes:
- Use the
_coordsnames, not terratorch's stockprithvi_eo_v2_300_tl. terratorch's TL encoders only apply the time/location embeddings whentemporal_coords/location_coordsare passed explicitly, and the embedding task calls the backbone with the image alone — so the stock names run in gelos but silently drop the TL signal. The_coordswrapper receives the side-channel and forwards it; the names still start withprithvi_eo_v2, so Prithvi's pretrainingmeans/stdsare injected as for plain Prithvi. - Both dataset hooks are required; no silent fallback. The dataset must
override
_get_timestampsand_get_location(see Timestamps and Location above). If eitherbatch["timestamps"]orbatch["location"]is missing, or shapes do not match the input, generation raises aValueErrornaming the missing key and hook. - Date conversion. Canonical
[year, month, day]timestamps are converted at consumption time to Prithvi's[year, day_of_year](1-based, Gregorian leap years) bycalendar_to_prithvi_temporal_coords. temporal_wrapper: truerecommended. UnderTemporalWrappereach timestep is encoded on its own (CLS at index 0), matching the plain Prithvi token layout, so the sameslice_argsapply to both arms of the comparison (configs/prithvi_eo_v2_300_tl.yamlvs.configs/prithvi_eo_v2_300.yaml). Withtemporal_wrapper: false(joint space-time encoding, 5D input) the number of timesteps must equalmodel_args.num_frames; a mismatch raises.
Embedding extraction strategies
Each key under embedding_extraction_strategies is a user-defined name that becomes part of output file names. Within each strategy:
title: Display name used in plot titlesslice_args: List of slice operations applied sequentially to extract tokens from the embedding. Each operation usesstart,stop,step(PyArrowlist_slicesemantics). Use multiple entries for nested structures.transforms: Optional list of transforms to run on extracted embeddingsplots: Optional list of plots to generatemodels: Optional list of classification models to runmetrics: Optional list of analysis metrics to compute on the raw embeddings (each writes a CSV consumed by the comparison stage)
Available transforms:
| Type | Description | Key params |
|---|---|---|
tsne |
t-SNE dimensionality reduction | n_components (default 2), perplexity (default 50), max_iter (default 1000) |
pca |
PCA dimensionality reduction | n_components (int for fixed, float for variance threshold; default 0.95) |
pca |
UMAP dimensionality reduction | n_components (default 2) |
Available plots:
| Type | Description | Key params |
|---|---|---|
scatter_2d |
Scatter plot colored by category | axis_lim (default 120), legend_loc (default "upper left") |
Available models:
| Type | Description | Key params |
|---|---|---|
knn |
K-nearest neighbors with stratified k-fold CV | n_neighbors (default 5), n_splits (default 5) |
linear_probe |
Logistic regression with stratified k-fold CV | max_iter (default 1000), n_splits (default 5) |
random_forest |
Random forest with repeated stratified k-fold CV | n_estimators (default 100), n_splits (default 5), n_repeats (default 3) |
Available metrics (always computed on the raw embeddings; outputs are cached as
{prefix}_{metric}.csv under the processed layer directory):
| Type | Description | Key params |
|---|---|---|
pca_ablation |
Number of PCA components needed to reach each cumulative-variance threshold | variance_thresholds (default [0.8, 0.85, 0.9, 0.95, 0.99]) |
knn_purity |
Fraction of each chip's k nearest embedding neighbours sharing its class, overall and per class. Requires class labels (style.category_column) |
k_values (default [1, 2, 5, 10, 20, 50]), n_subsample (stratified query subsample) |
knn_geo_distance |
Mean geographic distance between each chip and its k nearest embedding neighbours, aggregated over all chips (class-agnostic — works without chip-level labels). Two measures per k: gsd_m, the great-circle (haversine) distance between chip centres in metres, and lat_diff_deg, the absolute latitude difference in degrees. Needs chip coordinates: the geometry of a .geojson tracker (reprojected to EPSG:4326, centre = bounds midpoint) or lat/lon (or latitude/longitude) columns in a .csv tracker. Writes {prefix}_knn_geo_distance.csv (k, measure, mean, median, q1, q3, n_samples) and {prefix}_knn_geo_distance_per_query.csv (k, query_idx, chip_id, gsd_m, lat_diff_deg) |
k_values (default [1, 2, 5, 10, 20, 50]), n_subsample (uniform query subsample) |
For plots and models, the transform field selects which data to use as input: "raw" for the untransformed embeddings, or the name of a transform defined in the same strategy (e.g., "tsne", "pca").
Style
Maps category values from your metadata to colors and labels for plotting. category_column must match a column accessible via chip_gdf[category_column].loc[chip_indices] in the analysis pipeline.
Comparison plots
Comparison configs may list comp_plots, each with a type from the comparison
plot registry and an optional params block. Each plot reads the output of a
comparison metric; by default the source metric is derived from the plot type
(stripping the _plot/_table suffix), but it can be set explicitly with a
metric field — required when the names don't match.
| Type | Description | Key params |
|---|---|---|
knn_purity_distribution_plot |
Per-class box plots of per-query KNN purity vs k | (none) |
knn_purity_violin_distribution_plot |
Per-class violin plots of per-query KNN purity vs k. Split violin (one half per group) when exactly two experiments are compared, otherwise side-by-side single violins. Mean shown as a diamond, median as a short line | split (bool, default auto: split iff exactly two experiments). split_pairs (list of 2-element experiment-name lists; each pair → one split violin per k; unpaired experiments → single violins; takes precedence over split). Requires metric: knn_purity_per_query_comparison |
knn_gsd_plot |
Single panel: mean ground surface distance (km, haversine between chip centres) to the k nearest embedding neighbours vs k, one line per experiment | show_iqr (bool, default false: shade the q1–q3 band), log_x (bool, default false). Requires metric: knn_geo_distance_comparison |
knn_lat_diff_plot |
Single panel: mean absolute latitude difference (degrees) to the k nearest embedding neighbours vs k, one line per experiment | show_iqr, log_x as above. Requires metric: knn_geo_distance_comparison |
All kNN plots use a fixed layout: figure size depends only on the facet grid shape,
the legend is stacked one entry per line in a fixed band below the plots (room for
four experiments), and files are saved at a fixed dpi so images of the same grid
shape are pixel-identical in size. Legend labels are shown in full: a prefix common
to all experiments is stripped, but nothing is truncated, so choose experiment
labels that fit the figure width (roughly 60 characters is safe for the
single-panel and multi-column grids; narrower single-column grids fit fewer, and
longer labels run off the sides of the fixed canvas).
Example:
comp_plots:
- type: knn_purity_violin_distribution_plot
metric: knn_purity_per_query_comparison
params:
split: true
The geographic-distance plots read the knn_geo_distance_comparison metric, which
joins the per-experiment knn_geo_distance CSVs (so every compared experiment must
list knn_geo_distance under its strategy metrics). Both plots take the same
metric; the metric field is required because the plot names do not match it:
comp_metrics:
- type: knn_geo_distance_comparison
comp_plots:
- type: knn_gsd_plot
metric: knn_geo_distance_comparison
params:
show_iqr: true
log_x: true
- type: knn_lat_diff_plot
metric: knn_geo_distance_comparison
To contrast several pairs of experiments as side-by-side split violins (for
example multitemporal vs single-time-step variants of two models), use
split_pairs. Each inner list names the two experiments of one split violin;
any experiment not named in a valid pair is drawn as a single violin. When
split_pairs is set it takes precedence over split:
comp_plots:
- type: knn_purity_violin_distribution_plot
metric: knn_purity_per_query_comparison
params:
split_pairs:
- [model_A_multi, model_A_single]
- [model_B_multi, model_B_single]
Spectral-band baseline configs
Randomly-initialized (or mis-pretrained) foundation-model weights can still produce embedding spaces that look reasonable on downstream probes. To sanity-check how much a model is actually contributing, GELOS ships gelos.spectral_bands.SpectralBandsEmbeddingTask — a passthrough task that skips the model entirely and writes the normalized spectral band values themselves as "embeddings". The output parquets match EmbeddingGenerationTask's schema, so analysis and comparison stages consume them with no special-casing.
Swap the model block for the raw task and add a top-level spectral_band_extraction section:
model:
class_path: gelos.spectral_bands.SpectralBandsEmbeddingTask
title: "Spectral Bands Baseline"
init_args:
patch_size: 16
embed_file_key: filename
# Each named entry becomes a per-strategy subdir under the run's output_dir
# (playing the role of a "layer" for analysis). The product of
# len(timesteps) * len(patches) must be <= 4 — spectral band tokens are high-dim,
# so the cap keeps parquet sizes reasonable.
spectral_band_extraction:
center_2x2_t0:
title: "Center 2x2 patches, single timestep"
patches: center_2x2 # 'center_NxN' or an explicit list of [row, col] pairs
timesteps: [0] # list of ints or the string 'all'
all_timesteps_center_patch:
title: "All timesteps of the center patch"
patches: center_1x1
timesteps: all
Notes:
- Normalization is reused from the datamodule. The task trusts
GELOSDataModule.aug(defaults to z-score via means/stds) — set real per-band statistics on your dataset class (means/stdsorMEANS/STDSattributes) or indata.init_args.means/stds, or baseline pixels stay un-normalized (the datamodule logs a loud warning when a modality resolves entirely to default stats). - Patch grid is derived from
H, W, patch_size, not configured. All ofH,Wmust be divisible bypatch_size, and for multi-sensor configs all sensors must shareT,H,Wafter normalization (userepeat_bandsto align single-timestep modalities like DEM). - Multi-modal runs channel-concatenate per token. Do NOT set
concat_bands: Trueon the datamodule — the task handles concat itself. Sensor order followsdata.bandsYAML key order, which becomes the dict iteration order. Reordering that block between runs produces parquets of the same shape but different channel layouts. - Comparison workflow. Each modality combination is its own generation config (
spectral_s2.yaml,spectral_s2s1dem.yaml, etc.) with its owndata.bandsand its ownspectral_band_extraction. Comparison configs reference spectral-band runs by the same(config, strategy, layer)triple as any model run. S2 pixels getting written twice is bounded (~kB/chip per run at the 4-token cap).
embedding_extraction_strategies still applies on top — each spectral-band subdir becomes a "layer" for analysis, and each embedding-extraction strategy runs its slice/transforms/plots/models against it.