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_plots — Functionmake_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.
ClimaCoupler.Plotting.make_ocean_diagnostics_plots — Functionmake_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.
ClimaCoupler.Plotting.debug — Functiondebug(cs::Interfacer.CoupledSimulation, dir = "debug", cs_fields_ref = nothing)Plot the fields of a coupled simulation and save plots to a directory.
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.
debug(sim::Interfacer.ComponentModelSimulation, dir)Plot the fields of a component model simulation and save plots to a directory.
ClimaCoupler.Plotting.debug_plot_fields — FunctionPlotting.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.
ClimaCoupler.Plotting.debug_plot! — FunctionPlotting.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.
Plotting.debug_plot!(ax, fig, field, i, j)Make a line plot of the provided array.
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.
ClimaCoupler.Plotting.plot_global_conservation — Functionplot_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$):
- global quantity of each model component as a function of time,
relative to the initial value;
- fractional change in the sum of all components over time on a log scale.
ClimaCoupler.Plotting.compute_leaderboard — Functioncompute_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.
ClimaCoupler.Plotting.compute_pfull_leaderboard — Functioncompute_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.
ClimaCouplerMakieExt Extension
The ClimaCouplerMakieExt extension provides the actual implementations of all plotting functions when the following packages are loaded:
Makie- The core plotting packageCairoMakie- For PDF image output and other backend plotting workClimaCoreMakie- For plotting ClimaCore fieldsGeoMakie- For geographic/map visualizationsPoppler_jll- For saving PDFs nicelyPrintf- 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, PrintfOnce 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 OceananigansAdditional Features
The Oceananigans extension adds support for:
Oceananigans field plotting: Extends
Plotting.debug_plot!to handleOceananigans.FieldandOceananigans.AbstractOperations.AbstractOperationtypes, allowing debug plots to visualize ocean model fields directly.Oceananigans field extrema: Extends
Plotting.print_extremato 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.