xarray.Dataset.temporal.group_average

Dataset.temporal.group_average(data_var, freq, weighted=True, keep_weights=False, season_config={'custom_seasons': None, 'dec_mode': 'DJF', 'drop_incomplete_djf': False})

Returns a Dataset with average of a data variable by time group.

Time bounds are used for generating weights to calculate weighted group averages (refer to the weighted parameter documentation below).

Parameters

• data_var (str) – The key of the data variable for calculating time series averages.

• freq (Frequency) – The time frequency to group by.

  • “year”: groups by year for yearly averages.

  • “season”: groups by (year, season) for seasonal averages.

  • “month”: groups by (year, month) for monthly averages.

  • “day”: groups by (year, month, day) for daily averages.

  • “hour”: groups by (year, month, day, hour) for hourly averages.

• weighted (bool, optional) – Calculate averages using weights, by default True.

  Weights are calculated by first determining the length of time for each coordinate point using the difference of its upper and lower bounds. The time lengths are grouped, then each time length is divided by the total sum of the time lengths to get the weight of each coordinate point.

  The weight of masked (missing) data is excluded when averages are calculated. This is the same as giving them a weight of 0.

• keep_weights (bool, optional) – If calculating averages using weights, keep the weights in the final dataset output, by default False.

• season_config (SeasonConfigInput, optional) – A dictionary for “season” frequency configurations. If configs for predefined seasons are passed, configs for custom seasons are ignored and vice versa.

  Configs for predefined seasons:

  • “dec_mode” (Literal[“DJF”, “JFD”], by default “DJF”)

    The mode for the season that includes December.

    • “DJF”: season includes the previous year December.

    • “JFD”: season includes the same year December.

      Xarray labels the season with December as “DJF”, but it is actually “JFD”.

  • “drop_incomplete_djf” (bool, by default False)

    If the “dec_mode” is “DJF”, this flag drops (True) or keeps (False) time coordinates that fall under incomplete DJF seasons Incomplete DJF seasons include the start year Jan/Feb and the end year Dec.

  Configs for custom seasons:

  • “custom_seasons” ([List[List[str]]], by default None)

    List of sublists containing month strings, with each sublist representing a custom season.

    • Month strings must be in the three letter format (e.g., ‘Jan’)

    • Each month must be included once in a custom season

    • Order of the months in each custom season does not matter

    • Custom seasons can vary in length

    >>> # Example of custom seasons in a three month format:
    >>> custom_seasons = [
    >>>     ["Jan", "Feb", "Mar"],  # "JanFebMar"
    >>>     ["Apr", "May", "Jun"],  # "AprMayJun"
    >>>     ["Jul", "Aug", "Sep"],  # "JulAugSep"
    >>>     ["Oct", "Nov", "Dec"],  # "OctNovDec"
    >>> ]
    

Returns

xr.Dataset – Dataset with the average of a data variable by time group.

Examples

Get seasonal averages for a data variable:

>>> ds_season = ds.temporal.group_average(
>>>     "ts",
>>>     "season",
>>>     season_config={
>>>         "dec_mode": "DJF",
>>>         "drop_incomplete_season": True
>>>     }
>>> )
>>> ds_season.ts
>>>
>>> ds_season_with_jfd = ds.temporal.group_average(
>>>     "ts",
>>>     "season",
>>>     season_config={"dec_mode": "JFD"}
>>> )
>>> ds_season_with_jfd.ts

Get seasonal averages with custom seasons for a data variable:

>>> custom_seasons = [
>>>     ["Jan", "Feb", "Mar"],  # "JanFebMar"
>>>     ["Apr", "May", "Jun"],  # "AprMayJun"
>>>     ["Jul", "Aug", "Sep"],  # "JulAugSep"
>>>     ["Oct", "Nov", "Dec"],  # "OctNovDec"
>>> ]
>>>
>>> ds_season_custom = ds.temporal.group_average(
>>>     "ts",
>>>     "season",
>>>     season_config={"custom_seasons": custom_seasons}
>>> )

Get the average() operation attributes:

>>> ds_season_with_djf.ts.attrs
{
    'operation': 'temporal_avg',
    'mode': 'average',
    'freq': 'season',
    'weighted': 'True',
    'dec_mode': 'DJF',
    'drop_incomplete_djf': 'False'
}