Developer Documentation

TemplateVar

The main struct in ClimaAnalysis is OutputVar. To manually construct a OutputVar from scratch involves either making your own NetCDF file or manually defining the attributes, dimensions, dimension attributes, and data. This process is prone to errors (e.g., mismatches between dimension size and data size or mismatch between variable names) and is repetitive when initializing multiple OutputVars for testing.

To solve this issue, we introduce TemplateVar. A TemplateVar can be thought of as an uninitialized OutputVar which is not materialized until it is called with initialize. See the example below of constructing a TemplateVar and initializing it into an OutputVar.

var =
    Template.TemplateVar() |>
    Template.add_attribs(long_name = "Test", short_name = "test") |>
    Template.add_time_dim(name = "t", dim = collect(0.0:2.0)) |>
    Template.add_lon_dim(units = "degrees") |>
    Template.add_lat_dim(axis = "Y") |>
    Template.one_to_n_data(collected = true) |>
    Template.initialize

Attributes:
  short_name => test
  long_name  => Test
Dimension attributes:
  t:
    units => seconds
  longitude:
    units => degrees
  latitude:
    units => degrees_east
    axis  => Y
Data defined over:
  t         with 3 elements (0.0 to 2.0)
  longitude with 361 elements (-180.0 to 180.0)
  latitude  with 181 elements (-90.0 to 90.0)

The convenience functions for adding a dimension are add_time_dim, add_lon_dim, add_lat_dim, add_pfull_dim, and add_z_dim which accept the keyword arguments dim_name, dim_array, and units. Any other keyword arguments will be used as attributes for the dimension. These functions are designed to be used with the pipe operator (|>). Additionally, there are also functions of the form add_x_dim! which are designed to be used with function composition. The x can be time, lon, lat, pfull, or z.

The order in which dimensions are added to the TemplateVar determines their order in the OutputVar. If the same dimension is added again, then the existing dimension is overwritten with the new dimension. As a result, when defining a dimension, one must add all the dimension attributes, name of the dimension, and the dimension array at once.

When adding multiple attributes using add_attribs or add_attribs!, existing attributes will be overwritten. There is currently no functionality to remove attributes.

If multiple functions are provided for specifying the data, only the last one will be used.

There is also the convenience function make_template_var which is shown below.

# Order of arguments determine the order of the dimensions in OutputVar
# Names passed to `make_template_var` is not used for the names of the dimensions of the
# OutputVar
var =
    Template.make_template_var("t", "long", "lat"; abc = "def") |>
    Template.add_lon_dim(name = "lon", dim = [1.0, 2.0]) |>
    Template.add_time_dim(name = "t", dim = [3.0, 4.0]) |>
    Template.initialize

Attributes:
  abc => def
Dimension attributes:
  t:
    units => seconds
  lon:
    units => degrees_north
  lat:
    units => degrees_east
Data defined over:
  t   with 2 elements (3.0 to 4.0)
  lon with 2 elements (1.0 to 2.0)
  lat with 181 elements (-90.0 to 90.0)

API

Template

TemplateVar()

using ClimaAnalysis.Template
var =
    Template.TemplateVar() |>
    Template.add_attribs(long_name = "Test", short_name = "test") |>
    Template.add_time_dim(name = "t", dim = collect(0.0:2.0)) |>
    Template.add_lon_dim(units = "degrees") |>
    Template.add_lat_dim(axis = "Y") |>
    Template.one_to_n_data(collected = true) |>
    Template.initialize

initialize(var::TemplateVar)

add_attribs(; attribs...)

add_attribs!(var::TemplateVar; attribs...)

add_dim(dim_name, dim; dim_attribs...)

add_dim!(var::TemplateVar, dim_name, dim; dim_attribs...)

ones_data(; data_type = Float64)

ones_data!(var::TemplateVar; data_type = Float64)

zeros_data(; data_type = Float64)

zeros_data!(var::TemplateVar; data_type = Float64)

one_to_n_data(; data_type = Float64, collected = false)

one_to_n_data!(var::TemplateVar; data_type = Float64, collected = false)

make_template_var(dims::String...; attribs...)