lair.background.thoning_filter#

lair.background.thoning_filter(data, **kwargs)[source]#

Create a Thoning filter object from a time series of data.

Parameters:
  • data (pd.Series) – Time series of data to be smoothed. Must have a datetime index.

  • **kwargs – Additional keyword arguments to pass to the ccgFilter class. Its times are in days of 1/365 of a decimal year (a calendar day, or 366/365 of one in a leap year): the cutoffs shortterm (default 80) and longterm (default 667), and sampleinterval, the step of the even grid that the filter interpolates the data onto. With the default, sampleinterval=0, the filter uses the mean of the steps between samples that are about a day or more. When there are none (data more often than daily with no gap of a day, or daily data within one leap year), lair passes the median step between samples instead (1/24 for hourly data). For data more often than daily with gaps of a day or more, the filter’s estimate is the mean length of those gaps. The filter interpolates onto its grid, it does not average, so a grid that coarse samples the data at about the same hour each time and a diurnal cycle shifts the curve. Pass the data’s own step there (sampleinterval=1/24 for hourly data).

Returns:

ccgFilter – Thoning filter object. Its methods (getSmoothValue, getTrendValue, getHarmonicValue, …) take decimal years (lair.clock.dt2decimalDate()).

Return type:

lair._ccg_filter.ccgFilter

See also

thoning

The smooth curve at given times, from this filter.

Examples

The trend of three years of made-up daily CO2 that grows 2.5 ppm a year, with a seasonal cycle and noise:

>>> import numpy as np
>>> import pandas as pd
>>> from lair.background import thoning_filter
>>> from lair.clock import dt2decimalDate
>>> rng = np.random.default_rng(0)
>>> days = pd.date_range("2020-01-01", "2022-12-31", freq="D")
>>> years = (days - days[0]).days / 365.25
>>> seasons = 3 * np.cos(2 * np.pi * years)
>>> noise = rng.normal(0, 0.5, days.size)
>>> co2 = pd.Series(410 + 2.5 * years + seasons + noise, index=days)
>>> filt = thoning_filter(co2)
>>> jan1 = [dt2decimalDate(pd.Timestamp(f"{y}-01-01")) for y in (2021, 2022)]
>>> filt.getTrendValue(np.array(jan1)).round(1)
array([412.5, 415. ])