arctichoke.analysis.sum_by_year
===============================

.. py:module:: arctichoke.analysis.sum_by_year


Functions
---------

.. autoapisummary::

   arctichoke.analysis.sum_by_year.sum_by_year


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

.. py:function:: sum_by_year(dataset: (str, [str], xarray.DataArray, xarray.Dataset), attr_long_name: str = None, attr_units: str = None, save_as: str = None, verbose: bool = False, **kwargs)

   Sum a dataset by year along the time axis.

   Groups the dataset by year and sums each year.
   This results in one time step for each year in the given dataset.

   :param dataset: The dataset of which to sum by year.
   :type dataset: `str`, list of `str`, `xarray.DataArray`, `xarray.Dataset`
   :param attr_long_name: The name of the variable for which to put in the `long_name` attribute.
                          Default is `None`, which uses the original `long_name` plus `'Yearly Sum of '`.
   :type attr_long_name: `str`, `None`, optional
   :param attr_units: The units of the variable for which to put in the `units` attribute.
                      Default is `None`, which uses the original `units` plus `'_per_year'`.
   :type attr_units: `str`, `None`, 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: **dataset** -- A dataset where the data has been summed by year.
   :rtype: `xarray.Dataset`

   .. rubric:: Examples

   >>> from arctichoke.dataset.example_dataset import make_example_dataset
   >>> dataset = make_example_dataset(n=3, time_axis=True)
   >>> dataset['test_var'].values
   array([[[0., 1., 2.],
           [3., 4., 5.],
           [6., 7., 8.]],

          [[0., 1., 2.],
           [3., 4., 5.],
           [6., 7., 8.]]])
   >>> from arctichoke.analysis.sum_by_year import sum_by_year
   >>> dataset_year_sum = sum_by_year(dataset)
   >>> dataset_year_sum['test_var_year_sum'].values
   array([[[ 0.,  2.,  4.],
           [ 6.,  8., 10.],
           [12., 14., 16.]]])