arctichoke.analysis.trend_in_time
=================================

.. py:module:: arctichoke.analysis.trend_in_time


Functions
---------

.. autoapisummary::

   arctichoke.analysis.trend_in_time.trend_in_time
   arctichoke.analysis.trend_in_time.mask_where_all_zero


Module Contents
---------------

.. py:function:: 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.

   :param dataset: The dataset of which to find the sum across time.
   :type dataset: `str`, list of `str`, `xarray.Dataset`, `xarray.DataArray`
   :param var: The variable in `dataset` for which to take the trend across time.
               This is required if `dataset` is an `xarray.Dataset`.
               Default is `None`.
   :type var: `str`, `None`, optional
   :param time_dim: The name of the time dimension over which to find the trend.
                    Default is `year`.
   :type time_dim: `str`, optional
   :param mask_where_zero_across_time: 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`.
   :type mask_where_zero_across_time: `bool`, optional
   :param save_as: The file name to which to save the modified dataset.
                   Default is `None`, which doesn't save the dataset to a file.
   :type save_as: `str`, `None`, optional
   :param verbose: Whether to verbosely output information as the function executes.
                   Default is `False`.
   :type verbose: `bool`, optional
   :param \*\*kwargs: Keyword arguments to pass to `xr.sum()`.

   :returns: **trends_dataset** -- A dataset with the trends in time for the specified variable.
   :rtype: `xarray.Dataset` or `xarray.DataArray`

   .. rubric:: 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]])


.. py:function:: 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.

   :param dataset: The dataset of which to mask zeros across time.
   :type dataset: `str`, list of `str`, `xarray.Dataset`, `xarray.DataArray`
   :param var: The variable in `dataset` for which to mask zeros across time.
               This is required if `dataset` is an `xarray.Dataset`.
               Default is `None`.
   :type var: `str`, `None`, optional
   :param time_dim: The name of the time dimension over which to find zeros.
                    Default is `year`.
   :type time_dim: `str`, optional
   :param verbose: Whether to verbosely output information as the function executes.
                   Default is `False`.
   :type verbose: `bool`, optional

   :returns: **trends_dataset** -- A dataset with the trends in time for the specified variable.
   :rtype: `xarray.Dataset` or `xarray.DataArray`

   .. rubric:: Examples

   >>> import xarray as xr
   >>> xr_ds = xr.Dataset({
   >>>     'test_var': (
   >>>         ['t', 'i', 'j'],
   >>>         [[[ 0,  0,  0],
   >>>         [ 1,  1,  1],
   >>>         [ 0,  0,  0]],
   >>>         [[ 0,  1,  1],
   >>>         [ 1,  0,  0],
   >>>         [ 0,  0,  0]]]
   >>>     )
   >>> })
   >>> xr_ds['test_var'].values
   array([[[0, 0, 0],
           [1, 1, 1],
           [0, 0, 0]],

          [[0, 1, 1],
           [1, 0, 0],
           [0, 0, 0]]])
   >>> from arctichoke.analysis.trend_in_time import mask_where_all_zero
   >>> xr_ds_nan = mask_where_all_zero(
   >>>     xr_ds,
   >>>     'test_var',
   >>>     time_dim = 't'
   >>> )
   >>> xr_ds_nan['test_var'].values
   array([[[nan,  0.,  0.],
           [ 1.,  1.,  1.],
           [nan, nan, nan]],

          [[nan,  1.,  1.],
           [ 1.,  0.,  0.],
           [nan, nan, nan]]])