# dauvillc/motif architecture

> Architecture diagram of the GitHub repository dauvillc/motif, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dauvillc/motif
- Repository: https://github.com/dauvillc/motif

## Overview

MOTIF is a research framework for tropical-cyclone image interpolation from multiple geospatial sources. Its workflow prepares and splits satellite/weather data, loads flexible multi-source batches, and trains deterministic or flow-matching reconstructors that embed, mask, process, and reconstruct a source. Prediction and evaluation are separate user-facing stages. The README documents the end-to-end capabilities; source excerpts and the index substantiate selected implementation links, while some script internals and model wiring were not sampled.

Main entry points: [`src/motif/data/dataset.py`](https://github.com/dauvillc/motif/blob/main/src/motif/data/dataset.py) (Multi-source dataset), [`scripts/eval.py`](https://github.com/dauvillc/motif/blob/main/scripts/eval.py) (Evaluation runner), [`scripts/train.py`](https://github.com/dauvillc/motif/blob/main/scripts/train.py) (Training entrypoint), [`scripts/make_predictions.py`](https://github.com/dauvillc/motif/blob/main/scripts/make_predictions.py) (Prediction runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_prep["Data preparation"]
  node_downloads["Dataset downloads"]
  node_tcprep["TC-PRIMED preparation"]
  node_sarprep["SAR preparation<br/>[prepare_sar.py]"]
  node_era5prep["ERA5 download<br/>[dl_era5_64x32.py]"]
  node_splits["Dataset splits"]
  node_normalization["Normalization constants"]
end

subgraph group_data["Data loading"]
  node_dataset["Multi-source dataset<br/>[dataset.py]"]
  node_source["Source definitions<br/>[source.py]"]
  node_grid["Grid operations<br/>[grid_functions.py]"]
  node_collate["Batch collation<br/>[collate_fn.py]"]
  node_types["Batch data types<br/>[datatypes.py]"]
end

subgraph group_learn["Model and training"]
  node_train["Training entrypoint<br/>[train.py]"]
  node_reconstructor["Reconstruction module"]
  node_embedding["Source embeddings"]
  node_backbone["Multi-source backbone<br/>[backbone.py]"]
  node_deterministic["Deterministic learner<br/>[deterministic.py]"]
  node_flow["Flow-matching learner<br/>[flow_matching.py]"]
end

subgraph group_results["Prediction and evaluation"]
  node_predict["Prediction runner"]
  node_writer["Prediction writer<br/>[writer.py]"]
  node_eval["Evaluation runner<br/>[eval.py]"]
  node_metrics["Quantitative metrics<br/>[quantitative.py]"]
  node_visual["Evaluation visualizations"]
  node_spectral["Spectrum analysis<br/>[spectrum.py]"]
end

node_user(("Researcher"))
node_raw[("Raw datasets")]
node_prepared[("Prepared dataset")]

node_user -->|"requests data"| node_downloads
node_raw -->|"provides files"| node_downloads
node_downloads -->|"downloads sources"| node_raw
node_user -->|"prepares data"| node_tcprep
node_raw -->|"provides TC-PRIMED"| node_tcprep
node_raw -->|"provides SAR"| node_sarprep
node_raw -->|"provides ERA5"| node_era5prep
node_tcprep -->|"writes prepared data"| node_prepared
node_sarprep -->|"prepares SAR"| node_prepared
node_era5prep -->|"downloads ERA5"| node_raw
node_user -->|"creates splits"| node_splits
node_prepared -->|"splits samples"| node_splits
node_user -->|"computes statistics"| node_normalization
node_prepared -->|"reads samples"| node_normalization
node_prepared -->|"loads sources"| node_dataset
node_dataset -->|"uses source metadata"| node_source
node_dataset -->|"uses grid operations"| node_grid
node_dataset -.->|"supplies samples"| node_collate
node_collate -->|"builds batches"| node_types
node_user -->|"starts training"| node_train
node_train -.->|"loads batches"| node_dataset
node_train -->|"configures learner"| node_deterministic
node_train -->|"configures learner"| node_flow
node_deterministic -.->|"extends base"| node_reconstructor
node_flow -->|"extends base"| node_reconstructor
node_reconstructor -->|"embeds sources"| node_embedding
node_flow -->|"processes sequences"| node_backbone
node_user -->|"requests predictions"| node_predict
node_prepared -->|"provides inference data"| node_predict
node_predict -.->|"writes predictions"| node_writer
node_user -->|"requests evaluation"| node_eval
node_predict -->|"provides predictions"| node_eval
node_eval -->|"computes metrics"| node_metrics
node_eval -->|"generates visuals"| node_visual
node_eval -->|"compares spectra"| node_spectral

click node_downloads "https://github.com/dauvillc/motif/tree/main/preproc"
click node_tcprep "https://github.com/dauvillc/motif/tree/main/preproc/tc_primed"
click node_sarprep "https://github.com/dauvillc/motif/blob/main/preproc/sar/prepare_sar.py"
click node_era5prep "https://github.com/dauvillc/motif/blob/main/preproc/era5/dl_era5_64x32.py"
click node_splits "https://github.com/dauvillc/motif/blob/main/preproc/train_val_test_split.py"
click node_normalization "https://github.com/dauvillc/motif/blob/main/preproc/compute_normalization_constants.py"
click node_dataset "https://github.com/dauvillc/motif/blob/main/src/motif/data/dataset.py"
click node_source "https://github.com/dauvillc/motif/blob/main/src/motif/data/source.py"
click node_grid "https://github.com/dauvillc/motif/blob/main/src/motif/data/grid_functions.py"
click node_collate "https://github.com/dauvillc/motif/blob/main/src/motif/data/collate_fn.py"
click node_types "https://github.com/dauvillc/motif/blob/main/src/motif/datatypes.py"
click node_train "https://github.com/dauvillc/motif/blob/main/scripts/train.py"
click node_reconstructor "https://github.com/dauvillc/motif/blob/main/src/motif/lightning_module/base_reconstructor.py"
click node_embedding "https://github.com/dauvillc/motif/blob/main/src/motif/models/embedding_layers.py"
click node_backbone "https://github.com/dauvillc/motif/blob/main/src/motif/models/motif/backbone.py"
click node_deterministic "https://github.com/dauvillc/motif/blob/main/src/motif/lightning_module/deterministic.py"
click node_flow "https://github.com/dauvillc/motif/blob/main/src/motif/lightning_module/flow_matching.py"
click node_predict "https://github.com/dauvillc/motif/blob/main/scripts/make_predictions.py"
click node_writer "https://github.com/dauvillc/motif/blob/main/src/motif/data/writer.py"
click node_eval "https://github.com/dauvillc/motif/blob/main/scripts/eval.py"
click node_metrics "https://github.com/dauvillc/motif/blob/main/src/motif/eval/quantitative.py"
click node_visual "https://github.com/dauvillc/motif/blob/main/src/motif/eval/footprint_visualization.py"
click node_spectral "https://github.com/dauvillc/motif/blob/main/src/motif/eval/spectrum.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_downloads,node_tcprep,node_sarprep,node_era5prep,node_splits,node_normalization toneBlue
class node_dataset,node_source,node_grid,node_collate,node_types,node_raw,node_prepared toneAmber
class node_train,node_reconstructor,node_embedding,node_backbone,node_deterministic,node_flow toneMint
class node_predict,node_writer,node_eval,node_metrics,node_visual,node_spectral toneRose
class node_user toneIndigo
```

## Components

### Data preparation

- [Dataset downloads](https://github.com/dauvillc/motif/tree/main/preproc): `preproc`
- [TC-PRIMED preparation](https://github.com/dauvillc/motif/tree/main/preproc/tc_primed): `preproc/tc_primed`
- [SAR preparation](https://github.com/dauvillc/motif/blob/main/preproc/sar/prepare_sar.py): `preproc/sar/prepare_sar.py`
- [ERA5 download](https://github.com/dauvillc/motif/blob/main/preproc/era5/dl_era5_64x32.py): `preproc/era5/dl_era5_64x32.py`
- [Dataset splits](https://github.com/dauvillc/motif/blob/main/preproc/train_val_test_split.py): `preproc/train_val_test_split.py`
- [Normalization constants](https://github.com/dauvillc/motif/blob/main/preproc/compute_normalization_constants.py): `preproc/compute_normalization_constants.py`

### Data loading

- [Multi-source dataset](https://github.com/dauvillc/motif/blob/main/src/motif/data/dataset.py): `src/motif/data/dataset.py`
- [Source definitions](https://github.com/dauvillc/motif/blob/main/src/motif/data/source.py): `src/motif/data/source.py`
- [Grid operations](https://github.com/dauvillc/motif/blob/main/src/motif/data/grid_functions.py): `src/motif/data/grid_functions.py`
- [Batch collation](https://github.com/dauvillc/motif/blob/main/src/motif/data/collate_fn.py): `src/motif/data/collate_fn.py`
- [Batch data types](https://github.com/dauvillc/motif/blob/main/src/motif/datatypes.py): `src/motif/datatypes.py`

### Model and training

- [Training entrypoint](https://github.com/dauvillc/motif/blob/main/scripts/train.py): `scripts/train.py`
- [Reconstruction module](https://github.com/dauvillc/motif/blob/main/src/motif/lightning_module/base_reconstructor.py): `src/motif/lightning_module/base_reconstructor.py`
- [Source embeddings](https://github.com/dauvillc/motif/blob/main/src/motif/models/embedding_layers.py): `src/motif/models/embedding_layers.py`
- [Multi-source backbone](https://github.com/dauvillc/motif/blob/main/src/motif/models/motif/backbone.py): `src/motif/models/motif/backbone.py`
- [Deterministic learner](https://github.com/dauvillc/motif/blob/main/src/motif/lightning_module/deterministic.py): `src/motif/lightning_module/deterministic.py`
- [Flow-matching learner](https://github.com/dauvillc/motif/blob/main/src/motif/lightning_module/flow_matching.py): `src/motif/lightning_module/flow_matching.py`

### Prediction and evaluation

- [Prediction runner](https://github.com/dauvillc/motif/blob/main/scripts/make_predictions.py): `scripts/make_predictions.py`
- [Prediction writer](https://github.com/dauvillc/motif/blob/main/src/motif/data/writer.py): `src/motif/data/writer.py`
- [Evaluation runner](https://github.com/dauvillc/motif/blob/main/scripts/eval.py): `scripts/eval.py`
- [Quantitative metrics](https://github.com/dauvillc/motif/blob/main/src/motif/eval/quantitative.py): `src/motif/eval/quantitative.py`
- [Evaluation visualizations](https://github.com/dauvillc/motif/blob/main/src/motif/eval/footprint_visualization.py): `src/motif/eval/footprint_visualization.py`
- [Spectrum analysis](https://github.com/dauvillc/motif/blob/main/src/motif/eval/spectrum.py): `src/motif/eval/spectrum.py`

### Other components

- **Researcher**
- **Raw datasets**
- **Prepared dataset**

## Connections

- Researcher → Dataset downloads: requests data (evidence: `README.md`)
- Raw datasets → Dataset downloads: provides files (evidence: `README.md`)
- Dataset downloads → Raw datasets: downloads sources (evidence: `README.md`)
- Researcher → TC-PRIMED preparation: prepares data (evidence: `README.md`)
- Raw datasets → TC-PRIMED preparation: provides TC-PRIMED (evidence: `README.md`)
- Raw datasets → SAR preparation: provides SAR (evidence: `README.md`)
- Raw datasets → ERA5 download: provides ERA5 (evidence: `README.md`)
- TC-PRIMED preparation → Prepared dataset: writes prepared data (evidence: `preproc/tc_primed/prepare_pmw_concat.py`)
- SAR preparation → Prepared dataset: prepares SAR (evidence: `README.md`)
- ERA5 download → Raw datasets: downloads ERA5 (evidence: `README.md`)
- Researcher → Dataset splits: creates splits (evidence: `README.md`)
- Prepared dataset → Dataset splits: splits samples (evidence: `README.md`)
- Researcher → Normalization constants: computes statistics (evidence: `README.md`)
- Prepared dataset → Normalization constants: reads samples (evidence: `README.md`)
- Prepared dataset → Multi-source dataset: loads sources (evidence: `src/motif/data/dataset.py`)
- Multi-source dataset → Source definitions: uses source metadata (evidence: `src/motif/data/dataset.py`)
- Multi-source dataset → Grid operations: uses grid operations (evidence: `src/motif/data/dataset.py`)
- Multi-source dataset → Batch collation: supplies samples (evidence: `README.md`)
- Batch collation → Batch data types: builds batches (evidence: `src/motif/data/collate_fn.py`)
- Researcher → Training entrypoint: starts training (evidence: `README.md`)
- Training entrypoint → Multi-source dataset: loads batches (evidence: `README.md`)
- Training entrypoint → Deterministic learner: configures learner (evidence: `README.md`)
- Training entrypoint → Flow-matching learner: configures learner (evidence: `README.md`)
- Deterministic learner → Reconstruction module: extends base (evidence: `README.md`)
- Flow-matching learner → Reconstruction module: extends base (evidence: `src/motif/lightning_module/flow_matching.py`)
- Reconstruction module → Source embeddings: embeds sources (evidence: `src/motif/lightning_module/base_reconstructor.py`)
- Flow-matching learner → Multi-source backbone: processes sequences (evidence: `src/motif/lightning_module/flow_matching.py`)
- Researcher → Prediction runner: requests predictions (evidence: `README.md`)
- Prepared dataset → Prediction runner: provides inference data (evidence: `README.md`)
- Prediction runner → Prediction writer: writes predictions
- Researcher → Evaluation runner: requests evaluation (evidence: `README.md`)
- Prediction runner → Evaluation runner: provides predictions (evidence: `README.md`)
- Evaluation runner → Quantitative metrics: computes metrics (evidence: `README.md`)
- Evaluation runner → Evaluation visualizations: generates visuals (evidence: `README.md`)
- Evaluation runner → Spectrum analysis: compares spectra (evidence: `README.md`)
