ilamb3.dataset

Convenience functions which operate on datasets.

`accumulate_time`¶

function ilamb3.dataset.accumulate_time(dset, varname=None)

Return the time accumulation of the dataset.

Parameters

dset (xr.Dataset or xr.DataArray) – The input dataset/dataarray.
varname (str, optional) – The variable to integrate, must be given if a dataset is passed in.

Returns

xr.DataArray – The accumulation.

`cmip_cell_measures`¶

function ilamb3.dataset.cmip_cell_measures(ds, varname)

Add a DataArray for the cell_measures built from CMIP variables if present.

`coarsen_annual`¶

function ilamb3.dataset.coarsen_annual(dset)

Return the dataset coarsened to annual.

Parameters

dset (xr.Dataset) – The input dataset/dataarray.

Returns

xr.Dataset – The coarsened dataset.

`coarsen_dataset`¶

function ilamb3.dataset.coarsen_dataset(dset, varname, res=0.5)

Return the convervative spatially coarsened dataset.

Parameters

dset (xr.Dataset) – The input dataset.
varname (str) – The name of the dataarray to be coarsened.
res (float, optional) – The target resolution in degrees.

Returns

xr.Dataset – The coarsened dataset.

`compute_annual_mean`¶

function ilamb3.dataset.compute_annual_mean(ds)

One time-weighted mean per year of data.

For example, given 5 years of daily input, the result has 5 timesteps.

`compute_cell_measures`¶

function ilamb3.dataset.compute_cell_measures(data, varname=None)

Return the area of each spatial cell.

Parameters

data (xr.Dataset or xr.DataArray) – The input dataset.
varname (str, optional) – If a dataset is given, the DataArray for which we will compute the measures.

Returns

xr.DataArray – The cell areas.

Notes

It would be better to get these from the model data itself, but they are not always provided, particularly in reference data.

`compute_monthly_climatology`¶

function ilamb3.dataset.compute_monthly_climatology(ds)

One time-weighted mean per month of the year of data.

For example, given 5 years of daily input, the result has 12 timesteps.

`compute_monthly_mean`¶

function ilamb3.dataset.compute_monthly_mean(ds)

One time-weighted mean per month of data.

For example, given 5 years of daily input, the result has 60 (12*5) timesteps.

`compute_seasonal_climatology`¶

function ilamb3.dataset.compute_seasonal_climatology(data, seasons=['DJF', 'MAM', 'JJA', 'SON'], varname=None)

Time-weighted mean of each season across all complete years of data.

First subsets the input to only timesteps that fall within complete season-years using SeasonResampler(drop_incomplete=True) to identify them. Then, a single-pass time-weighted mean is calculated per season label. For example, given 5 years of daily data and seasons = [“DJF”, “MAM”, “JJA”, “SON”], the result has 4 timesteps, one for each season, where the data[varname] is the weighted mean of the 5 DJF seasons (incomplete seasons are dropped). The time coordinate of the result is the first day of each season, e.g. “1990-12-01” for DJF, “1990-03-01” for MAM, etc.

Parameters

data (xarray.Dataset) – The input dataset.
seasons (list of str, optional) – The seasons to use, default is [“DJF”, “MAM”, “JJA”, “SON”]. Can be any list of seasons supported by xarray.groupers.SeasonResampler.
varname (str, optional) – If data is a dataset, the variable name to subselect.

Returns

xarray.Dataset – The seasonal climatology of the input data, with the time dimension resampled to the seasons and reduced to a single time step per season.

Notes

The time-weighted mean is only computed if a dataset and variable name are provided. If a dataset is provided without a variable name, the regular mean is taken for all variables, which is not time-weighted. While this preserves the full dataset, variables like time_bounds will be incorrect because the new seasonal time steps are the first day of the season rather than the midpoint. Providing a variable name, which drops all other variables, is safer.

`compute_seasonal_mean`¶

function ilamb3.dataset.compute_seasonal_mean(ds, seasons=['DJF', 'MAM', 'JJA', 'SON'], varname=None)

One time-weighted mean per season of data.

For example, given 5 years of daily input starting in Dec and ending in Nov, the result has 20 (4*5) timesteps. The default seasons are [“DJF”, “MAM”, “JJA”, “SON”], but they can be any list of seasons supported by xr.groupers.SeasonResampler. Only complete seasons are included in the output. E.g., if input data starts in January, the first DJF will be incomplete and dropped, and if it ends in December, the last DJF will be incomplete and dropped, so the result will have 19 timesteps.

Parameters

ds (xarray.Dataset) – The input dataset.
seasons (list of str, optional) – The seasons to use, default is [“DJF”, “MAM”, “JJA”, “SON”].
varname (str, optional) – If ds is a dataset, the variable name to subselect.

Returns

xarray.Dataset – The seasonal mean of the input data, with the time dimension resampled to the seasons.

Notes

`compute_time_measures`¶

function ilamb3.dataset.compute_time_measures(dset)

Return the length of each time interval.

Parameters

dset (xr.Dataset or xr.DataArray) – The input dataset.

Returns

xr.DataArray – The time measures, the length of the time intervals, in days.

Notes

In order to integrate in time, we need the time measures. While this function is written for greatest flexibility, the most accurate time measures will be computed when a dataset is passed in where the ‘bounds’ on the ‘time’ dimension are labeled and part of the dataset.

`convert`¶

function ilamb3.dataset.convert(dset, unit, varname=None)

Convert the units of the dataarray.

Parameters

dset (xr.Dataset or xr.DataArray) – The dataset (specify varname) or dataarray who units you wish to convert.
unit (str) – The unit to which we will convert.
varname (str, optional) – If dset is a dataset, give the variable name to convert.

Returns

xr.Dataset or xr.DataArray – The converted dataset.

`convert_year_to_datetime`¶

function ilamb3.dataset.convert_year_to_datetime(ds)

Return the dataset with a integer ‘years’ dimension converted to a CF-compliant time.

`fix_missing_bounds_attrs`¶

function ilamb3.dataset.fix_missing_bounds_attrs(ds)

Add a bounds attribute if variable appears to exist.

`get_all_bounds_vars`¶

function ilamb3.dataset.get_all_bounds_vars(ds)

Return the data variables that are listed as ‘bounds’ in the dimensions.

`get_ancillary_variable`¶

function ilamb3.dataset.get_ancillary_variable(ds, varname)

Return the sub-dataset with the ancillary variables found in ds[varname].

`get_bounds_variable`¶

function ilamb3.dataset.get_bounds_variable(ds, varname)

Return the dataarray defined as the bounds of the input variable.

`get_coord_name`¶

function ilamb3.dataset.get_coord_name(dset, coord)

Return the name of the coord coordinate from the dataset.

Parameters

dset (xr.Dataset or xr.DataArray) – The input dataset/dataarray.
coord (str, one of {`lat`, `lon`}) – The coordinate to find in the dataset/dataarray.

Returns

str – The name of the coordinate.

See Also

get_dim_name,

A variant when the coordinate is a dimension.

`get_dim_name`¶

function ilamb3.dataset.get_dim_name(dset, dim)

Return the name of the dim dimension from the dataset.

Parameters

dset (xr.Dataset or xr.DataArray) – The input dataset/dataarray.
dim (str, one of {`time`, `lat`, `lon`, `depth`, `site`}) – The dimension to find in the dataset/dataarray.

Returns

str – The name of the dimension.

Notes

This function is meant to handle the problem that not all data calls the dimensions the same things (‘lat’, ‘Lat’, ‘latitude’, etc). We could replace this with cf-xarray functionality. My concern is that we want this to work even if the datasets are not CF-compliant (e.g. raw model output).

See Also

get_coord_name,

A variant when the coordinate is not a dimension.

`get_frequency_label`¶

function ilamb3.dataset.get_frequency_label(ds)

Return the CMIP time frequency label of the dataset. One of “3hr”, “6hr”, “day”, “mon”, “yr”, or “fx” if the dataset is not temporal.

`get_integer_dims`¶

function ilamb3.dataset.get_integer_dims(data)

Return which dimensions are integers and therefore likely indices.

`get_interval_uncertainty`¶

function ilamb3.dataset.get_interval_uncertainty(ds, varname)

Get the uncertainty interval from the variable.

`get_mean_spatial_resolution`¶

function ilamb3.dataset.get_mean_spatial_resolution(dset)

Return the mean spatial resolution of the dataset.

`get_mean_time_frequency`¶

function ilamb3.dataset.get_mean_time_frequency(ds)

Return the mean time frequency of the dataset.

`get_scalar_uncertainty`¶

function ilamb3.dataset.get_scalar_uncertainty(ds, varname)

Get a scalar uncertainty from the variable.

`get_time_extent`¶

function ilamb3.dataset.get_time_extent(dset, include_bounds=True)

Return the time extent of the dataset/dataarray.

Parameters

dset (xr.Dataset or xr.DataArray) – The input dataset.

Returns

tuple of xr.DataArray – The minimum and maximum time.

Notes

The function will prefer the values in the ‘bounds’ array if present.

`has_bounds`¶

function ilamb3.dataset.has_bounds(dset, dim, bounds)

Do the bounds for the input dataset and dimension exist?

`integrate_depth`¶

function ilamb3.dataset.integrate_depth(dset, varname=None, mean=False)

Return the depth integral or mean of the dataset.

Parameters

dset (xr.Dataset or xr.DataArray) – The dataset of dataarray to integrate.
varname (str, optional) – If dset is a dataset, the variable name to integrate.
mean (bool, optional) – Enable to take a depth mean.

Returns

xr.DataArray – The depth integral or sum.

`integrate_space`¶

function ilamb3.dataset.integrate_space(dset, varname, region=None, mean=False, weight=None)

Return the space integral or mean of the dataset.

Parameters

dset (xr.Dataset or xr.DataArray) – The input dataset/dataarray.
varname (str, optional) – The variable to integrate, must be given if a dataset is passed in.
region (str, optional) – The region label, one of ilamb3.Regions.regions or None to indicate that the whole spatial domain should be used.
mean (bool, optional) – Enable to divide the integral by the integral of the measures, returning the mean in a functional sense.
weight (xr.DataArray, optional) – Optional weight for the spatial integral. Used when mass weighting.

Returns

xr.Dataset – The integral or mean.

Notes

This interface is useful in our analysis as many times we want to report the total of a quantity (total mass of carbon) and other times we want the mean value (e.g. temperature). This allows the analysis code to read the same where a flag can be passed to change the behavior. We could consider replacing with xarray.integrate. However, as of v2023.6.0, this does not handle the pint units correctly, and can only be done in a single dimension at a time.

`integrate_time`¶

function ilamb3.dataset.integrate_time(data, varname=None, mean=False)

Return the time integral or time mean of a variable.

Climate analyses often need totals for extensive quantities (total carbon mass, accumulated precipitation) and means for intensive ones (temperature, mixing ratios). The mean flag selects between the two so a single call site can handle both cases.

Parameters

data (xarray.Dataset or xarray.DataArray) – The input dataset or dataarray.
varname (str, optional) – The variable to integrate, must be given if a dataset is passed in.
mean (bool, optional) – Enable to divide the integral by the integral of the measures, returning the mean in a functional sense.

Returns

xarray.DataArray – The time integral (or time mean if mean=True) of varname, with the time dimension removed. Other dimensions are preserved.

Notes

We do not use integrate because as of v2023.6.0, xarray does not handle the pint units correctly, and can only be applied to a single dimension at a time, leaving the spatial analog to be hand-coded. It also uses the trapezoidal rule, which should return the same integration, but could have small differences depending on how endpoints are interpreted.

`is_gridded`¶

function ilamb3.dataset.is_gridded(data)

Return if the dataarray is gridded, i.e., has latitude and longitude dimensions.

Parameters data : xr.DataArray or xr.Dataset

The input dataarray or dataset.

Returns

bool – True if latitude and longitude dimensions are present, False otherwise.

`is_latlon2d`¶

function ilamb3.dataset.is_latlon2d(data)

Return if the dataarray has 2D latitudes and longitudes.

`is_layered`¶

function ilamb3.dataset.is_layered(da)

Return if the dataarray is layered, i.e., has a depth dimension.

Parameters

da (xr.DataArray) – The input dataarray.

Returns

bool – True if a depth dimension is present, False otherwise.

`is_site`¶

function ilamb3.dataset.is_site(da)

Return if the dataarray is a collection of sites, i.e., has latitude and longitude coordinates but no corresponding dimensions.

Parameters

da (xr.DataArray) – The input dataarray.

Returns

bool – True if sites, False otherwise.

`is_temporal`¶

function ilamb3.dataset.is_temporal(data)

Return if the dataarray is temporal.

Parameters

data (xr.DataArray or xr.Dataset) – The input dataarray or dataset.

Returns

bool – True if time dimension is present, False otherwise.

`latlon2d_to_1d`¶

function ilamb3.dataset.latlon2d_to_1d(grid, da)

Return the da with 2D lat/lon interpolated at the grid resolution.

`ones_grid`¶

function ilamb3.dataset.ones_grid(resolution)

Return a regular lat/lon DataArray of ones at the given resolution.

`scale_by_water_density`¶

function ilamb3.dataset.scale_by_water_density(da, target)

Conditionally scale the dataarray by density if needed in the conversion.

Parameters

da (xr.DataArray) – The pint quantified input data array.
target (str) – The target conversion unit as a string.

Returns

xr.DataArray – The potentially water density scaled data array.

Notes

Most modeled hydrologic quantities tend to be output as a mass flux rate. However, a linear speed is often the preferred unit. For example a conversion such as kg m-2 s-1 to mm d-1. This is possible if scaled by the density of water which we do here conditionally if needed. Used by our convert() routine.

`sel`¶

function ilamb3.dataset.sel(dset, coord, cmin, cmax)

Return a selection of the dataset.

Parameters

dset (xr.Dataset) – The input dataset.
coord (str) – The coordinate to slice.
cmin (> Any) – The minimum coordinate value.
cmax (Any) – The maximum coordinate value.

Returns

xr.Dataset – The selected dataset.

Notes

The behavior of xarray.sel does not work for us here. We want to pick a slice of the dataset but where the value lies in between the coord bounds. Then we clip the min and max to be the limits of the slice.

`shift_lon`¶

function ilamb3.dataset.shift_lon(dset)

Return the dataset with longitudes shifted to [-180,180].

Parameters

dset (xr.Dataset) – The input dataset.

Returns

xr.Dataset – The longitude-shifted dataset.

`shift_time_by_years`¶

function ilamb3.dataset.shift_time_by_years(ds, years)

Return the dataset shifted by the given number of years.

`std_time`¶

function ilamb3.dataset.std_time(dset, varname=None)

Return the standard deviation of a variable in time.

Parameters

dset (xr.Dataset or xr.DataArray) – The input dataset/dataarray.
varname (str, optional) – The variable, must be given if a dataset is passed in.

Returns

xr.DataArray – The weighted standard deviation.

`which_cell_measures`¶

function ilamb3.dataset.which_cell_measures(data, varname)

Return the name of the cell measures variable for the given variable, if present.

accumulate_time¶

cmip_cell_measures¶

coarsen_annual¶

coarsen_dataset¶

compute_annual_mean¶

compute_cell_measures¶

compute_monthly_climatology¶

compute_monthly_mean¶

compute_seasonal_climatology¶

compute_seasonal_mean¶

compute_time_measures¶

convert¶

convert_year_to_datetime¶

fix_missing_bounds_attrs¶

get_all_bounds_vars¶

get_ancillary_variable¶

get_bounds_variable¶

get_coord_name¶

get_dim_name¶

get_frequency_label¶

get_integer_dims¶

get_interval_uncertainty¶

get_mean_spatial_resolution¶

get_mean_time_frequency¶

get_scalar_uncertainty¶

get_time_extent¶

has_bounds¶

integrate_depth¶

integrate_space¶

integrate_time¶

is_gridded¶

is_latlon2d¶

is_layered¶

is_site¶

is_temporal¶

latlon2d_to_1d¶

ones_grid¶

scale_by_water_density¶

sel¶

shift_lon¶

shift_time_by_years¶

std_time¶

which_cell_measures¶

`accumulate_time`¶

`cmip_cell_measures`¶

`coarsen_annual`¶

`coarsen_dataset`¶

`compute_annual_mean`¶

`compute_cell_measures`¶

`compute_monthly_climatology`¶

`compute_monthly_mean`¶

`compute_seasonal_climatology`¶

`compute_seasonal_mean`¶

`compute_time_measures`¶

`convert`¶

`convert_year_to_datetime`¶

`fix_missing_bounds_attrs`¶

`get_all_bounds_vars`¶

`get_ancillary_variable`¶

`get_bounds_variable`¶

`get_coord_name`¶

`get_dim_name`¶

`get_frequency_label`¶

`get_integer_dims`¶

`get_interval_uncertainty`¶

`get_mean_spatial_resolution`¶

`get_mean_time_frequency`¶

`get_scalar_uncertainty`¶

`get_time_extent`¶

`has_bounds`¶

`integrate_depth`¶

`integrate_space`¶

`integrate_time`¶

`is_gridded`¶

`is_latlon2d`¶

`is_layered`¶

`is_site`¶

`is_temporal`¶

`latlon2d_to_1d`¶

`ones_grid`¶

`scale_by_water_density`¶

`sel`¶

`shift_lon`¶

`shift_time_by_years`¶

`std_time`¶

`which_cell_measures`¶