ClimaViz.jl

Appearance

API Reference ​

Main Functions ​

ClimaViz.dashboard Function
julia
dashboard(path::String; HPC=false, obs=default_obs())

Launch an interactive web dashboard for visualizing climate simulation outputs and benchmarking against gridded observations when available.

Features:

  • Variable / reduction / period menus driven by ClimaAnalysis.SimDir.

  • Temporal aggregation (Monthly / Seasonal / Annual) re-binning the time axis on the fly — choices are restricted to levels at least as coarse as the native data resolution.

  • 2D map (model) with click-to-select location.

  • Bias map (model − observation) when an observation is registered for the selected variable; otherwise hidden. Observation products are shown by name (ERA5, CarbonTracker, GOSIF, …) in the legend, bias panel and metrics table.

  • Time-series mode menu: Local (the clicked map location) or Global (area- weighted mean, the same convention as the metrics table). The spatial mask for "global" follows the component: ocean-masked land mean for ClimaLand output (and plain runs), the full globe for atmos, land-masked ocean mean for ocean/seaice. Clicking a map switches back to Local at that location.

  • Vertical profile when the variable has a z / z_reference dimension; otherwise replaced by a benchmark metrics table (Sim mean, Obs mean, Bias, RMSE, Spatial r, Amplitude ratio, Phase shift across All-time / Selected / DJF / MAM / JJA / SON).

  • Time-series at the selected location (or global land mean), with the observation overlaid when available.

Arguments

  • path::String: simulation output directory (readable by SimDir).

  • HPC::Bool = false: serve on 0.0.0.0:8080 for HPC port-forwarding.

  • obs::Dict{String,Function} = default_obs(): maps variable short_names to obs loaders. Each loader receives the sim's start_date and returns a ClimaAnalysis.OutputVar. The default registers ERA5 monthly fluxes for lhf, shf, lwu, swu and inversion-derived carbon fluxes for nee, gpp, er, hr via ClimaViz LazyArtifacts.

  • cache::Bool = true: read/write the persistent benchmark cache in <path>/.climaviz_cache. On a hit, the bias map, colorbar limits and metrics for the selected variable are served from disk instead of recomputed (regridding + ocean-masked RMSE/bias), which is the slow part of a variable switch. Raw fields are always read lazily. Falls back to live computation on a miss, so this is purely a responsiveness optimization. See precompute_dashboard_cache to warm it up front.

  • precompute::Bool = false: before serving, run precompute_dashboard_cache (per component in coupled mode) and warm the model-summary cache, so every benchmark panel and the first "Model summary" click are instant. Slow on a cold cache (regridding + metrics for all variables), near-instant if already warm. Useful for long-lived deployments; ignored when cache = false.

  • run_title::String = "": optional caption shown in the menu, just below the play button (e.g. "ClimaLand long run, #4836"). Empty string hides it.

  • coupled::Bool = false: treat path as a ClimaCoupler output directory holding one subfolder per component (clima_atmos, clima_land, clima_ocean, clima_seaice) instead of a single flat output. Adds a "Component:" menu that swaps the active component at runtime; components whose folder is missing or empty are skipped. The atmos component is restricted to its monthly (_1M_) native-grid diagnostics, and components whose files lack a start_date attribute (possible for land) inherit the atmos one. All components are assumed to share the diagnostic lon/lat grid (ClimaCoupler regrids them onto one). The benchmark cache lives per component folder.

A "Model summary" button opens an overlay with the global RMSE (and bias) of every benchmarked variable over the whole simulation period, per season — computed once per component (persisted via the cache) on first open.

Example

julia
using ClimaViz
dashboard("path/to/output/")

# Warm the cache once, then everything is instant:
precompute_dashboard_cache("path/to/output/")
dashboard("path/to/output/")

# ClimaCoupler AMIP run (clima_atmos/, clima_land/, … subfolders):
dashboard("path/to/coupler_output/"; coupled = true)
source
ClimaViz.precompute_dashboard_cache Function
julia
precompute_dashboard_cache(path; obs = default_era5_obs(), verbose = true, mask_kind = :land)

Warm the persistent benchmark cache for every (variable, reduction, period, aggregation level) in path that has a registered observation. Already-cached, up-to-date entries are skipped (cheap fingerprint check), so this is safe to re-run — e.g. after regenerating the longrun, or on each server restart.

mask_kind selects the spatial mask for the metrics (see MASK_SPECS): :land (ocean-masked, the default), :globe (atmos components of coupled runs) or :ocean. It must match what the dashboard will use for this output.

Run this once after producing the simulation output (or in CI). The dashboard reads whatever is present and falls back to live computation on a miss, so precomputing is purely a responsiveness optimization.

Returns the BenchmarkCache.

source

Observation registries ​

ClimaViz.default_obs Function
julia
default_obs()

Combined built-in observation set: ERA5 monthly energy fluxes (default_era5_obs: lhf, shf, lwu, swu) merged with the inversion-derived carbon fluxes (default_inversion_obs: nee, gpp, er, hr). This is the default observation registry for dashboard and precompute_dashboard_cache.

source
ClimaViz.default_era5_obs Function
julia
default_era5_obs()

Built-in Dict{String, Function} mapping simulation short names to ERA5 monthly observation loaders. Each loader takes a start_date and returns a ClimaAnalysis.OutputVar aligned to that origin.

Covers the surface fluxes (W m⁻², monthly, 1°×1°) under both the ClimaLand names (lhf, shf, lwu, swu) and the ClimaAtmos/CMIP names (hfls, hfss, rlus, rsus) — the same ERA5 fields and sign conventions either way. Returns an empty Dict if the underlying artifact is unavailable.

source
ClimaViz.default_inversion_obs Function
julia
default_inversion_obs()

Built-in Dict{String, Function} mapping ClimaLand carbon short names to inversion-derived observation loaders from the inversion_nee artifact. Each loader returns a ClimaAnalysis.OutputVar in g C m⁻² day⁻¹ (the dashboard's carbon display unit), monthly 1°×1°, 2002–2020.

Covers: nee (CarbonTracker CT2022), gpp (GOSIF-GPP v2), er (residual NEE + GPP), hr (Hashimoto-2015 Rh). Returns an empty Dict if the underlying artifact is unavailable.

source

Index ​