xarray.Dataset.temporal.departures#

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

Returns a Dataset with the climatological departures (anomalies) for a data variable.

In climatology, “anomalies” refer to the difference between the value during a given time interval (e.g., the January average surface air temperature) and the long-term average value for that time interval (e.g., the average surface temperature over the last 30 Januaries).

Parameters:

  • data_var (str) – The key of the data variable for calculating departures.

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

    • “season”: groups by season for the seasonal cycle departures.

    • “month”: groups by month for the annual cycle departures.

    • “day”: groups by (month, day) for the daily cycle departures. If the CF calendar type is "gregorian", "proleptic_gregorian", or "standard", leap days (if present) are dropped to avoid inconsistencies when calculating climatologies. Refer to [2] for more details on this implementation decision.

  • 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 taken. 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.

  • reference_period (Optional[Tuple[str, str]], optional) – The climatological reference period, which is a subset of the entire time series and used for calculating departures. This parameter accepts a tuple of strings in the format ‘yyyy-mm-dd’. For example, ('1850-01-01', 1899-12-31'). If no value is provided, the climatological reference period will be the full period covered by the dataset.

  • 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"],  # "JunJulAug"
>>>     ["Oct", "Nov", "Dec"],  # "OctNovDec"
>>> ]
Returns:

xr.Dataset – The Dataset containing the departures for a data var’s climatology.

Notes

This method uses xarray’s grouped arithmetic as a shortcut for mapping over all unique labels. Grouped arithmetic works by assigning a grouping label to each time coordinate of the observation data based on the averaging mode and frequency. Afterwards, the corresponding climatology is removed from the observation data at each time coordinate based on the matching labels.

Refer to [3] to learn more about how xarray’s grouped arithmetic works.

References

Examples

Get a data variable’s annual cycle departures:

>>> ds_depart = ds_climo.temporal.departures("ts", "month")

Get the departures() operation attributes:

>>> ds_depart.ts.attrs
{
    'operation': 'departures',
    'frequency': 'season',
    'weighted': 'True',
    'dec_mode': 'DJF',
    'drop_incomplete_djf': 'False'
}