xarray.Dataset.temporal.climatology#
- Dataset.temporal.climatology(data_var, freq, weighted=True, keep_weights=False, reference_period=None, season_config={'custom_seasons': None, 'dec_mode': 'DJF', 'drop_incomplete_djf': False, 'drop_incomplete_seasons': False})#
Returns a Dataset with the climatology of a data variable.
Data is grouped into the labeled time point for the averaging operation. Time bounds are used for generating weights to calculate weighted climatology (refer to the
weighted
parameter documentation below).Deprecated since version v0.8.0: The
season_config
dictionary argument"drop_incomplete_djf"
is being deprecated. Please use"drop_incomplete_seasons"
instead.- Parameters:
data_var (
str
) – The key of the data variable for calculating climatology.freq (
Frequency
) – The time frequency to group by.“season”: groups by season for the seasonal cycle climatology.
“month”: groups by month for the annual cycle climatology.
“day”: groups by (month, day) for the daily cycle climatology. 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 [1] 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.
Note that weights are assigned by the labeled time point. If the dataset includes timepoints that span across typical boundaries (e.g., a timepoint on 2020-06-01 with bounds that begin in May 2020 and 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 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. 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.- “drop_incomplete_seasons” (bool, by default False)
Seasons are considered incomplete if they do not have all of the required months to form the season. This argument supersedes “drop_incomplete_djf”. For example, if we have the time coordinates [“2000-11-16”, “2000-12-16”, “2001-01-16”, “2001-02-16”] and we want to group seasons by “ND” (“Nov”, “Dec”) and “JFM” (“Jan”, “Feb”, “Mar”).
- [“2000-11-16”, “2000-12-16”] is considered a complete “ND”
season since both “Nov” and “Dec” are present.
- [“2001-01-16”, “2001-02-16”] is considered an incomplete “JFM”
season because it only has “Jan” and “Feb”. Therefore, these time coordinates are dropped.
- “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. This argument is superceded by “drop_incomplete_seasons” and will be deprecated in a future release.
- “dec_mode” (Literal[“DJF”, “JFD”], by default “DJF”)
The mode for the season that includes December in the list of list of pre-defined seasons (“DJF”/”JFD”, “MAM”, “JJA”, “SON”). This config is ignored if the
custom_seasons
config is set.“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”.
- “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’)
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 climatology of a data variable.
References
Notes
When using weighted averages, the weights are assigned based on the timepoint 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 expected behavior, but it’s possible that data could span across typical temporal boundaries. 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 weight would be assigned to June, 2020, which would be incorrect (15 days of weight should be assigned to May and 15 days of weight should be assigned to June). This issue could plausibly arise when using pentad data.
Examples
Get a data variable’s seasonal climatology:
>>> ds_season = ds.temporal.climatology( >>> "ts", >>> "season", >>> season_config={ >>> "dec_mode": "DJF", >>> "drop_incomplete_seasons": True >>> } >>> ) >>> ds_season.ts >>> >>> ds_season = ds.temporal.climatology( >>> "ts", >>> "season", >>> season_config={"dec_mode": "JFD"} >>> ) >>> ds_season.ts
Get a data variable’s seasonal climatology with custom seasons:
>>> custom_seasons = [ >>> ["Jan", "Feb", "Mar"], # "JanFebMar" >>> ["Apr", "May", "Jun"], # "AprMayJun" >>> ["Jul", "Aug", "Sep"], # "JulAugSep" >>> ["Oct", "Nov", "Dec"], # "OctNovDec" >>> ] >>> >>> ds_season_custom = ds.temporal.climatology( >>> "ts", >>> "season", >>> season_config={"custom_seasons": custom_seasons} >>> )
Get
climatology()
operation attributes:>>> ds_season_with_djf.ts.attrs { 'operation': 'temporal_avg', 'mode': 'climatology', 'freq': 'season', 'weighted': 'True', 'dec_mode': 'DJF', 'drop_incomplete_seasons': 'False' }