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.bands lists the bands in the order the tensor presents them and must match data.bands.S2L2A exactly (same names, same order); an unknown band name raises a clear ValueError. With a v1.2 checkpoint model_args.bands may be a subset of the 12 bands (e.g. a 10-band dataset without COASTAL_AEROSOL / B01 and WATER_VAPOR / B09): each absent band's channel is set to exactly 0 after 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). See configs/olmoearth_v1_2_base.yaml.
  • Sentinel-1 support (S1+S2 models). Pass model_args.bands_s1: [VV, VH] and add S1RTC: [VV, VH] to data.bands to enable S1. The S1 tensor is fused with the S2 embedding via equal-weight averaging. Backward compatibility: omitting bands_s1 (or the S2-only model variants) requires no changes to existing configs. See configs/olmoearth_v1_2_base_s1s2.yaml.
  • Built-in pretraining normalization (model_args.apply_pretraining_normalization, default true). OlmoEarth's encoder performs no normalization itself — during pretraining its data loader normalized inputs. The wrapper replicates that exactly: S1 linear power is clipped at 1e-10, converted to dB (10*log10), then min-max scaled per band over mean±2σ; S2 raw DN (0–10000) is min-max scaled per band over mean±2σ (no log). Stats come from olmoearth_pretrain's computed.json. Inputs must therefore be RAW sensor scale (S1 linear-power gamma0, S2 L2A digital numbers): set normalize: false under data.init_args and do not apply db_scale_bands to S1, or values get double-transformed. Set apply_pretraining_normalization: false only 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). keep preserves per-timestep tokens flattened time-major to (B, T*H'*W', D) — token t*H'*W' + i is spatial patch i at timestep t — so strided slice_args can extract single-timestep vs. all-timestep features, matching the Prithvi token layout. Note that with keep, 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 factor s: after encoding, the H'×W' token grid is average-pooled over non-overlapping s×s neighborhoods, 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: 4 yields tokens covering 16×16 pixels whose grid and indices line up exactly with Prithvi/TerraMind's 16-pixel patches, so the same slice_args strategies apply across models. The string mean: 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) with temporal_pooling: keep, (B, 1, D) with temporal_pooling: mean. Encoding still runs at the fine patch_size; only the output tokens are aggregated.
  • Nodata masking (model_args.mask_nodata, default true). When data.init_args.nodata_value is set, the datamodule's raw-batch nodata mask is passed to the OlmoEarth backbone (as batch["nodata_mask"], popped by the generation task). Each patch_size × patch_size patch whose fraction of nodata pixels — in any band, per timestep — is above zero (or at or above model_args.nodata_patch_threshold if set to a value in (0, 1]; default 0, i.e. any nodata pixel) is flagged MISSING for 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 (strided slice_args may 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 its fast_pass shortcut, 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 _coords names, not terratorch's stock prithvi_eo_v2_300_tl. terratorch's TL encoders only apply the time/location embeddings when temporal_coords / location_coords are 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 _coords wrapper receives the side-channel and forwards it; the names still start with prithvi_eo_v2, so Prithvi's pretraining means/stds are injected as for plain Prithvi.
  • Both dataset hooks are required; no silent fallback. The dataset must override _get_timestamps and _get_location (see Timestamps and Location above). If either batch["timestamps"] or batch["location"] is missing, or shapes do not match the input, generation raises a ValueError naming 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) by calendar_to_prithvi_temporal_coords.
  • temporal_wrapper: true recommended. Under TemporalWrapper each timestep is encoded on its own (CLS at index 0), matching the plain Prithvi token layout, so the same slice_args apply to both arms of the comparison (configs/prithvi_eo_v2_300_tl.yaml vs. configs/prithvi_eo_v2_300.yaml). With temporal_wrapper: false (joint space-time encoding, 5D input) the number of timesteps must equal model_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 titles
  • slice_args: List of slice operations applied sequentially to extract tokens from the embedding. Each operation uses start, stop, step (PyArrow list_slice semantics). Use multiple entries for nested structures.
  • transforms: Optional list of transforms to run on extracted embeddings
  • plots: Optional list of plots to generate
  • models: Optional list of classification models to run
  • metrics: 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/stds or MEANS/STDS attributes) or in data.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 of H, W must be divisible by patch_size, and for multi-sensor configs all sensors must share T, H, W after normalization (use repeat_bands to align single-timestep modalities like DEM).
  • Multi-modal runs channel-concatenate per token. Do NOT set concat_bands: True on the datamodule — the task handles concat itself. Sensor order follows data.bands YAML 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 own data.bands and its own spectral_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.