Plotting

The Plotting module provides functionality for visualizing ClimaCoupler simulation output, including diagnostic plots, visualizations for debugging, leaderboards comparing to observations, and calibration parameter plots.

By default, the Plotting module provides stub implementations that do nothing. The actual plotting implementations are provided by the ClimaCouplerMakieExt extension when Makie.jl and related packages are available, and by ClimaCouplerOceananigansMakieExt when the plotting packages and Oceananigans.jl are available.

Plotting API

ClimaCoupler.Plotting.make_diagnostics_plotsFunction
make_diagnostics_plots(
    output_path::AbstractString,
    plot_path::AbstractString;
    output_prefix = "",
)

Create plots for diagnostics. The plots are saved to plot_path. This function will plot all variables that have been saved in output_path. The reduction keyword argument should be consistent with the reduction used to save the diagnostics.

source
ClimaCoupler.Plotting.make_ocean_diagnostics_plotsFunction
make_ocean_diagnostics_plots(output_path::AbstractString, plot_path::AbstractString; output_prefix = "")

Create plots for diagnostics. The plots are saved to ocean_summary_2D.pdf in plot_path. This function will plot the following variables, if they have been saved in output_path: - Temperature (T) - Salinity (S) - Zonal velocity (u) - Meridional velocity (v)

For each variable, take the surface level (top level) of the variable and create a 2D plot. The plots will be saved in a single PDF file.

source
ClimaCoupler.Plotting.debugFunction
debug(cs::Interfacer.CoupledSimulation, dir = "debug", cs_fields_ref = nothing)

Plot the fields of a coupled simulation and save plots to a directory.

source
debug(cs_fields::CC.Fields.Field, dir, cs_fields_ref = nothing)

Plot useful coupler fields (in field_names) and save plots to a directory.

If cs_fields_ref is provided (e.g., using a copy of cs.fields from the initialization), plot the anomalies of the fields with respect to cs_fields_ref.

source
debug(sim::Interfacer.ComponentModelSimulation, dir)

Plot the fields of a component model simulation and save plots to a directory.

source
ClimaCoupler.Plotting.debug_plot_fieldsFunction
Plotting.debug_plot_fields(sim::Interfacer.SurfaceModelSimulation)

Return the default fields to include in debug plots for a surface model. This should be extended for any atmosphere model, and any surface model that has additional fields to plot.

source
ClimaCoupler.Plotting.debug_plot!Function
Plotting.debug_plot!(ax, fig, field::CC.Fields.Field, i, j)

Helper function to plot a heatmap of a ClimaCore field in the given figure at position (i, j). If the field is constant, skip plotting it to avoid heatmap errors.

source
Plotting.debug_plot!(ax, fig, field, i, j)

Make a line plot of the provided array.

source
Plotting.debug_plot!(ax, fig, field, i, j)

Plot a heatmap of the provided Oceananigans field or operation. This is intended to be used as part of the debug plotting system.

source
ClimaCoupler.Plotting.plot_global_conservationFunction
plot_global_conservation(
    cc::AbstractConservationCheck,
    coupler_sim::Interfacer.CoupledSimulation,
    softfail = false;
    figname1 = "total.png",
    figname2 = "total_log.png",
)

Creates two plots of the globally integrated quantity (energy, $\rho e$):

  1. global quantity of each model component as a function of time,

relative to the initial value;

  1. fractional change in the sum of all components over time on a log scale.
source
ClimaCoupler.Plotting.compute_leaderboardFunction
compute_leaderboard(leaderboard_base_path, diagnostics_folder_path, spinup)

Plot the biases and a leaderboard of various variables defined over longitude, latitude, and time.

The argument leaderboard_base_path is the path to save the leaderboards and bias plots, diagnostics_folder_path is the path to the simulation data, and spinup is the number of months to remove from the beginning of the simulation.

Loading and preprocessing simulation data is done by get_sim_var_dict. Loading and preprocessing observational data is done by get_obs_var_dict. The ranges of the bias plots are determined by get_compare_vars_biases_plot_extrema. The groups of variables plotted on the bias plots are determined by get_compare_vars_biases_groups(). Loading the RMSEs from other models is done by get_rmse_var_dict. See the functions defined in data_sources.jl.

source
ClimaCoupler.Plotting.compute_pfull_leaderboardFunction
compute_pfull_leaderboard(leaderboard_base_path, diagnostics_folder_path, spinup)

Plot the biases and a leaderboard of various variables defined over longitude, latitude, time, and pressure levels.

The argument leaderboard_base_path is the path to save the leaderboards and bias plots, diagnostics_folder_path is the path to the simulation data, and spinup is the number of months to remove from the beginning of the simulation.

Loading and preprocessing simulation data is done by get_sim_var_in_pfull_dict. Loading and preprocessing observational data is done by get_obs_var_in_pfull_dict. The ranges of the bias plots is defined by get_compare_vars_biases_plot_extrema_pfull. See the functions defined in data_sources.jl for more information.

source

ClimaCouplerMakieExt Extension

The ClimaCouplerMakieExt extension provides the actual implementations of all plotting functions when the following packages are loaded:

  • Makie - The core plotting package
  • CairoMakie - For PDF image output and other backend plotting work
  • ClimaCoreMakie - For plotting ClimaCore fields
  • GeoMakie - For geographic/map visualizations
  • Poppler_jll - For saving PDFs nicely
  • Printf - For string manipulation

Loading the Extension

The extension is automatically loaded when you using or import all of the required Makie packages:

using Makie, GeoMakie, CairoMakie, ClimaCoreMakie, Poppler_jll, Printf

Once loaded, all plotting functions in the Plotting module will use the full implementations instead of the stub methods.

Features

Diagnostics plots

ClimaCouplerMakieExt.jl uses ClimaAnalysis.jl to generate plots of diagnostic variables saved using the ClimaDiagnostics.jl infrastructure.

For information about diagnostics in ClimaCoupler, including how to customize which variables to save, how often, and with which reductions, see the Diagnostics documentation.

Leaderboards

Leaderboards compare simulation output against observational data, computing bias and RMSE metrics for various variables. Both 2D surface variables and 3D pressure-level variables are supported.

For detailed information about adding variables to leaderboards and customizing comparisons, see the Leaderboard documentation.

Calibration plots

Calibration plots visualize parameter calibration results, including scatter plots of parameter values versus observations and parameter evolution across iterations.

These plots are used to visualize the results of model parameter calibration with EnsembleKalmanProcesses.jl.

Conservation plots

Conservation plots show time series of global conservation quantities (energy and water) over the course of a simulation. These plots help verify that the coupled system maintains physical conservation properties.

Please note that the current AMIP/CMIP configurations are not expected to be conservative, so conservation plots are only available for the Slabplanet configuration.

For information about conservation checks in ClimaCoupler, see the Conservation Checks documentation.

Debug plots

To facilitate debugging, ClimaCoupler.jl plots most coupler fields and model fields of physical interest by default. These plots are availabe at the end of a simulation in the provided artifacts directory.

ClimaCouplerOceananigansMakieExt Extension

The ClimaCouplerOceananigansMakieExt extension extends the base plotting functionality to support Oceananigans.jl fields when Oceananigans is used as the ocean component model.

Loading the Extension

The extension is automatically loaded when Oceananigans.jl and the required Makie packages are available:

using Makie, GeoMakie, CairoMakie, ClimaCoreMakie, Poppler_jll, Printf
using Oceananigans

Additional Features

The Oceananigans extension adds support for:

  • Oceananigans field plotting: Extends Plotting.debug_plot! to handle Oceananigans.Field and Oceananigans.AbstractOperations.AbstractOperation types, allowing debug plots to visualize ocean model fields directly.

  • Oceananigans field extrema: Extends Plotting.print_extrema to format the minimum and maximum values of Oceananigans fields for display in plot titles and labels.

These extensions enable the debug plotting system to automatically handle Oceananigans fields when they are encountered in coupled simulations, without requiring any special handling in user code.