easyclimate.filter.spectrum

Spatio-temporal Spectrum Analysis

Functions

calc_time_spectrum(→ tuple[xarray.DataArray, ...)

Calculate the time spectrum of a multi-dimensional xarray.DataArray along the time dimension.

calc_mean_fourier_amplitude(→ xarray.DataArray)

Calculate mean Fourier amplitude between specified period bounds.

filter_fourier_harmonic_analysis(, filter_type, , ] =, ...)

Apply Fourier harmonic analysis to filter an dataset along a time dimension.

Module Contents

easyclimate.filter.spectrum.calc_time_spectrum(data: xarray.DataArray, time_dim: str = 'time', inv: bool = False) → tuple[xarray.DataArray, xarray.DataArray]

Calculate the time spectrum of a multi-dimensional xarray.DataArray along the time dimension.

Parameters

dataxarray.DataArray

Input data with at least a time dimension.

time_dimstr, optional

Name of the time dimension in the DataArray, by default 'time'

invbool, optional

If True, use forward FFT instead of inverse, by default False

Returns

easyclimate.DataNode, containing:

  • Amplitude spectrum (same dimensions as input but with freq and period dimension)

  • Frequency or period values

Tip

The function automatically handles even/odd length time series and removes the zero-frequency component. The amplitude is calculated as the power spectrum (\(|\mathrm{fft}|^2\)).

easyclimate.filter.spectrum.calc_mean_fourier_amplitude(data: xarray.DataArray, time_dim: str = 'time', lower: float = None, upper: float = None) → xarray.DataArray

Calculate mean Fourier amplitude between specified period bounds.

Parameters

dataxarray.DataArray

Input data with at least a time dimension. Can have additional dimensions.

time_dimstr, optional

Name of the time coordinate in the DataArray, by default 'time'

lowerfloat

Lower bound of period range

upperfloat

Upper bound of period range

Returns

xarray.DataArray

Mean amplitude within specified period range, with same dimensions as input but without time dimension.

Tip

easyclimate.filter.spectrum.filter_fourier_harmonic_analysis(da: xarray.DataArray, time_dim: str = 'time', period_bounds: tuple = (None, None), filter_type: Literal['highpass', 'lowpass', 'bandpass'] = 'bandpass', sampling_interval: float = 1.0, apply_window: bool = True) → xarray.DataArray

Apply Fourier harmonic analysis to filter an dataset along a time dimension.

Parameters

daxarray.DataArray

Input data array with a time dimension (e.g., z200 with dims [time, lat, lon]).

time_dimstr, optional

Name of the time dimension (default: ‘time’).

period_boundstuple, optional

Period range for filtering in units of sampling_interval (e.g., years if sampling_interval=1). Format: (min_period, max_period). Use None for unbounded limits.

  • High-pass: (None, max_period) to retain periods < max_period.

  • Low-pass: (min_period, None) to retain periods > min_period.

  • Bandpass: (min_period, max_period) to retain min_period < periods < max_period.

filter_typestr, optional

Type of filter: 'highpass', 'lowpass', or 'bandpass' (default: 'bandpass').

sampling_intervalfloat, optional

Sampling interval of the time dimension (default: 1.0, e.g., 1 year for annual data).

apply_windowbool, optional

Apply a Hann window to reduce boundary effects (default: True).

Returns

xarray.DataArray

Filtered data array with same dimensions and coordinates as input.

Examples

>>> # Create example data
>>> ds = xr.DataArray(
...    np.random.randn(56, 90, 180),
...    dims=['time', 'lat', 'lon'],
...    coords={
...        'time': np.arange(1948, 2004),
...        'lat': np.linspace(-90, 90, 90),
...        'lon': np.linspace(0, 360, 180, endpoint=False)
...    },
...    name='z200'
... )
>>> # Apply low-pass filter to retain periods > 8 years
>>> ds_filtered = filter_fourier_harmonic_analysis(
...    da=ds,
...    time_dim='time',
...    period_bounds=(8.0, None),
...    filter_type='lowpass',
...    sampling_interval=1.0,
...    apply_window=True
... )