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)

Read a variable in the given NetCDF file.

Example

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

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.

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.

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.

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.

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.

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.

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.0min_max.nc")
("pfull", "6.0min", "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)

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"

split_by_season(dates::AbstractArray{<: Dates.DateTime})

Return four vectors with dates split by seasons.

The months of the seasons are March to May, June to August, September to November, and December to February. The order of the tuple is MAM, JJA, SON, and DJF.

Examples

julia> import Dates

julia> dates = [Dates.DateTime(2024, 1, 1), Dates.DateTime(2024, 3, 1), Dates.DateTime(2024, 6, 1), Dates.DateTime(2024, 9, 1)];

julia> split_by_season(dates)
([Dates.DateTime("2024-03-01T00:00:00")], [Dates.DateTime("2024-06-01T00:00:00")], [Dates.DateTime("2024-09-01T00:00:00")], [Dates.DateTime("2024-01-01T00:00:00")])

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 linearly sampling the interval minimum(pressure), maximum(pressure). Then, for each column in var, the values are linearly interpolate onto this new grid.

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!

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.

contours2D_on_globe!(fig::Makie.Figure,
                    var::ClimaAnalysis.OutputVar;
                    p_loc = (1,1),
                    plot_coastline = true,
                    plot_colorbar = true,
                    plot_contours = true,
                    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,
                    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.

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 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,
                    more_kwargs)
heatmap2D_on_globe!(grid_layout::Makie.GridLayout,
                    var::ClimaAnalysis.OutputVar;
                    p_loc = (1,1),
                    plot_coastline = true,
                    plot_colorbar = true,
                    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.

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 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.