Skip to content

Seasonality

Seasonality Detection Algorithms

This module provides an xarray accessor to carry out analysis of seasons on xarray timeseries.

Seasonality

Bases: AccessorBase

Numba implementations for 1D seasonality computation functions.

get_dt_from_idx(ref_dt=None, time_dim_name='time')

Convert sos eos index raster into datetime raster. Use this function on a 3D or 4D DataArray of indices structured as (idx, x, y) or (year, idx, x, y).

Parameters:

Name Type Description Default
ref_dt DataArray

The long-term datetime series. Recommend to use the coordinates value of the observational raster.

 None
time_dim_name str

The name of the time dimension in ref_dt.

 'time'

Returns:

Type Description
Dataset

A datetime raster of the same size as the index array. No value is marked as
Dataset

np.datetime64('NaT').

get_seasons_by_anomaly(input_core_dim='time', period=36, mask=None, bimodal_mask=None, soc_eoc=None, search_wd_uni=5, search_wd_bi=2, output_type='soc_eoc_ts')

Detect seasons via anomaly-based method from an observational raster. Use this function on a 3D DataArray that contains observational time series data structured as (time, x, y).

Parameters:

Name Type Description Default
input_core_dim str

Core dimension of the series along which to perform the calculation.

 'time'
period int

The number of time step points per period.

 36
mask Optional[Union[bool, DataArray]]

2D DataArray (x, y) of all-year humid&arid mask.

 None
bimodal_mask Optional[DataArray]

2D DataArray (x, y) specifying whether a pixel is classified as bimodal area, True for bimodal, False for unimodal, nan for ocean. If omitted, it is calculated in Step 1

 None
soc_eoc Optional[DataArray]

3D DataArray (4, x, y) of climatological start and end. If omitted, it is calculated in Step 2.

 None
search_wd_uni int

The searching window for unimodal area when extracting SoS and EoS from SoC and EoC. The search interval is represented as [SoC - search_wd_uni, EoC + search_wd_uni].

 5
search_wd_bi int

Same as search_wd_uni, the searching window for bimodal area.

 2
output_type str
  • 'soc_eoc_ts': Climatological SoC EoC indices with the size (4, x, y): -> For unimodal area: np.array(soc1, eoc1, np.nan, np.nan) -> For bimodal area: np.array(soc1, eoc1, soc2, eoc2)
  • 'sos_eos_ts': SoS EoS indices for each year (first year and last year excluded), the size is (year*4, x, y): -> For unimodal area: np.array(soc1, eoc1, np.nan, np.nan, soc2, eoc2..., np.nan, np.nan) -> For bimodal area: np.array(soc1, eoc1, soc2, eoc2, ..., socn, eocn)
 'soc_eoc_ts'

Returns:

Type Description
Dataset

Depending on the chosen output_type, returns the corresponding output xr.DataArray.
Additional information

Reference: The onset and cessation of seasonal rainfall over Africa:ß https://agupubs.onlinelibrary.wiley.com/doi/10.1002/2016JD025428

get_seasons_by_threshold(input_core_dim='time', s_threshold=50, e_threshold=50, mask=None, repeat_end_constraint=1, period=36, min_duration=3, soc_eoc_idx=None, search_wd=3, max_seasons=2, output_type='yearly_idxs')

Detect seasons via threshold-based method from an observational raster. Use this function on a 3D DataArray that contains observational time series data structured as (time, x, y).

Parameters:

Name Type Description Default
input_core_dim str

The name of the time dimension.

 'time'
s_threshold Optional[Union[float, int, DataArray]]

2D DataArray (x, y) or a number of the starting threshold.

 50
e_threshold Optional[Union[float, int, DataArray]]

2D DataArray (x, y) or a number of the ending threshold.

 50
mask Optional[Union[bool, DataArray]]

2D DataArray (x, y) of all-year humid&arid mask.

 None
repeat_end_constraint int

An integer n greater than 0, representing 'n consecutive time steps below e_threshold' rule.

 1
period float

The number of time steps per year.

 36
min_duration float

The minimum length of a season.

 3
soc_eoc_idx DataArray

3D DataArray (x, y, max_seasons*2) or a np.array(soc_1, eoc_1, soc_2, eoc_2) of climatological start and end. soc_1 and soc_2 should range from 0 to (period-1). Use this parameter to set searching ranges for extracting yearly indices. Seasons will be detected within a slightly extended interval search_wd.

 None
search_wd float

The searching window to construct the interval, [start_index - search_wd, end_index + search_wd].

 3
max_seasons int

The maximum number of seasons per year. The resulting raster will have 2 * max_seasons positions along the index dimension.

 2
output_type str
  • 'mts_idxs': Masked time series raster with the same size as the input. 1) nan for ocean, humid/arid mask and out-of-season pixels; 2) positional index for the sos for within-season pixels
  • 'mts_binary': Binary mask raster with the same size as the input. 1) nan for ocean and humid/arid mask; 2) True for within-season pixels; 3) False for out-of-season pixels.
  • 'soc_eoc_idxs': 3D(lat, lon, soc_eoc_idx) climatological starts and ends, with soc_eoc_idx of dimension max_seasons * 2 1) nan for ocean and humid/arid mask; 2) -1 for all-year-humid pixels; 3) an integer index for other pixels.
  • 'yearly_idxs': 4D(lat, lon, idx, year) yearly starts and ends, with idx of dimension max_seasons * 2 1) nan for ocean and humid/arid mask; 2) -1 for all-year-humid pixels; 3) an integer index for other pixels.
 'yearly_idxs'

Returns:

Type Description
Dataset

Depending on the chosen output_type, returns the corresponding output xr.DataArray.

harmonic_analysis(input_core_dim='time', rolling_periods=None, period=36, mask=None, output_type='ratio')

Determine annual/biannual regime via harmonic analysis for an observational raster. Use this function on a 3D DataArray that contains observational time series data structured as (time, x, y).

Parameters:

Name Type Description Default
input_core_dim str

The name of the time dimension.

 'time'
rolling_periods int

Estimate regime over a rolling window of n periods

 None
period int

The number of time points per year.

 36
mask Optional[Union[bool, DataArray]]

2D DataArray (x, y) of all-year humid&arid mask.

 None
output_type str
  • 'ratio': Amplitude ratio.
  • 'bimodal_mask': A mask to define whether it is bimodal. 1) nan for ocean and humid/arid mask; 2) True for bimodal area; 3) False for unimodal area.
 'ratio'

Returns:

Type Description
Dataset

Depending on the chosen output_type, returns the corresponding output xr.DataArray.

amp_reg_1d(y, period, mask, res)

1D implementation of amplitude ratio, determined by comparing the second harmonic's amplitude to that of the first harmonic.

get_season_dates(soc_eoc, date, include_active=True)

Get the dates for the most recent completed seasons.

Parameters:

Name Type Description Default
soc_eoc Dataset

Grid of climatological start and end of seasons with dimensions 'soc_eoc_idx', 'latitude', 'longitude'.

 required
date date

Date at which to evaluate the most recent seaons.

 required
include_active bool

bool, default True, of whether to include the active season

 True

Returns:

Type Description

ss1_dates, ss2_dates: Grids of np.datetime64 start and end dates

idx2date_1d(idx, time_array)

1D function converting indices into datetime array.

mts2soceoc_1d(mts, period, min_duration, start_index, end_index, res)

Extract climatological start and end within the start_index to end_index range, subject to a length of min_duration time steps, from extended masked time series.

mts2yearly_1d(mts, period, min_duration, search_wd, soc_eoc_idx, res)

Extract yearly start and end within a specific searching range from extended masked time series. If two seasons start in a single climatological range, merge them into one season.

ots2mts_1d(x, s_threshold, e_threshold, mask, repeat_end_constraint, res)

1d implementation of getting masked time series, with the following pixel categories: 1) ocean & mask pixels: -9 2) within-season pixels: marked with the positional index of the season start 3) out-of-season pixels: nan

soc_eoc_1d(y, bimodal_mask, period, res)

1D implementation of extracting climatological start and end (SoC, EoC) from cumulative sum of anomaly.

sos_eos_1d(y, period, soc_eoc_idx, bimodal_mask, q_bar, search_wd_uni, search_wd_bi, res)

1D implementation of extracting start and end of season (SoS, EoS) for every year. The search region is a fixed empirical interval defined by climatological start and end.