API

SimDir(simulation_path::String)

Object that describes all the ClimaAtmos output found in the given simulation_path.

get(simdir::SimDir;
    short_name,
    reduction = nothing,
    period = nothing)

Return a OutputVar for the corresponding combination of short_name, reduction, and period (if it exists).

The variable is read only once and saved into the simdir.

Keyword arguments

When passing nothing to reduction and period, ClimaAnalysis will try to automatically deduce the value. An error will be thrown if this is not possible.

For instance, if the simulation has only one ta, you do not need to specify short_name, reduction, and period (short_name is enough). Similarly, if there is only one ta_average (ie, not multiple periods), short_name and reduction will be enough.

get(simdir::SimDir, short_name)

If only one reduction and period exist for short_name, return the corresponding OutputVar.

available_vars(simdir::SimDir)

Return the short names of the variables found in the given simdir.

available_reductions(simdir::SimDir, short_name::String)

Return the reductions available for the given variable in the given simdir.

available_periods(simdir::SimDir, short_name::String, reduction::String)

Return the periods associated to the given variable and reduction.

Representing an output variable

read_var(path::String; short_name = nothing)

Read the short_name variable in the given NetCDF file.

When short_name is nothing, automatically identify the name of the variable. If multiple variables are present, the last one in alphabetical order is chosen.

When units is among the attributes, try to parse it and convert it into an Unitful object. OutputVars with Unitful support automatic unit conversions.

If you want to access units as a string, look at units function.

Example

simdir = SimDir("my_output")
read_var(simdir.variable_paths["hu"]["inst"])

read_var("my_netcdf_file.nc", short_name = "ts")

read_var(paths::Vector{String}; short_name = nothing)

Read the short_name variable in the vector of NetCDF files.

This function automatically aggregates the NetCDF files along the time dimension. If this is not possible, then an error is thrown. The attributes of the OutputVar is the same as the attributes of the first NetCDF file.

When short_name is nothing, automatically identify the name of the variable. If multiple variables are present, the last one in alphabetical order is chosen.

When units is among the attributes, try to parse it and convert it into an Unitful object. OutputVars with Unitful support automatic unit conversions.

If you want to access units as a string, look at units function.

Example

simdir = SimDir("my_output")
read_var(simdir.variable_paths["hu"]["inst"])

read_var(["my_netcdf_file1.nc", "my_netcdf_file2.nc"], short_name = "ts")

is_z_1D(var::OutputVar)

Return whether the given variable has an altitude dimension that is 1D.

When topography is present, the altitude dimension in the output variable is typically multidimensional. The dimensions are (X, Y, Z), where (X, Y) are the horizontal dimensions. In this case, dims["z"] is essentially a map that identifies the physical altitude of the given point.

isempty(var::OutputVar)

Determine whether an OutputVar is empty.

short_name(var::OutputVar)

Return the short_name of the given var, if available.

If not available, return an empty string.

long_name(var::OutputVar)

Return the long_name of the given var, if available.

If not available, return an empty string.

units(var::OutputVar)

Return the units of the given var, if available.

If not available, return an empty string.

has_units(var::OutputVar)

Return whether the given var has units or not.

slice(var::OutputVar, kwargs...)

Return a new OutputVar by slicing across dimensions as defined by the keyword arguments.

Example

slice(var, lat = 30, lon = 20, time = 100)

average_lat(var::OutputVar; ignore_nan = true, weighted = false)

Return a new OutputVar where the values on the latitudes are averaged arithmetically.

When weighted is true, weight the average over cos(lat).

weighted_average_lat(var::OutputVar; ignore_nan = true)

Return a new OutputVar where the values on the latitudes are averaged arithmetically with weights of cos(lat).

average_lon(var::OutputVar; ignore_nan = true)

Return a new OutputVar where the values on the longitudes are averaged arithmetically.

average_x(var::OutputVar; ignore_nan = true)

Return a new OutputVar where the values along the x dimension are averaged arithmetically.

average_y(var::OutputVar; ignore_nan = true)

Return a new OutputVar where the values along the y dimension are averaged arithmetically.

average_xy(var::OutputVar; ignore_nan = true)

Return a new OutputVar where the values along both horizontal dimensions x and y are averaged arithmetically.

average_time(var::OutputVar; ignore_nan = true)

Return a new OutputVar where the values are averaged arithmetically in time.

window(var::OutputVar, dim_name; left = nothing, right = nothing)

Return a new OutputVar by selecting the values of the given dimension that are between left and right.

If left and/or right are nothing, assume beginning (or end) of the array.

Example

window(var, 'lat', left = -50, right = 50)

arecompatible(x::OutputVar, y::OutputVar)

Return whether two OutputVar are defined on the same physical space

This is accomplished by comparing dims and dim_attributes (the latter because they might contain information about the units).

We assume that:

• dim2index and index2dim where correctly created and they reflect dims
• data is also consistent with dims,

We also do not check units for data.

center_longitude!(var::OutputVar, lon::Real)

Shift the longitudes in var so that lon is the center one.

This is useful to center the global projection to the 180 meridian instead of the 0.

times(var::OutputVar)

Return the time dimension in var.

dates(var::OutputVar)

Return the date dimension in var.

longitudes(var::OutputVar)

Return the longitude dimension in var.

latitudes(var::OutputVar)

Return the latitude dimension in var.

altitudes(var::OutputVar)

Return the altitude dimension in var.

pressures(var::OutputVar)

Return the pressure dimension in var.

time_name(var::OutputVar)

Return the name of the time dimension in var.

date_name(var::OutputVar)

Return the name of the date dimension in var.

longitude_name(var::OutputVar)

Return the name of the longitude dimension in var.

latitude_name(var::OutputVar)

Return the name of the latitude dimension in var.

altitude_name(var::OutputVar)

Return the name of the altitude dimension in var.

pressure_name(var::OutputVar)

Return the name of the pressure dimension in var.

has_time(var::OutputVar)

Return whether var has a time dimesnion.

has_date(var::OutputVar)

Return whether var has a date dimesnion.

has_longitude(var::OutputVar)

Return whether var has a longitude dimesnion.

has_latitude(var::OutputVar)

Return whether var has a latitude dimesnion.

has_altitude(var::OutputVar)

Return whether var has a altitude dimesnion.

has_pressure(var::OutputVar)

Return whether var has a pressure dimension.

conventional_dim_name(dim_name::AbstractString)

Return the type of dimension as a string from longitude, latitude, time, date, altitude, or pressure if possible or dim_name as a string otherwise.

dim_units(var::OutputVar, dim_name)

Return the units of the given dim_name in var, if available.

If not available, return an empty string.

range_dim(var::OutputVar, dim_name)

Return the range of the dimension dim_name in var.

Range here is a tuple with the minimum and maximum of dim_name.

reordered_as(src_var::OutputVar, dest_var::OutputVar)

Reorder the dimensions in src_var to match the ordering of dimensions in dest_var.

resampled_as(src_var::OutputVar, dest_var::OutputVar)

Resample data in src_var to dims in dest_var.

The resampling performed here is a 1st-order linear resampling.

Var.convert_units(var, new_units; conversion_function = nothing)

Return a new OutputVar with converted physical units of var to new_units, if possible.

Automatic conversion happens when the units for var and new_units are both parseable. When var does not have units (see also Var.has_units) or has no parseable units, a conversion function conversion_function is required.

conversion_function has to be a function that takes one data point and returns the transformed value.

Being parseable means that Unitful.uparse can parse the expression. Please, refer to the documentation for Unitful.jl for more information.

Examples

Let us set up a trivial 1D OutputVar with units of meters per second and automatically convert it to centimeters per second.

julia> values = 0:100.0 |> collect;

julia> data = copy(values);

julia> attribs = Dict("long_name" => "speed", "units" => "m/s");

julia> dim_attribs = Dict{String, Any}();

julia> var = ClimaAnalysis.OutputVar(attribs, Dict("distance" => values), dim_attribs, data);

julia> ClimaAnalysis.has_units(var)
true

julia> var_cms = ClimaAnalysis.convert_units(var, "cm/s");

julia> extrema(var_cms.data)
(0.0, 10000.0)

Not all the units can be properly parsed, for example, assuming bob=5lol

julia> attribs = Dict("long_name" => "speed", "units" => "bob/s");

julia> var_bob = ClimaAnalysis.OutputVar(attribs, Dict("distance" => values), dim_attribs, data);

julia> var_lols = ClimaAnalysis.convert_units(var, "lol/s", conversion_function = (x) -> 5x);

julia> extrema(var_lols.data)
(0.0, 500.0)

Failure to specify the conversion_function will produce an error.

set_units(var::OutputVar, units::AbstractString)

Set units for data in var.

Var.convert_dim_units(var, dim_name, new_units; conversion_function = nothing)

Return a new OutputVar with converted physical units of dim_name to new_units using conversion_function

This function does not support Unitful, so the parameter conversion_function must be supplied.

set_dim_units!(var::OutputVar, dim_name::AbstractString, units::AbstractString)

Set units for the dim_name dimension in var.

integrate_lonlat(var::OutputVar)

Integrate data in var on longitude and latitude with a first-order scheme. data has to be discretized on longitude and latitude.

If the points are equispaced, it is assumed that each point correspond to the midpoint of a cell which results in rectangular integration using the midpoint rule. Otherwise, the integration being done is rectangular integration using the left endpoints for integrating longitude and latitude. The units for longitude and latitude should be degrees.

All NaNs in var.data are treated as zeros when integrating.

integrate_lat(var::OutputVar)

Integrate data in var on latitude with a first-order scheme. data has to be discretized on latitude.

If the points are equispaced, it is assumed that each point correspond to the midpoint of a cell which results in rectangular integration using the midpoint rule. Otherwise, the integration being done is rectangular integration using the left endpoints. The unit for latitude should be degrees.

All NaNs in var.data are treated as zeros when integrating.

integrate_lon(var::OutputVar)

Integrate data in var on longitude with a first-order scheme. data has to be discretized on longitude.

If the points are equispaced, it is assumed that each point correspond to the midpoint of a cell which results in rectangular integration using the midpoint rule. Otherwise, the integration being done is rectangular integration using the left endpoints. The unit for longitude should be degrees.

All NaNs in var.data are treated as zeros when integrating.

split_by_season(var::OutputVar)

Return a vector of four OutputVars split by season.

The months of the seasons are March to May, June to August, September to November, and December to February. The order of the vector is MAM, JJA, SON, and DJF. If there are no dates found for a season, then the OutputVar for that season will be an empty OutputVar.

The function will use the start date in var.attributes["start_date"]. The unit of time is expected to be second. Also, the interpolations will be inaccurate in time intervals outside of their respective season for the returned OutputVars.

bias(sim::OutputVar, obs::OutputVar; mask = nothing)

Return a OutputVar whose data is the bias (sim.data - obs.data) and compute the global bias of data in sim and obs over longitude and latitude. The result is stored in var.attributes["global_bias"].

This function is currently implemented for OutputVars with only the dimensions longitude and latitude. Units must be supplied for data and dimensions in sim and obs. The units for longitude and latitude should be degrees. Resampling is done automatically by resampling obs on sim. Attributes in sim and obs will be thrown away. The long name and short name of the returned OutputVar will be updated to reflect that a bias is computed.

The parameter mask is a function that masks a OutputVar. See apply_landmask and apply_oceanmask.

See also global_bias, squared_error, global_mse, global_rmse.

global_bias(sim::OutputVar, obs::OutputVar; mask = nothing)

Return the global bias of data in sim and obs over longitude and latitude.

This function is currently only implemented for OutputVars with only the dimensions longitude and latitude. Units must be supplied for data and dimensions in sim and obs. The units for longitude and latitude should be degrees. Resampling is done automatically by resampling obs on sim.

The parameter mask is a function that masks a OutputVar. See apply_landmask and apply_oceanmask.

See also bias, squared_error, global_mse, global_rmse.

squared_error(sim::OutputVar, obs::OutputVar; mask = nothing)

Return a OutputVar whose data is the squared error ((sim.data - obs.data)^2) and compute the global mean squared error (MSE) and global root mean squared error (RMSE) of data in sim and obs over longitude and latitude. The result is stored in var.attributes["mse"] and var.attributes["rmse"].

This function is currently implemented for OutputVars with only the dimensions longitude and latitude. Units must be supplied for data and dimensions in sim and obs. The units for longitude and latitude should be degrees. Resampling is done automatically by resampling obs on sim. Attributes in sim and obs will be thrown away. The long name and short name of the returned OutputVar will be updated to reflect that a squared error is computed.

The parameter mask is a function that masks a OutputVar. See apply_landmask and apply_oceanmask.

See also global_mse, global_rmse, bias, global_bias.

global_mse(sim::OutputVar, obs::OutputVar; mask = nothing)

Return the global mean squared error (MSE) of data in sim and obs over longitude and latitude.

This function is currently implemented for OutputVars with only the dimensions longitude and latitude. Units must be supplied for data and dimensions in sim and obs. The units for longitude and latitude should be degrees. Resampling is done automatically by resampling obs on sim.

The parameter mask is a function that masks a OutputVar. See apply_landmask and apply_oceanmask.

See also squared_error, global_rmse, bias, global_bias.

global_rmse(sim::OutputVar, obs::OutputVar; mask = nothing)

Return the global root mean squared error (RMSE) of data in sim and obs over longitude and latitude.

This function is currently implemented for OutputVars with only the dimensions longitude and latitude. Units must be supplied for data and dimensions in sim and obs. The units for longitude and latitude should be degrees. Resampling is done automatically by resampling obs on sim.

The parameter mask is a function that masks a OutputVar. See apply_landmask and apply_oceanmask.

See also squared_error, global_mse, bias, global_bias.

shift_to_start_of_previous_month(var::OutputVar)

Shift the times in the time dimension to the start of the previous month.

After applying this function, the start date in the attributes correspond to the first element in the time array.

This function is helpful in ensuring consistency in dates between simulation and observational data. One example of this is when adjusting monthly averaged data. For instance, suppose that data on 2010-02-01 in the OutputVar corresponds to the monthly average for January. This function shifts the times so that 2010-01-01 will correspond to the monthly average for January.

Note that this function only works for the time dimension and will not work for the date dimension.

apply_landmask(var::OutputVar)

Apply a land mask to var by NaNing any data whose coordinates are located on land.

apply_oceanmask(var::OutputVar)

Apply an ocean mask to var by NaNing any data whose coordinates are in the ocean.

make_lonlat_mask(var;
                 set_to_val = nothing,
                 true_val = NaN,
                 false_val = 1.0)

Return a masking function that takes in a OutputVar and mask the data using var.data.

The parameter set_to_val is a function that takes in an element of var.data and return true or false. If set_to_nan returns true, then the value will be true_val in the mask and if set_to_nan returns false, then the value will be false_val in the mask.

If set_to_nan is nothing, then no transformation is done and var.data is used. This is helpful if var.data is already an array of NaNs and ones or an array of zeros and ones.

replace(var::OutputVar, old_new::Pair...)

Return a OutputVar where, for each pair old => new, all occurences of old are replaced by new in Var.data

This function is useful if there are NaNs or missing values in the data. For instance, you want to use the ocean mask, but there are NaNs in the ocean. You can replace all the NaN and missing values with 0.0 and apply the ocean mask afterward.

reverse_dim(var::OutputVar, dim_name)

Reverse a dimension by name.

This function is helpful if the order of a dimension need to be reversed, so that an interpolant can be made.

Holding root mean squared errors over multiple categories and models for a single
variable.

RMSEVariable(short_name, model_names::Vector{String})

Construct a RMSEVariable with the short_name of the variable and the names of the models in model_names.

The categories default to "ANN", "DJF", "MAM", "JJA", "SON". The root mean square errors default to NaN. The unit for each model is missing which is denoted by an empty string.

RMSEVariable(short_name, model_names::Vector{String}, units::Dict)

Construct a RMSEVariable with the short_name of the variable, the names of the models in model_names, and provided units in the dictionary units that map model name to unit.

The categories default to "ANN", "DJF", "MAM", "JJA", "SON". The root mean square errors default to NaN. Any missing model in the dictionary units will has missing unit which is denoted by an empty string.

RMSEVariable(short_name,
             model_names::Vector{String},
             category_names::Vector{String},
             units::Dict)

Construct a RMSEVariable with the short_name of the variable, the names of the models in model_names, the categories in category_names, and provided units in the dictionary units that map model name to unit.

The root mean square errors default to NaN. Any missing model in the dictionary units will has missing unit which is denoted by an empty string.

RMSEVariable(short_name::String,
             model_names::Vector{String},
             category_names::Vector{String},
             RMSEs,
             units::Dict)

Construct a RMSEVariable with the short_name of the variable, the names of the models in model_names, the categories in category_names, the root mean squared errors in RMSEs, and units.

RMSEVariable(short_name, model_names::Vector{String}, units::String)

Construct a RMSEVariable with the short_name of the variable, the names of the models in model_names, and units which map each model name to units.

The categories default to "ANN", "DJF", "MAM", "JJA", "SON". The root mean square errors default to NaN.

This is useful if all the models share the same unit.

RMSEVariable(short_name,
             model_names::Vector{String},
             category_names::Vector{String},
             units::String)

Construct a RMSEVariable with the short_name of the variable, the names of the models in model_names, the categories in category_names, and units which map each model name to units.

The root mean square errors default to NaN.

This is useful if all the models share the same unit.

RMSEVariable(short_name::String,
             model_names::Vector{String},
             category_names::Vector{String},
             RMSEs,
             units::String)

Construct a RMSEVariable with the short_name of the variable, the names of the models in model_names, the categories in category_names, the root mean squared errors in RMSEs, and units which map each model name to units.

This is useful if all the models share the same unit.

model_names(rmse_var::RMSEVariable)

Return all the model names in rmse_var.

category_names(rmse_var::RMSEVariable)

Return all the category names in rmse_var.

rmse_units(rmse_var::RMSEVariable)

Return all the unit of the models in rmse_var.

read_rmses(csv_file::String, short_name::String; units = nothing)

Read a CSV file and create a RMSEVariable with the short_name of the variable.

The format of the CSV file should have a header consisting of the entry "model_name" (or any other text as it is ignored by the function) and rest of the entries should be the category names. Each row after the header should start with the model name and the root mean squared errors for each category for that model. The entries of the CSV file should be separated by commas.

The parameter units can be a dictionary mapping model name to unit or a string. If units is a string, then units will be the same across all models. If units is nothing, then the unit is missing for each model which is denoted by an empty string.

Base.getindex(rmse_var::RMSEVariable, model_name, category)

Return a subset of the array holding the root mean square errors as specified by model_name and category. Support indexing by String and Int.

Base.getindex(rmse_var::RMSEVariable, model_name::String)

Return a subset of the array holding the root mean square errors as specified by model_name. Support indexing by String. Do not support linear indexing.

Base.setindex!(rmse_var::RMSEVariable, rmse, model_name, category)

Store a value or values from an array in the array of root mean squared errors in rmse_var. Support indexing by String and Int.

Base.setindex!(rmse_var::RMSEVariable, rmse, model_name::String)

Store a value or values from an array into the array of root mean squared errors in rmse_var. Support indexing by String. Do not support linear indexing.

add_category(rmse_var::RMSEVariable, categories::String...)

Add one or more categories named categories to rmse_var.

add_model(rmse_var::RMSEVariable, models::String...)

Add one or more models named models to rmse_var.

add_unit!(rmse_var::RMSEVariable, model_name, unit)

Add a unit named unit to a model named model_name in rmse_var.

add_unit!(rmse_var::RMSEVariable, model_name2unit::Dict)

Add all model name and unit pairs in the dictionary model_name2unit to rmse_var.

find_best_single_model(rmse_var::RMSEVariable; category_name = "ANN")

Return a tuple of the best single model and the name of the model. Find the best single model using the root mean squared errors of the category category_name.

find_worst_single_model(rmse_var::RMSEVariable; category_name = "ANN")

Return a tuple of the worst single model and the name of the model. Find the worst single model using the root mean squared errors of the category category_name.

median(rmse_var::RMSEVariable)

Find the median using the root mean squared errors across all categories.

Any NaN is ignored in computing the median.

match_nc_filename(filename::String)

Return short_name, period, reduction extracted from the filename, if matching the expected convention.

The convention is: shortname_(period)_reduction.nc, with period being optional.

Examples

julia> match_nc_filename("bob")

julia> match_nc_filename("ta_1d_average.nc")
("ta", "1d", "average")

julia> match_nc_filename("pfull_6.0m_max.nc")
("pfull", "6.0m", "max")

julia> match_nc_filename("hu_inst.nc")
("hu", nothing, "inst")

squeeze(A :: AbstractArray; dims)

Return an array that has no dimensions with size 1.

When an iterable dims is passed, only try to squeeze the given dimensions.

Examples

julia> A = [[1 2] [3 4]];

julia> size(A)
(1, 4)

julia> A_squeezed = squeeze(A);

julia> size(A_squeezed)
(4,)

julia> A_not_squeezed = squeeze(A; dims = (2, ));

julia> size(A_not_squeezed)
(1, 4)

nearest_index(A::AbstractArray, val)

Return the index in A closest to the given val.

Examples

julia> A = [-1, 0, 1, 2, 3, 4, 5];

julia> nearest_index(A, 3)
5

julia> nearest_index(A, 0.1)
2

kwargs(; kwargs...)

Convert keyword arguments in a dictionary that maps Symbols to values.

Useful to pass keyword arguments to different constructors in a function.

Examples

julia> kwargs(a = 1)
pairs(::NamedTuple) with 1 entry:
  :a => 1

seconds_to_prettystr(seconds::Real)

Convert the given seconds into a string with rich time information.

One year is defined as having 365 days.

Examples

julia> seconds_to_prettystr(10)
"10s"

julia> seconds_to_prettystr(600)
"10m"

julia> seconds_to_prettystr(86400)
"1d"

julia> seconds_to_prettystr(864000)
"10d"

julia> seconds_to_prettystr(864010)
"10d 10s"

julia> seconds_to_prettystr(24 * 60 * 60 * 365 + 1)
"1y 1s"

warp_string(str::AbstractString; max_width = 70)

Return a string where each line is at most max_width characters or less or at most one word.

Examples

julia> warp_string("space", max_width = 5)
"space"

julia> warp_string("space", max_width = 4)
"space"

julia> warp_string("\tspace    ", max_width = 4)
"space"

julia> warp_string("space space", max_width = 5)
"space\nspace"

julia> warp_string("space space", max_width = 4)
"space\nspace"

julia> warp_string("\n   space  \n  space", max_width = 4)
"space\nspace"

The Atmos module contains functions that are primarily useful when working with atmospheric simulations.

to_pressure_coordinates(var::OutputVar, pressure::OutputVar; target_pressure = nothing)

Change the vertical dimension of var to be in pressure coordinates.

If target_pressure is nothing, the target pressure levels are computed by Plvl(z) = P0 * exp(-z / HEARTH), where HEARTH = 7000.0 and P0 = 1e5, following a simple hydrostatic model for the atmosphere.

target_pressure can be set to a Vector to specify custom pressure levels.

The return value is a new OutputVar where the vertical dimension is pressure.

:important: Values outside of the range are linearly extrapolated, so do not

trust them too much!

global_rmse_pfull(sim::OutputVar,
                  obs::OutputVar;
                  sim_pressure = nothing,
                  obs_pressure = nothing,
                  target_pressure = nothing)

Return the global RMSE in pressure space as a number.

The arguments sim and obs are defined as 3-dimensional OutputVars with the dimensions longitude, latitude, and altitude or pressure. If altitude is a dimension, then sim and obs are converted to pressure coordinates using to_pressure_coordinates through the keywords sim_pressure and obs_pressure. Specific pressure levels can chosen by supplying a vector of pressure levels for the keyword target_pressure.

Resampling is done automatically by resampling obs on sim.

The global RMSE is calculated by computing the mean squared error over longitude and latitude, integrating and normalizing over pressure, and taking the square root of the resulting number.

heatmap2D!(fig::Makie.Figure,
           var::ClimaAnalysis.OutputVar;
           p_loc = (1,1),
           more_kwargs)
heatmap2D!(grid_layout::Makie.GridLayout,
           var::ClimaAnalysis.OutputVar;
           p_loc = (1,1),
           more_kwargs)

Plot a heatmap of the given 2D variable in the given place and location. The place can be a Figure or a GridLayout.

The plot comes with labels, units, and a colorbar.

This function assumes that the following attributes are available:

• long_name
• short_name
• units (also for the dimensions)

Additional arguments to the plotting and axis functions

more_kwargs can be a dictionary that maps symbols to additional options for:

• the axis (:axis)
• the plotting function (:plot)
• the colorbar (:cb)

The values are splatted in the relevant functions. Populate them with a Dictionary of Symbols => values to pass additional options.

sliced_heatmap!(fig::Makie.Figure,
                var::ClimaAnalysis.OutputVar,
                cut::Union{Nothing, AbstractDict{String, <: Real}};
                p_loc = (1,1),
                more_kwargs,
                )
sliced_heatmap!(grid_layout::Makie.GridLayout,
                var::ClimaAnalysis.OutputVar,
                cut::Union{Nothing, AbstractDict{String, <: Real}};
                p_loc = (1,1),
                more_kwargs,
                )

Take a variable, slice as directed, and plot a 2D heatmap in the given place and location.

The place can be a Figure or a GridLayout.

The plot comes with labels, units, and a colorbar.

Arguments

If the variable is not 2D, cut has to be a dictionary that maps the dimension that has to be sliced and the value where to cut.

For example, if var has four dimensions: time, long, lat, z, this function can be used to plot a lat-long heatmap at fixed time and z. Assuming we want to plot time 100. and altitude 50., cut should be Dict("time" => 100., "z" => 50.).

This function assumes that the following attributes are available:

• long_name
• short_name
• units (also for the dimensions)

Additional arguments to the plotting and axis functions

more_kwargs can be a dictionary that maps symbols to additional options for:

• the axis (:axis)
• the plotting function (:plot)
• the colorbar (:cb)

The values are splatted in the relevant functions. Populate them with a Dictionary of Symbols => values to pass additional options.

heatmap!(place::MakiePlace,
         var::ClimaAnalysis.OutputVar;
         p_loc = (1,1),
         more_kwargs,
         kwargs...
        )

Syntactic sugar for sliced_heatmap with kwargs instead of cut.

Example

heatmap!(fig, var, time = 100, lat = 70) plots a heatmap by slicing var along the time nearest to 100 and latitude nearest 70.

Additional arguments to the plotting and axis functions

more_kwargs can be a dictionary that maps symbols to additional options for:

• the axis (:axis)
• the plotting function (:plot)
• the colorbar (:cb)

The values are splatted in the relevant functions. Populate them with a Dictionary of Symbols => values to pass additional options.

line_plot1D!(place::Makie.Figure,
             var::ClimaAnalysis.OutputVar;
             p_loc = (1,1),
             more_kwargs
             )
line_plot1D!(place::Makie.GridLayout,
             var::ClimaAnalysis.OutputVar;
             p_loc = (1,1),
             more_kwargs
             )

Plot a line plot of the given 1D variable in the given place and location. The place can be a Figure or a GridLayout.

The plot comes with labels, units.

This function assumes that the following attributes are available:

• long_name
• short_name
• units (also for the dimensions)

Additional arguments to the plotting and axis functions

more_kwargs can be a dictionary that maps symbols to additional options for:

• the axis (:axis)
• the plotting function (:plot)

The values are splatted in the relevant functions. Populate them with a Dictionary of Symbols => values to pass additional options.

A special argument that can be passed to :axis is :dim_on_y, which puts the dimension on the y axis instead of the variable. This is useful to plot columns with z on the vertical axis instead of the horizontal one.

sliced_line_plot!(place::Makie.Figure,
                  var::ClimaAnalysis.OutputVar,
                  cut::Union{Nothing, AbstractDict{String, <: Real}};
                  p_loc = (1,1),
                  more_kwargs
                  )
sliced_line_plot!(place::Makie.GridLayout,
                  var::ClimaAnalysis.OutputVar,
                  cut::Union{Nothing, AbstractDict{String, <: Real}};
                  p_loc = (1,1),
                  more_kwargs
                  )

Take a variable, slice as directed, and plot a 1D line plot in the given place and location. The place can be a Figure or a GridLayout.

The plot comes with labels, and units.

Arguments

If the variable is not 1D, cut has to be a dictionary that maps the dimension that has to be sliced and the value where to cut.

For example, if var has four dimensions: time, long, lat, z, this function can be used to plot a lat-long heatmap at fixed time and z. Assuming we want to plot time 100. and altitude 50., cut should be Dict("time" => 100., "z" => 50.).

This function assumes that the following attributes are available:

• long_name
• short_name
• units (also for the dimensions)

Additional arguments to the plotting and axis functions

more_kwargs can be a dictionary that maps symbols to additional options for:

• the axis (:axis)
• the plotting function (:plot)

The values are splatted in the relevant functions. Populate them with a Dictionary of Symbols => values to pass additional options.

sliced_plot!(place::Makie.Figure,
             var::ClimaAnalysis.OutputVar,
             cut::Union{Nothing, AbstractDict{String, <: Real}};
             p_loc = (1,1),
             more_kwargs
             )
sliced_plot!(place::Makie.GridLayout,
             var::ClimaAnalysis.OutputVar,
             cut::Union{Nothing, AbstractDict{String, <: Real}};
             p_loc = (1,1),
             more_kwargs
             )

Take a variable, slice as directed, and plot a 1D line plot or 2D heatmap in the given place and location. The place can be a Figure or a GridLayout.

The plot comes with labels, and units (and possibly a colorbar).

Arguments

If the variable is not 1D/2D, cut has to be a dictionary that maps the dimension that has to be sliced and the value where to cut.

For example, if var has four dimensions: time, long, lat, z, this function can be used to plot a lat-long heatmap at fixed time and z. Assuming we want to plot time 100. and altitude 50., cut should be Dict("time" => 100., "z" => 50.).

This function assumes that the following attributes are available:

• long_name
• short_name
• units (also for the dimensions)

Additional arguments to the plotting and axis functions

more_kwargs can be a dictionary that maps symbols to additional options for:

• the axis (:axis)
• the plotting function (:plot)
• the colorbar (:cb)

The values are splatted in the relevant functions. Populate them with a Dictionary of Symbols => values to pass additional options.

plot!(place::Makie.Figure,
      var::ClimaAnalysis.OutputVar;
      p_loc = (1,1),
      more_kwargs,
      kwargs...
      )
plot!(place::Makie.GridLayout,
      var::ClimaAnalysis.OutputVar;
      p_loc = (1,1),
      more_kwargs,
      kwargs...
      )

Syntactic sugar for sliced_plot with kwargs instead of cut.

Example

line_plot!(fig, var, time = 100, lat = 70) plots a line plot or a heatmap by slicing var along the time nearest to 100 and latitude nearest 70.

Additional arguments to the plotting and axis functions

more_kwargs can be a dictionary that maps symbols to additional options for:

• the axis (:axis)
• the plotting function (:plot)
• the colorbar (:cb)

The values are splatted in the relevant functions. Populate them with a Dictionary of Symbols => values to pass additional options.

Visualize.plot_boxplot!(fig,
                        rmse_var::ClimaAnalysis.RMSEVariable;
                        model_names = ["CliMA"],
                        ploc = (1, 1),
                        best_and_worst_category_name = "ANN",
                        legend_text_width = 10)

Plot a Tukey style boxplot for each category in rmse_var.

The best and worst single models are found for the category best_and_worst_category_name and are plotted on the boxplot. When finding the best and worst single models, any models in model_names will be excluded. Additionally, any model in model_names will also be plotted on the boxplot.

The parameter ploc determines where to place the plot on the figure. The parameter legend_text_width determines the number of characters on each line in the legend.

Visualize.plot_leaderboard!(fig,
                            rmse_vars::ClimaAnalysis.RMSEVariable...;
                            ploc = (1, 1),
                            model_names = ["CliMA"],
                            best_category_name = "ANN")

Plot a heatmap over the categories and models. The models that appear is the best model as found for the category best_category_name and any other models in model_names. The root mean squared errors for each variable of interest is normalized by dividing over the median root mean squared error of each variable.

The parameter ploc determines where to place the plot on the figure.

oceanmask()

Return a collection of polygons to mask out the ocean.

Plot with Makie.poly.

landmask()

Return a collection of polygons to mask out the continents.

Plot with Makie.poly.

contours2D_on_globe!(fig::Makie.Figure,
                    var::ClimaAnalysis.OutputVar;
                    p_loc = (1,1),
                    plot_coastline = true,
                    plot_colorbar = true,
                    plot_contours = true,
                    mask = nothing,
                    more_kwargs)
contours2D_on_globe!(grid_layout::Makie.GridLayout,
                    var::ClimaAnalysis.OutputVar;
                    p_loc = (1,1),
                    plot_coastline = true,
                    plot_colorbar = true,
                    plot_contours = true,
                    mask = nothing,
                    more_kwargs)

Plot discrete contours of the given 2D variable on a projected geoid.

The plot comes with labels, units, and a colorbar.

This function assumes that the following attributes are available:

• long_name
• short_name
• units

The dimensions have to be longitude and latitude.

mask has to be an object that can be plotted by Makie.poly or a masking function. ClimaAnalysis comes with predefined masks, check out Visualize.oceanmask and Visualize.landmask. Also, the corresponding mask is applied to the OutputVars. For instance, using Visualize.landmask means ClimaAnalysis.apply_landmask is applied to the OutputVars when computing the bias. One can also pass in ClimaAnalysis.apply_landmask, ClimaAnalysis.apply_oceanmask, or a custom masking function (ClimaAnalysis.Var.make_lonlat_mask).

Additional arguments to the plotting and axis functions

more_kwargs can be a dictionary that maps symbols to additional options for:

• the axis (:axis)
• the plotting function (:plot)
• the colorbar (:cb)
• the coastline (:coast)
• the mask (:mask)

The coastline is plotted from GeoMakie.coastline using the lines! plotting function.

The values are splatted in the relevant functions. Populate them with a Dictionary of Symbols => values to pass additional options.

heatmap2D_on_globe!(fig::Makie.Figure,
                    var::ClimaAnalysis.OutputVar;
                    p_loc = (1,1),
                    plot_coastline = true,
                    plot_colorbar = true,
                    mask = nothing,
                    more_kwargs)
heatmap2D_on_globe!(grid_layout::Makie.GridLayout,
                    var::ClimaAnalysis.OutputVar;
                    p_loc = (1,1),
                    plot_coastline = true,
                    plot_colorbar = true,
                    mask = nothing,
                    more_kwargs)

Plot a heatmap of the given 2D variable on a projected geoid.

The plot comes with labels, units, and a colorbar.

This function assumes that the following attributes are available:

• long_name
• short_name
• units

The dimensions have to be longitude and latitude.

mask has to be an object that can be plotted by Makie.poly or a masking function. ClimaAnalysis comes with predefined masks, check out Visualize.oceanmask and Visualize.landmask. Also, the corresponding mask is applied to the OutputVars. For instance, using Visualize.landmask means ClimaAnalysis.apply_landmask is applied to the OutputVars when computing the bias. One can also pass in ClimaAnalysis.apply_landmask, ClimaAnalysis.apply_oceanmask, or a custom masking function (ClimaAnalysis.Var.make_lonlat_mask).

Additional arguments to the plotting and axis functions

more_kwargs can be a dictionary that maps symbols to additional options for:

• the axis (:axis)
• the plotting function (:plot)
• the colorbar (:cb)
• the coastline (:coast)
• the mask (:mask)

The coastline is plotted from GeoMakie.coastline using the lines! plotting function.

The values are splatted in the relevant functions. Populate them with a Dictionary of Symbols => values to pass additional options.

plot_bias_on_globe!(fig::Makie.Figure,
                    sim::ClimaAnalysis.OutputVar,
                    obs::ClimaAnalysis.OutputVar;
                    cmap_extrema = nanextrema(ClimaAnalysis.bias(sim, obs).data),
                    p_loc = (1, 1),
                    plot_coastline = true,
                    plot_colorbar = true,
                    mask = nothing,
                    more_kwargs)
plot_bias_on_globe!(grid_layout::Makie.GridLayout,
                    sim::ClimaAnalysis.OutputVar,
                    obs::ClimaAnalysis.OutputVar;
                    cmap_extrema = nanextrema(ClimaAnalysis.bias(sim, obs).data),
                    p_loc = (1, 1),
                    plot_coastline = true,
                    plot_colorbar = true,
                    mask = nothing,
                    more_kwargs)

Plot the bias (sim.data - var.data) on a projected geoid. The gloal bias and root mean squared error (RMSE) are computed and can be found in the title of the plot. This function plots the returned OutputVar of ClimaAnalysis.bias(sim, obs). See also ClimaAnalysis.bias.

The plot comes with labels, units, and a colorbar. This function uses a constrained colormap based on the values of cmap_extrema.

The dimensions have to be longitude and latitude.

mask has to be an object that can be plotted by Makie.poly or a masking function. ClimaAnalysis comes with predefined masks, check out Visualize.oceanmask and Visualize.landmask. Also, the corresponding mask is applied to the OutputVars. For instance, using Visualize.landmask means ClimaAnalysis.apply_landmask is applied to the OutputVars when computing the bias. One can also pass in ClimaAnalysis.apply_landmask, ClimaAnalysis.apply_oceanmask, or a custom masking function (ClimaAnalysis.Var.make_lonlat_mask). The masking function is used for computing the bias.

Additional arguments to the plotting and axis functions

more_kwargs can be a dictionary that maps symbols to additional options for:

• the axis (:axis)
• the plotting function (:plot)
• the colorbar (:cb)
• the coastline (:coast)
• the mask (:mask)

The coastline is plotted from GeoMakie.coastline using the lines! plotting function.

The values are splatted in the relevant functions. Populate them with a Dictionary of Symbols => values to pass additional options.