arctichoke.analysis.trend_in_time

Functions

`trend_in_time`(dataset[, var, time_dim, ...])	Find the trend for each grid cell along the time axis.
`mask_where_all_zero`(dataset[, var, time_dim, verbose])	Masks out grid cells which are zero across time.

Module Contents

arctichoke.analysis.trend_in_time.trend_in_time(dataset: str, [str], xarray.Dataset, xarray.DataArray, var: str = None, time_dim: str = 'year', mask_where_zero_across_time: bool = False, save_as: str = None, verbose: bool = False, **kwargs)

Find the trend for each grid cell along the time axis.

For each grid cell in the dataset, find the trend in time for the given variable. This results in a new dataset without a time dimension.

Parameters:

dataset (str, list of str, xarray.Dataset, xarray.DataArray) – The dataset of which to find the sum across time.
var (str, None, optional) – The variable in dataset for which to take the trend across time. This is required if dataset is an xarray.Dataset. Default is None.
time_dim (str, optional) – The name of the time dimension over which to find the trend. Default is year.
mask_where_zero_across_time (bool, optional) – Whether to mask out grid cells which have zero as a value across the entire time dimension using mask_where_all_zero(). Default is False.
save_as (str, None, optional) – The file name to which to save the modified dataset. Default is None, which doesn’t save the dataset to a file.
verbose (bool, optional) – Whether to verbosely output information as the function executes. Default is False.
**kwargs – Keyword arguments to pass to xr.sum().

Returns:

trends_dataset – A dataset with the trends in time for the specified variable.

Return type:

xarray.Dataset or xarray.DataArray

Examples

>>> from arctichoke.dataset.example_dataset import make_example_dataset
>>> from arctichoke.path.manipulate_paths import make_file_path
>>> # Create multiple example test files
>>> test_file_dir = 'tests/test_analysis/example_datasets'
>>> make_file_path(test_file_dir)
>>> test_file_names = [
>>>     f"{test_file_dir}/example_dataset_0.nc",
>>>     f"{test_file_dir}/example_dataset_1.nc",
>>>     f"{test_file_dir}/example_dataset_2.nc",
>>> ]
>>> offsets = [0, 1, 3]
>>> for i in range(len(test_file_names)):
>>>     make_example_dataset(
>>>         n=3,
>>>         offset=offsets[i],
>>>         test_var_name='test_var',
>>>         time_axis=(2000+i),
>>>         save_as=test_file_names[i],
>>>     )
>>> import xarray as xr
>>> test_dataset = xr.open_mfdataset(test_file_names)
>>> test_dataset['test_var'].values
array([[[ 0.,  1.,  2.],
        [ 3.,  4.,  5.],
        [ 6.,  7.,  8.]],

[[ 0., 1., 2.],
[ 3., 4., 5.], [ 6., 7., 8.]],

[[ 1., 2., 3.],
[ 4., 5., 6.], [ 7., 8., 9.]],

[[ 1., 2., 3.],
[ 4., 5., 6.], [ 7., 8., 9.]],

[[ 3., 4., 5.],
[ 6., 7., 8.], [ 9., 10., 11.]],

[[ 3., 4., 5.],
[ 6., 7., 8.], [ 9., 10., 11.]]])

>>> from arctichoke.analysis.trend_in_time import trend_in_time
>>> test_trends = trend_in_time(
>>>     test_dataset,
>>>     var='test_var',
>>>     time_dim='time',
>>> )
>>> test_trends['test_var_trends'].values
array([[1.49369, 1.49369, 1.49369],
       [1.49369, 1.49369, 1.49369],
       [1.49369, 1.49369, 1.49369]])

arctichoke.analysis.trend_in_time.mask_where_all_zero(dataset: str, [str], xarray.Dataset, xarray.DataArray, var: str = None, time_dim: str = 'year', verbose: bool = False)

Masks out grid cells which are zero across time.

For each grid cell in the dataset, if that grid cell is equal to zero across the entire time dimension, set those values to nan. This will allow masking out grid cells which have no trend in time not because the values don’t change, but because they are missing data. Note, this is done by summing across time to find which cells have a sum of zero, so this should not be used for any variable which could have negative values.