`icclim._core.frequency`#

Contain the Frequency class and the FrequencyRegistry class.

Frequency wraps the concept of pandas frequency in order to resample time series. slice_mode parameter of icclim.index is always converted to a Frequency.

Module Contents#

icclim._core.frequency.get_seasonal_time_updater(start_month: int, end_month: int, start_day: int = 1, end_day: int | None = None) → Callable[[xarray.core.dataarray.DataArray], tuple[xarray.core.dataarray.DataArray, xarray.core.dataarray.DataArray]]#

Seasonal time updater and time bounds creator method generator.

Returns a callable of DataArray which will rewrite the time dimension to the season composed of the given months. The data must have been computed on this season beforehand. It also create the corresponding time_bounds.

Parameters:

start_month (int) – The season starting month, it must be between 1 and 12.
end_month (int) – The season ending month, it must be between 1 and 12.
start_day (int) – The season starting day, it must be between 1 and 31.
end_day (int) – The season ending day, it must be between 1 and 31.

Returns:

function – A function that will update the time dimension of a DataArray to the season composed of the given months and create the corresponding time_bounds.

Return type:

Callable[[DataArray], tuple[DataArray, DataArray]]

icclim._core.frequency.get_time_bounds_updater(freq: str) → Callable[[xarray.core.dataarray.DataArray], tuple[xarray.core.dataarray.DataArray, xarray.core.dataarray.DataArray]]#

Return a function that adds time bounds to a given DataArray.

Parameters:: freq (str) – The frequency at which the DataArray should be resampled.
Returns:: A function that takes a DataArray as input and returns a tuple containing the modified DataArray and the time bounds as a separate DataArray.
Return type:: Callable[[DataArray], tuple[DataArray, DataArray]]

Notes

The returned function assumes that the input DataArray has already been resampled to the specified frequency.

The time axis values in the modified DataArray will be set to the middle of the calculated time bounds.

class icclim._core.frequency.Frequency#

Time sampling frequency.

This acts as a wrapper around the pandas frequency string. icclim.index will always convert the slice_mode parameter to a Frequency.

Parameters:

pandas_freq (str) – The frequency string used by pandas to resample the time series.
accepted_values (list[str]) – The list of aliases for the frequency.
adjective (str) – The adjective form of the frequency. Used when templating the output’s metadata.
post_processing (Callable[[DataArray], tuple[DataArray, DataArray]] | None) – The function to apply for post-processing the resampled data.
units (str) – The units of the frequency.
indexer (Indexer | None) – The indexer to use for grouping the data.
long_name (str) – The long name of the frequency.
group_by_key (str | None) – The key to use for grouping the data.
delta (np.timedelta64) – The time delta for the frequency.

Returns:

The frequency object.

Return type:

Frequency

Notes

This class represents a time sampling frequency.

Examples

>>> freq = Frequency(
...     pandas_freq="D",
...     accepted_values=["daily", "day", "days", "d"],
...     adjective="daily",
...     indexer=None,
...     post_processing=get_time_bounds_updater("D"),
...     units="days",
...     long_name="day",
...     group_by_key="time.dayofyear",
...     delta=np.timedelta64(1, "D"),
... )

build_frequency_kwargs() → dict[str, Any]#: Build kwargs with possible keys in {“freq”, “month”, “date_bounds”}.

class icclim._core.frequency.FrequencyRegistry#

Registry class for Frequency objects.

NO_RESAMPLE#: Does not resample

HOUR#: Resample to hourly values

DAY#: Resample to daily values

MONTH#: Resample to monthly values

YEAR#: Resample to yearly values.

AMJJAS#: Resample to summer half-year, from April to September included.

ONDJFM#: Resample to winter half-year, from October to March included.

DJF#: Resample to winter season, from December to February included.

MAM#: Resample to spring season, from March to May included.

JJA#: Resample to summer season, from June to Agust included.

SON#: Resample to fall season, from September to November included.

classmethod lookup(query: icclim._core.model.icclim_types.FrequencyLike | Frequency) → Frequency#

Look up a Frequency object based on the query.

Parameters:: query (FrequencyLike or Frequency) – The query to look up the Frequency object. Typically a string.
Returns:: The Frequency object that matches the query.
Return type:: Frequency
Raises:: InvalidIcclimArgumentError – If the query is not a valid frequency.

Notes

The query can be a Frequency object, a string representing a frequency, or a list/tuple representing a frequency.

If the query is a string, it will be converted to a Frequency object first by looking in the FrequencyRegistry then by assuming it’s a pandas frequency and building a Frequency object from it.

If the query is a list/tuple, it needs a keyword as its first element and a list of months or a list of two date strings as its second element. The keyword can be either “month” or “season”. In “month” case, the second element must be a list of months and the Frequency will filter the data by these months. In “season” case, the second element must be a list of months or a list of two date and the Frequency will resample the data to the season composed of these months.

static get_item_aliases(item: Frequency) → list[str]#

Get the aliases of a Frequency object.

Parameters:: item (Frequency) – The Frequency object.
Returns:: The aliases of the Frequency object.
Return type:: list[str]

icclim._core.frequency._get_delta(pandas_freq: str) → numpy.timedelta64#

Build timedelta from a “pandas frequency” string.

A “pandas frequency” string may look like [“2YS-DEC”, “3W-TUE”, “M”, … ] The anchor, such as “DEC” in “YS-DEC”, does not modify the delta.

Parameters:

pandas_freq (str) –
query. (The frequency) –

Returns:

The timedelta corresponding to this frequency.
For example, “2YS-DEC” would return a 2 years delta.

icclim._core.frequency#

Module Contents#

`icclim._core.frequency`#