API
Sim
ClimaAnalysis.Sim.SimDir
— TypeSimDir(simulation_path::String)
Object that describes all the ClimaAtmos
output found in the given simulation_path
.
Base.get
— Functionget(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
.
ClimaAnalysis.Sim.available_vars
— Functionavailable_vars(simdir::SimDir)
Return the short names of the variables found in the given simdir
.
ClimaAnalysis.Sim.available_reductions
— Functionavailable_reductions(simdir::SimDir, short_name::String)
Return the reductions available for the given variable in the given simdir
.
ClimaAnalysis.Sim.available_periods
— Functionavailable_periods(simdir::SimDir, short_name::String, reduction::String)
Return the periods associated to the given variable and reduction.
Var
ClimaAnalysis.Var.OutputVar
— TypeRepresenting an output variable
ClimaAnalysis.Var.read_var
— Functionread_var(path::String)
Read a variable in the given NetCDF file.
Example
simdir = SimDir("my_output")
read_var(simdir.variable_paths["hu"]["inst"])
ClimaAnalysis.Var.is_z_1D
— Functionis_z_1D(var::OutputVar)
Return whether the given var
iable 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.
ClimaAnalysis.Var.short_name
— Functionshort_name(var::OutputVar)
Return the short_name
of the given var
, if available.
If not available, return an empty string.
ClimaAnalysis.Var.long_name
— Functionlong_name(var::OutputVar)
Return the long_name
of the given var
, if available.
If not available, return an empty string.
ClimaAnalysis.Var.units
— Functionunits(var::OutputVar)
Return the units
of the given var
, if available.
If not available, return an empty string.
ClimaAnalysis.Var.slice
— Functionslice(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)
ClimaAnalysis.Var.average_lat
— Functionaverage_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)
.
ClimaAnalysis.Var.weighted_average_lat
— Functionweighted_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)
.
ClimaAnalysis.Var.average_lon
— Functionaverage_lon(var::OutputVar; ignore_nan = true)
Return a new OutputVar where the values on the longitudes are averaged arithmetically.
ClimaAnalysis.Var.average_x
— Functionaverage_x(var::OutputVar; ignore_nan = true)
Return a new OutputVar where the values along the x
dimension are averaged arithmetically.
ClimaAnalysis.Var.average_y
— Functionaverage_y(var::OutputVar; ignore_nan = true)
Return a new OutputVar where the values along the y
dimension are averaged arithmetically.
ClimaAnalysis.Var.average_xy
— Functionaverage_xy(var::OutputVar; ignore_nan = true)
Return a new OutputVar where the values along both horizontal dimensions x
and y
are averaged arithmetically.
ClimaAnalysis.Var.average_time
— Functionaverage_time(var::OutputVar; ignore_nan = true)
Return a new OutputVar where the values are averaged arithmetically in time.
ClimaAnalysis.Var.window
— Functionwindow(var::OutputVar, dim_name; left = nothing, right = nothing)
Return a new OutputVar by selecting the values of the given dim
ension 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)
ClimaAnalysis.Var.arecompatible
— Functionarecompatible(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
andindex2dim
where correctly created and they reflectdims
data
is also consistent withdims
,
We also do not check units for data
.
ClimaAnalysis.Var.center_longitude!
— Functioncenter_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.
ClimaAnalysis.Var.times
— Functiontimes(var::OutputVar)
Return the time
dimension in var
.
ClimaAnalysis.Var.dates
— Functiondates(var::OutputVar)
Return the date
dimension in var
.
ClimaAnalysis.Var.longitudes
— Functionlongitudes(var::OutputVar)
Return the longitude
dimension in var
.
ClimaAnalysis.Var.latitudes
— Functionlatitudes(var::OutputVar)
Return the latitude
dimension in var
.
ClimaAnalysis.Var.altitudes
— Functionaltitudes(var::OutputVar)
Return the altitude
dimension in var
.
ClimaAnalysis.Var.time_name
— Functiontime_name(var::OutputVar)
Return the name of the time
dimension in var
.
ClimaAnalysis.Var.date_name
— Functiondate_name(var::OutputVar)
Return the name of the date
dimension in var
.
ClimaAnalysis.Var.longitude_name
— Functionlongitude_name(var::OutputVar)
Return the name of the longitude
dimension in var
.
ClimaAnalysis.Var.latitude_name
— Functionlatitude_name(var::OutputVar)
Return the name of the latitude
dimension in var
.
ClimaAnalysis.Var.altitude_name
— Functionaltitude_name(var::OutputVar)
Return the name of the altitude
dimension in var
.
ClimaAnalysis.Var.has_time
— Functionhas_time(var::OutputVar)
Return whether var
has a time
dimesnion.
ClimaAnalysis.Var.has_date
— Functionhas_date(var::OutputVar)
Return whether var
has a date
dimesnion.
ClimaAnalysis.Var.has_longitude
— Functionhas_longitude(var::OutputVar)
Return whether var
has a longitude
dimesnion.
ClimaAnalysis.Var.has_latitude
— Functionhas_latitude(var::OutputVar)
Return whether var
has a latitude
dimesnion.
ClimaAnalysis.Var.has_altitude
— Functionhas_altitude(var::OutputVar)
Return whether var
has a altitude
dimesnion.
ClimaAnalysis.Var.dim_units
— Functiondim_units(var::OutputVar, dim_name)
Return the units
of the given dim_name
in var
, if available.
If not available, return an empty string.
ClimaAnalysis.Var.range_dim
— Functionrange_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
.
Utilities
For development and not
ClimaAnalysis.Utils.match_nc_filename
— Functionmatch_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")
ClimaAnalysis.Utils.squeeze
— Functionsqueeze(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 dim
ensions.
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)
ClimaAnalysis.Utils.nearest_index
— Functionnearest_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
ClimaAnalysis.Utils.kwargs
— Functionkwargs(; kwargs...)
Convert keyword arguments in a dictionary that maps Symbol
s 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
ClimaAnalysis.Utils.seconds_to_prettystr
— Functionseconds_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"
ClimaAnalysis.Utils.warp_string
— Functionwarp_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"
ClimaAnalysis.Utils.split_by_season
— Functionsplit_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")])
Atmos
ClimaAnalysis.Atmos
— ModuleThe Atmos
module contains functions that are primarily useful when working with atmospheric simulations.
ClimaAnalysis.Atmos.to_pressure_coordinates
— Functionto_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!
Makie
ClimaAnalysis.Visualize.heatmap2D!
— Functionheatmap2D!(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 var
iable 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 Symbol
s => values to pass additional options.
ClimaAnalysis.Visualize.sliced_heatmap!
— Functionsliced_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 var
iable, 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 Symbol
s => values to pass additional options.
ClimaAnalysis.Visualize.heatmap!
— Functionheatmap!(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 Symbol
s => values to pass additional options.
ClimaAnalysis.Visualize.line_plot1D!
— Functionline_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 var
iable 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 Symbol
s => 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.
ClimaAnalysis.Visualize.sliced_line_plot!
— Functionsliced_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 var
iable, 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 Symbol
s => values to pass additional options.
ClimaAnalysis.Visualize.sliced_plot!
— Functionsliced_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 var
iable, 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 Symbol
s => values to pass additional options.
ClimaAnalysis.Visualize.plot!
— Functionplot!(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 Symbol
s => values to pass additional options.
GeoMakie
ClimaAnalysis.Visualize.contour2D_on_globe!
— Functioncontours2D_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 var
iable 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 Symbol
s => values to pass additional options.
ClimaAnalysis.Visualize.heatmap2D_on_globe!
— Functionheatmap2D_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 var
iable 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 Symbol
s => values to pass additional options.