xarray.Dataset.temporal.departures — xCDAT Documentation (2024)

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

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

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

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 (ifpresent) are dropped to avoid inconsistencies when calculatingclimatologies. Refer to [2] for more details on thisimplementation decision.

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

  Weights are calculated by first determining the length of time foreach coordinate point using the difference of its upper and lowerbounds. The time lengths are grouped, then each time length isdivided by the total sum of the time lengths to get the weight ofeach coordinate point.

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

  Note that weights are assigned by the labeled time point. If thedataset includes timepoints that span across typical boundaries(e.g., a timepoint on 2020-06-01 with bounds that begin in May 2020and end in June 2020), the weights will not be assigned properly.See explanation in the Notes section below.

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

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

• season_config (SeasonConfigInput, optional) – A dictionary for “season” frequency configurations. If configs forpredefined seasons are passed, configs for custom seasons areignored 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 isactually “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 seasonsIncomplete DJF seasons include the start year Jan/Feb and theend year Dec.

  Configs for custom seasons:

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

    List of sublists containing month strings, with each sublistrepresenting 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 – The Dataset containing the departures for a data var’s climatology.

Notes

When using weighted averages, the weights are assigned based on thetimepoint value. For example, a time point of 2020-06-15 with bounds(2020-06-01, 2020-06-30) has 30 days of weight assigned to June, 2020(e.g., for an annual average calculation). This would be expectedbehavior, but it’s possible that data could span across typical temporalboundaries. For example, a time point of 2020-06-01 with bounds(2020-05-16, 2020-06-15) would have 30 days of weight, but this weightwould be assigned to June, 2020, which would be incorrect (15 days ofweight should be assigned to May and 15 days of weight should beassigned to June). This issue could plausibly arise when using pentaddata.

This method uses xarray’s grouped arithmetic as a shortcut for mappingover all unique labels. Grouped arithmetic works by assigning a groupinglabel to each time coordinate of the observation data based on theaveraging mode and frequency. Afterwards, the corresponding climatologyis removed from the observation data at each time coordinate based onthe 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'}