# noaa-gfdl/mdtf-diagnostics architecture

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

- Interactive diagram: https://gitdiagram.com/noaa-gfdl/mdtf-diagnostics
- Repository: https://github.com/noaa-gfdl/mdtf-diagnostics

## Overview

MDTF-diagnostics is a framework for running independent process-oriented weather and climate diagnostics (PODs) on model data and producing figures viewable as HTML. The principal workflow starts with a user-supplied runtime configuration, prepares PODs and input data, executes eligible diagnostics, then organizes their outputs. The graph also preserves documented diagnostic capabilities and central framework utilities. Relationships are limited to calls or references visible in excerpts and the source index; unsampled diagnostic internals and runtime wiring are not inferred.

Main entry points: [`mdtf_framework.py`](https://github.com/noaa-gfdl/mdtf-diagnostics/blob/main/mdtf_framework.py) (Framework entry), [`src/preprocessor.py`](https://github.com/noaa-gfdl/mdtf-diagnostics/blob/main/src/preprocessor.py) (Preprocessor), [`diagnostics/stc_qbo_enso/stc_qbo_enso.py`](https://github.com/noaa-gfdl/mdtf-diagnostics/blob/main/diagnostics/stc_qbo_enso/stc_qbo_enso.py) (QBO and ENSO), [`src/data_sources.py`](https://github.com/noaa-gfdl/mdtf-diagnostics/blob/main/src/data_sources.py) (Data sources)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_run["Framework execution"]
  node_entry["Framework entry<br/>[mdtf_framework.py]"]
  node_cli["CLI<br/>[cli.py]"]
  node_podsetup["POD setup<br/>[pod_setup.py]"]
end

subgraph group_data["Data preparation"]
  node_sources["Data sources<br/>[data_sources.py]"]
  node_preprocess["Preprocessor<br/>[preprocessor.py]"]
  node_translation["Variable translation<br/>[translation.py]"]
  node_varlist["Variable lists<br/>[varlist_util.py]"]
  node_parser["Xarray parser<br/>[xr_parser.py]"]
  node_unit["Units<br/>[units.py]"]
end

subgraph group_runtime["Runtime support"]
  node_environment["Environment manager"]
  node_utilbasic["Core utilities<br/>[basic.py]"]
  node_utildate["Date labels<br/>[datelabel.py]"]
  node_utildataclass["Data classes<br/>[dataclass.py]"]
  node_utiljson["JSON utilities<br/>[json_utils.py]"]
  node_utillogs["Logging<br/>[logs.py]"]
end

subgraph group_diagnostics["Scientific diagnostics"]
  node_diagnosticset["Independent PODs"]
  node_stc_qbo["QBO and ENSO<br/>[stc_qbo_enso.py]"]
  node_stc_qbo_enso_plot["ENSO plotting"]
  node_stc_qbo_qbo_plot["QBO plotting"]
  node_spv["Polar vortex extremes"]
  node_spvdefs["Vortex definitions"]
  node_wave["Wave coupling"]
  node_wavecalc["Wave calculations"]
  node_mjo["MJO diagnostics<br/>[MJO_suite.py]"]
  node_oceanflux["Ocean flux"]
end

subgraph group_results["Output handling"]
  node_output["HTML output manager<br/>[output_manager.py]"]
end

node_user(("Climate analyst"))

node_user -->|"provides configuration"| node_entry
node_entry -->|"runs eligible PODs"| node_environment
node_entry -->|"creates HTML output"| node_output
node_entry -->|"imports CLI"| node_cli
node_entry -->|"imports setup"| node_podsetup
node_entry -->|"imports preprocessing"| node_preprocess
node_entry -->|"imports translation"| node_translation
node_entry -->|"imports sources"| node_sources
node_environment -->|"executes POD code"| node_diagnosticset
node_preprocess -->|"imports translation"| node_translation
node_preprocess -->|"imports parser"| node_parser
node_preprocess -->|"imports variable lists"| node_varlist
node_preprocess -->|"imports units"| node_unit
node_preprocess -->|"uses date labels"| node_utildate
node_sources -->|"imports variable lists"| node_varlist
node_stc_qbo -->|"uses plotting code"| node_stc_qbo_enso_plot
node_stc_qbo -->|"uses plotting code"| node_stc_qbo_qbo_plot
node_spv -->|"uses definitions"| node_spvdefs
node_wave -->|"uses calculations"| node_wavecalc

click node_entry "https://github.com/noaa-gfdl/mdtf-diagnostics/blob/main/mdtf_framework.py"
click node_cli "https://github.com/noaa-gfdl/mdtf-diagnostics/blob/main/src/cli.py"
click node_podsetup "https://github.com/noaa-gfdl/mdtf-diagnostics/blob/main/src/pod_setup.py"
click node_sources "https://github.com/noaa-gfdl/mdtf-diagnostics/blob/main/src/data_sources.py"
click node_preprocess "https://github.com/noaa-gfdl/mdtf-diagnostics/blob/main/src/preprocessor.py"
click node_translation "https://github.com/noaa-gfdl/mdtf-diagnostics/blob/main/src/translation.py"
click node_varlist "https://github.com/noaa-gfdl/mdtf-diagnostics/blob/main/src/varlist_util.py"
click node_parser "https://github.com/noaa-gfdl/mdtf-diagnostics/blob/main/src/xr_parser.py"
click node_environment "https://github.com/noaa-gfdl/mdtf-diagnostics/blob/main/src/environment_manager.py"
click node_utilbasic "https://github.com/noaa-gfdl/mdtf-diagnostics/blob/main/src/util/basic.py"
click node_utildate "https://github.com/noaa-gfdl/mdtf-diagnostics/blob/main/src/util/datelabel.py"
click node_utildataclass "https://github.com/noaa-gfdl/mdtf-diagnostics/blob/main/src/util/dataclass.py"
click node_utiljson "https://github.com/noaa-gfdl/mdtf-diagnostics/blob/main/src/util/json_utils.py"
click node_utillogs "https://github.com/noaa-gfdl/mdtf-diagnostics/blob/main/src/util/logs.py"
click node_diagnosticset "https://github.com/noaa-gfdl/mdtf-diagnostics/tree/main/diagnostics"
click node_stc_qbo "https://github.com/noaa-gfdl/mdtf-diagnostics/blob/main/diagnostics/stc_qbo_enso/stc_qbo_enso.py"
click node_stc_qbo_enso_plot "https://github.com/noaa-gfdl/mdtf-diagnostics/blob/main/diagnostics/stc_qbo_enso/stc_qbo_enso_plottingcodeenso.py"
click node_stc_qbo_qbo_plot "https://github.com/noaa-gfdl/mdtf-diagnostics/blob/main/diagnostics/stc_qbo_enso/stc_qbo_enso_plottingcodeqbo.py"
click node_spv "https://github.com/noaa-gfdl/mdtf-diagnostics/blob/main/diagnostics/stc_spv_extremes/stc_spv_extremes.py"
click node_spvdefs "https://github.com/noaa-gfdl/mdtf-diagnostics/blob/main/diagnostics/stc_spv_extremes/stc_spv_extremes_defs.py"
click node_wave "https://github.com/noaa-gfdl/mdtf-diagnostics/blob/main/diagnostics/stc_vert_wave_coupling/stc_vert_wave_coupling.py"
click node_wavecalc "https://github.com/noaa-gfdl/mdtf-diagnostics/blob/main/diagnostics/stc_vert_wave_coupling/stc_vert_wave_coupling_calc.py"
click node_output "https://github.com/noaa-gfdl/mdtf-diagnostics/blob/main/src/output_manager.py"
click node_unit "https://github.com/noaa-gfdl/mdtf-diagnostics/blob/main/src/units.py"
click node_mjo "https://github.com/noaa-gfdl/mdtf-diagnostics/blob/main/diagnostics/MJO_suite/MJO_suite.py"
click node_oceanflux "https://github.com/noaa-gfdl/mdtf-diagnostics/blob/main/diagnostics/ocn_surf_flux_diag/ocn_surf_flux_diag.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_entry,node_cli,node_podsetup toneBlue
class node_sources,node_preprocess,node_translation,node_varlist,node_parser,node_unit toneAmber
class node_environment,node_utilbasic,node_utildate,node_utildataclass,node_utiljson,node_utillogs toneMint
class node_diagnosticset,node_stc_qbo,node_stc_qbo_enso_plot,node_stc_qbo_qbo_plot,node_spv,node_spvdefs,node_wave,node_wavecalc,node_mjo,node_oceanflux toneRose
class node_output,node_user toneIndigo
```

## Components

### Framework execution

- [Framework entry](https://github.com/noaa-gfdl/mdtf-diagnostics/blob/main/mdtf_framework.py): `mdtf_framework.py`
- [CLI](https://github.com/noaa-gfdl/mdtf-diagnostics/blob/main/src/cli.py): `src/cli.py`
- [POD setup](https://github.com/noaa-gfdl/mdtf-diagnostics/blob/main/src/pod_setup.py): `src/pod_setup.py`

### Data preparation

- [Data sources](https://github.com/noaa-gfdl/mdtf-diagnostics/blob/main/src/data_sources.py): `src/data_sources.py`
- [Preprocessor](https://github.com/noaa-gfdl/mdtf-diagnostics/blob/main/src/preprocessor.py): `src/preprocessor.py`
- [Variable translation](https://github.com/noaa-gfdl/mdtf-diagnostics/blob/main/src/translation.py): `src/translation.py`
- [Variable lists](https://github.com/noaa-gfdl/mdtf-diagnostics/blob/main/src/varlist_util.py): `src/varlist_util.py`
- [Xarray parser](https://github.com/noaa-gfdl/mdtf-diagnostics/blob/main/src/xr_parser.py): `src/xr_parser.py`
- [Units](https://github.com/noaa-gfdl/mdtf-diagnostics/blob/main/src/units.py): `src/units.py`

### Runtime support

- [Environment manager](https://github.com/noaa-gfdl/mdtf-diagnostics/blob/main/src/environment_manager.py): `src/environment_manager.py`
- [Core utilities](https://github.com/noaa-gfdl/mdtf-diagnostics/blob/main/src/util/basic.py): `src/util/basic.py`
- [Date labels](https://github.com/noaa-gfdl/mdtf-diagnostics/blob/main/src/util/datelabel.py): `src/util/datelabel.py`
- [Data classes](https://github.com/noaa-gfdl/mdtf-diagnostics/blob/main/src/util/dataclass.py): `src/util/dataclass.py`
- [JSON utilities](https://github.com/noaa-gfdl/mdtf-diagnostics/blob/main/src/util/json_utils.py): `src/util/json_utils.py`
- [Logging](https://github.com/noaa-gfdl/mdtf-diagnostics/blob/main/src/util/logs.py): `src/util/logs.py`

### Scientific diagnostics

- [Independent PODs](https://github.com/noaa-gfdl/mdtf-diagnostics/tree/main/diagnostics): `diagnostics`
- [QBO and ENSO](https://github.com/noaa-gfdl/mdtf-diagnostics/blob/main/diagnostics/stc_qbo_enso/stc_qbo_enso.py): `diagnostics/stc_qbo_enso/stc_qbo_enso.py`
- [ENSO plotting](https://github.com/noaa-gfdl/mdtf-diagnostics/blob/main/diagnostics/stc_qbo_enso/stc_qbo_enso_plottingcodeenso.py): `diagnostics/stc_qbo_enso/stc_qbo_enso_plottingcodeenso.py`
- [QBO plotting](https://github.com/noaa-gfdl/mdtf-diagnostics/blob/main/diagnostics/stc_qbo_enso/stc_qbo_enso_plottingcodeqbo.py): `diagnostics/stc_qbo_enso/stc_qbo_enso_plottingcodeqbo.py`
- [Polar vortex extremes](https://github.com/noaa-gfdl/mdtf-diagnostics/blob/main/diagnostics/stc_spv_extremes/stc_spv_extremes.py): `diagnostics/stc_spv_extremes/stc_spv_extremes.py`
- [Vortex definitions](https://github.com/noaa-gfdl/mdtf-diagnostics/blob/main/diagnostics/stc_spv_extremes/stc_spv_extremes_defs.py): `diagnostics/stc_spv_extremes/stc_spv_extremes_defs.py`
- [Wave coupling](https://github.com/noaa-gfdl/mdtf-diagnostics/blob/main/diagnostics/stc_vert_wave_coupling/stc_vert_wave_coupling.py): `diagnostics/stc_vert_wave_coupling/stc_vert_wave_coupling.py`
- [Wave calculations](https://github.com/noaa-gfdl/mdtf-diagnostics/blob/main/diagnostics/stc_vert_wave_coupling/stc_vert_wave_coupling_calc.py): `diagnostics/stc_vert_wave_coupling/stc_vert_wave_coupling_calc.py`
- [MJO diagnostics](https://github.com/noaa-gfdl/mdtf-diagnostics/blob/main/diagnostics/MJO_suite/MJO_suite.py): `diagnostics/MJO_suite/MJO_suite.py`
- [Ocean flux](https://github.com/noaa-gfdl/mdtf-diagnostics/blob/main/diagnostics/ocn_surf_flux_diag/ocn_surf_flux_diag.py): `diagnostics/ocn_surf_flux_diag/ocn_surf_flux_diag.py`

### Output handling

- [HTML output manager](https://github.com/noaa-gfdl/mdtf-diagnostics/blob/main/src/output_manager.py): `src/output_manager.py`

### Other components

- **Climate analyst**

## Connections

- Climate analyst → Framework entry: provides configuration (evidence: `mdtf_framework.py`)
- Framework entry → Environment manager: runs eligible PODs (evidence: `mdtf_framework.py`)
- Framework entry → HTML output manager: creates HTML output (evidence: `mdtf_framework.py`)
- Framework entry → CLI: imports CLI (evidence: `mdtf_framework.py`)
- Framework entry → POD setup: imports setup (evidence: `mdtf_framework.py`)
- Framework entry → Preprocessor: imports preprocessing (evidence: `mdtf_framework.py`)
- Framework entry → Variable translation: imports translation (evidence: `mdtf_framework.py`)
- Framework entry → Data sources: imports sources (evidence: `mdtf_framework.py`)
- Environment manager → Independent PODs: executes POD code (evidence: `src/environment_manager.py`)
- Preprocessor → Variable translation: imports translation (evidence: `src/preprocessor.py`)
- Preprocessor → Xarray parser: imports parser (evidence: `src/preprocessor.py`)
- Preprocessor → Variable lists: imports variable lists (evidence: `src/preprocessor.py`)
- Preprocessor → Units: imports units (evidence: `src/preprocessor.py`)
- Preprocessor → Date labels: uses date labels (evidence: `src/preprocessor.py`)
- Data sources → Variable lists: imports variable lists (evidence: `src/data_sources.py`)
- QBO and ENSO → ENSO plotting: uses plotting code (evidence: `diagnostics/stc_qbo_enso/stc_qbo_enso.py`)
- QBO and ENSO → QBO plotting: uses plotting code (evidence: `diagnostics/stc_qbo_enso/stc_qbo_enso.py`)
- Polar vortex extremes → Vortex definitions: uses definitions (evidence: `diagnostics/stc_spv_extremes/stc_spv_extremes.py`)
- Wave coupling → Wave calculations: uses calculations (evidence: `diagnostics/stc_vert_wave_coupling/stc_vert_wave_coupling.py`)