Skip to content

Extremes

pyextremes.extremes.get_extremes

get_extremes(ts: Series, method: Literal['BM'], extremes_type: Literal['high', 'low'] = 'high', *, block_size: str = '365.2425D', errors: Literal['raise', 'ignore', 'coerce'] = 'raise', min_last_block: Optional[float] = None) -> Series
get_extremes(ts: Series, method: Literal['POT'], extremes_type: Literal['high', 'low'] = 'high', *, threshold: float, r: Union[Timedelta, Any] = '24h') -> Series
get_extremes(ts: Series, method: Literal['BM', 'POT'], extremes_type: Literal['high', 'low'] = 'high', **kwargs) -> Series

Get extreme events from time series.

Parameters:

Name Type Description Default
ts Series

Time series of the signal.

required
method str

Extreme value extraction method. Supported values: BM - Block Maxima POT - Peaks Over Threshold

required
extremes_type str

high (default) - get extreme high values low - get extreme low values

'high'
kwargs

if method is BM: block_size : str or pandas.Timedelta, optional Block size (default='365.2425D'). errors : str, optional raise (default) - raise an exception when encountering a block with no data ignore - ignore blocks with no data coerce - get extreme values for blocks with no data as mean of all other extreme events in the series with index being the middle point of corresponding interval min_last_block : float, optional Minimum data availability ratio (0 to 1) in the last block for it to be used to extract extreme value from. This is used to discard last block when it is too short. If None (default), last block is always used. if method is POT: threshold : float Threshold used to find exceedances. r : pandas.Timedelta or value convertible to timedelta, optional Duration of window used to decluster the exceedances. By default r='24h' (24 hours). See pandas.to_timedelta for more information.

{}

Returns:

Name Type Description
extremes Series

Time series of extreme events.

Source code in src/pyextremes/extremes/extremes.py
def get_extremes(
    ts: pd.Series,
    method: Literal["BM", "POT"],
    extremes_type: Literal["high", "low"] = "high",
    **kwargs,
) -> pd.Series:
    """
    Get extreme events from time series.

    Parameters
    ----------
    ts : pandas.Series
        Time series of the signal.
    method : str
        Extreme value extraction method.
        Supported values:
            BM - Block Maxima
            POT - Peaks Over Threshold
    extremes_type : str, optional
        high (default) - get extreme high values
        low - get extreme low values
    kwargs
        if method is BM:
            block_size : str or pandas.Timedelta, optional
                Block size (default='365.2425D').
            errors : str, optional
                raise (default) - raise an exception
                    when encountering a block with no data
                ignore - ignore blocks with no data
                coerce - get extreme values for blocks with no data
                    as mean of all other extreme events in the series
                    with index being the middle point of corresponding interval
            min_last_block : float, optional
                Minimum data availability ratio (0 to 1) in the last block
                for it to be used to extract extreme value from.
                This is used to discard last block when it is too short.
                If None (default), last block is always used.
        if method is POT:
            threshold : float
                Threshold used to find exceedances.
            r : pandas.Timedelta or value convertible to timedelta, optional
                Duration of window used to decluster the exceedances.
                By default r='24h' (24 hours).
                See pandas.to_timedelta for more information.

    Returns
    -------
    extremes : pandas.Series
        Time series of extreme events.

    """
    if method == "BM":
        return get_extremes_block_maxima(
            ts=ts,
            extremes_type=extremes_type,
            **kwargs,
        )
    if method == "POT":
        return get_extremes_peaks_over_threshold(
            ts=ts,
            extremes_type=extremes_type,
            **kwargs,
        )
    raise ValueError(
        f"invalid value in '{method}' for the 'method' argument, "
        f"available methods: 'BM', 'POT'"
    )

pyextremes.extremes.get_return_periods

get_return_periods(ts: Series, extremes: Series, extremes_method: Literal['BM', 'POT'], extremes_type: Literal['high', 'low'], block_size: Optional[Union[str, Timedelta]] = None, return_period_size: Union[str, Timedelta] = '365.2425D', plotting_position: Literal['ecdf', 'hazen', 'weibull', 'tukey', 'blom', 'median', 'cunnane', 'gringorten', 'beard'] = 'weibull') -> DataFrame

Calculate return periods for given extreme values using given plotting position.

Return periods are multiples of return_period_size. Plotting positions were taken from https://matplotlib.org/mpl-probscale/tutorial/closer_look_at_plot_pos.html

Parameters:

Name Type Description Default
ts Series

Time series of the signal.

required
extremes Series

Time series of extreme events.

required
extremes_method str

Extreme value extraction method. Supported values: BM - Block Maxima POT - Peaks Over Threshold

required
extremes_type str

high - provided extreme values are extreme high values low - provided extreme values are extreme low values

required
block_size str or Timedelta

Block size in the 'BM' extremes_method (default=None). If None, then is calculated as median distance between extreme events.

None
return_period_size str or Timedelta

Size of return periods (default='365.2425D'). If set to '30D', then a return period of 12 would be roughly equivalent to a 1 year return period (360 days).

'365.2425D'
plotting_position str

Plotting position name (default='weibull'), not case-sensitive. Supported plotting positions: ecdf, hazen, weibull, tukey, blom, median, cunnane, gringorten, beard

'weibull'

Returns:

Name Type Description
extreme_events DataFrame

A DataFrame with extreme values, exceedance probabilities, and return periods as multiples of return_period_size.

Source code in src/pyextremes/extremes/return_periods.py
def get_return_periods(
    ts: pd.Series,
    extremes: pd.Series,
    extremes_method: Literal["BM", "POT"],
    extremes_type: Literal["high", "low"],
    block_size: Optional[Union[str, pd.Timedelta]] = None,
    return_period_size: Union[str, pd.Timedelta] = "365.2425D",
    plotting_position: Literal[
        "ecdf",
        "hazen",
        "weibull",
        "tukey",
        "blom",
        "median",
        "cunnane",
        "gringorten",
        "beard",
    ] = "weibull",
) -> pd.DataFrame:
    """
    Calculate return periods for given extreme values using given plotting position.

    Return periods are multiples of `return_period_size`.
    Plotting positions were taken from
    https://matplotlib.org/mpl-probscale/tutorial/closer_look_at_plot_pos.html

    Parameters
    ----------
    ts : pandas.Series
        Time series of the signal.
    extremes : pandas.Series
        Time series of extreme events.
    extremes_method : str
        Extreme value extraction method.
        Supported values:
            BM - Block Maxima
            POT - Peaks Over Threshold
    extremes_type : str
        high - provided extreme values are extreme high values
        low - provided extreme values are extreme low values
    block_size : str or pandas.Timedelta, optional
        Block size in the 'BM' `extremes_method` (default=None).
        If None, then is calculated as median distance between extreme events.
    return_period_size : str or pandas.Timedelta, optional
        Size of return periods (default='365.2425D').
        If set to '30D', then a return period of 12
        would be roughly equivalent to a 1 year return period (360 days).
    plotting_position : str, optional
        Plotting position name (default='weibull'), not case-sensitive.
        Supported plotting positions:
            ecdf, hazen, weibull, tukey, blom, median, cunnane, gringorten, beard

    Returns
    -------
    extreme_events : pandas.DataFrame
        A DataFrame with extreme values, exceedance probabilities,
        and return periods as multiples of `return_period_size`.

    """
    if extremes_method == "BM":
        # Parse 'block_size' argument
        if block_size is None:
            # Calculate 'block_size' as median distance between extremes
            block_size = pd.to_timedelta(np.quantile(np.diff(extremes.index), 0.5))
        elif not isinstance(block_size, pd.Timedelta):
            if isinstance(block_size, str):
                block_size = pd.to_timedelta(block_size)
            else:
                raise TypeError(
                    f"invalid type in {type(block_size)} for the 'block_size' argument"
                )
    elif block_size is not None:
        raise ValueError(
            f"'block_size' value is used only if 'extremes_method' is 'BM', "
            f"provided 'extremes_method' is {extremes_method}"
        )

    # Parse the 'return_period_size' argument
    if not isinstance(return_period_size, pd.Timedelta):
        if isinstance(return_period_size, str):
            return_period_size = pd.to_timedelta(return_period_size)
        else:
            raise TypeError(
                f"invalid type in {type(return_period_size)} "
                f"for the 'return_period_size' argument"
            )

    # Calculate rate of extreme events as number of events per one return period
    if extremes_method == "BM":
        extremes_rate = return_period_size / block_size
    elif extremes_method == "POT":
        n_periods = (ts.index.max() - ts.index.min()) / return_period_size
        extremes_rate = len(extremes) / n_periods
    else:
        raise ValueError(
            f"invalid value in '{extremes_method}' for the 'extremes_method' argument"
        )

    # Rank extreme values from most extreme (1) to least extreme (len(extremes))
    if extremes_type == "high":
        ranks = (
            len(extremes) + 1 - scipy.stats.rankdata(extremes.values, method="average")
        )
    elif extremes_type == "low":
        ranks = scipy.stats.rankdata(extremes.values, method="average")
    else:
        raise ValueError(
            f"invalid value in '{extremes_type}' for the 'extremes_type' argument"
        )

    # Get plotting position parameters
    try:
        alpha, beta = plotting_positions[plotting_position.lower()]
    except KeyError as _error:
        raise ValueError(
            f"invalid value in '{plotting_position}' "
            f"for the 'plotting_position' argument"
        ) from _error

    # Calculate exceedance probabilities
    exceedance_probability = (ranks - alpha) / (len(extremes) + 1 - alpha - beta)

    # Calculate return periods
    return_periods = 1 / exceedance_probability / extremes_rate

    # Copy `extremes` to make the returned DataFrame independent from the original
    extremes = extremes.copy(deep=True)

    return pd.DataFrame(
        data={
            extremes.name: extremes.values,
            "exceedance probability": exceedance_probability,
            "return period": return_periods,
        },
        index=extremes.index,
        dtype=np.float64,
    )

pyextremes.extremes.ExtremesTransformer

Utility class used to transform extreme values between high and low extremes type.

Provides methods to transform extreme value series to and from format compatible with pyextremes models. Extreme values are transformed in a way to have more extreme events (lower probability of exceedance) oriented to the right (in the increasing order). For extremes_type being 'high' no transform is performed. For extremes_type being 'low' values are flipped around the maximum value.

Source code in src/pyextremes/extremes/transformation.py
class ExtremesTransformer:
    """
    Utility class used to transform extreme values between high and low extremes type.

    Provides methods to transform extreme value series to and from format
    compatible with pyextremes models. Extreme values are transformed in a way
    to have more extreme events (lower probability of exceedance) oriented to the right
    (in the increasing order).
    For extremes_type being 'high' no transform is performed.
    For extremes_type being 'low' values are flipped around the maximum value.

    """

    __slots__ = [
        "__pivot_point",
        "__transformed_extremes",
        "extremes",
        "extremes_type",
    ]

    def __init__(self, extremes: pd.Series, extremes_type: str) -> None:
        """
        Initialize the extreme value transformer.

        Parameters
        ----------
        extremes : pandas.Series
            Time series of extreme events.
        extremes_type : str
            high - provided extreme values are extreme high values
            low - provided extreme values are extreme low values

        """
        self.extremes: pd.Series = extremes
        self.extremes_type: str = extremes_type

        self.__pivot_point: typing.Optional[float] = (
            None if self.extremes_type == "high" else self.extremes.max()
        )
        self.__transformed_extremes: pd.Series = self.transform(value=extremes)

    @property
    def pivot_point(self) -> typing.Optional[float]:
        return self.__pivot_point

    @property
    def transformed_extremes(self) -> pd.Series:
        return self.__transformed_extremes

    def transform(
        self, value: typing.Union[float, pd.Series, None]
    ) -> typing.Union[float, pd.Series, None]:
        """
        Transform extreme values in either direction.

        Parameters
        ----------
        value : float or pandas.Series
            Value or series of values to be transformed.

        Returns
        -------
        transformed_value : None, float, or pandas.Series
            Transformed value or series.
            If value is None, returns None (a.k.a. null-transform).

        """
        if value is None or self.pivot_point is None:
            return value
        return 2 * self.pivot_point - value

__init__

__init__(extremes: Series, extremes_type: str) -> None

Initialize the extreme value transformer.

Parameters:

Name Type Description Default
extremes Series

Time series of extreme events.

required
extremes_type str

high - provided extreme values are extreme high values low - provided extreme values are extreme low values

required
Source code in src/pyextremes/extremes/transformation.py
def __init__(self, extremes: pd.Series, extremes_type: str) -> None:
    """
    Initialize the extreme value transformer.

    Parameters
    ----------
    extremes : pandas.Series
        Time series of extreme events.
    extremes_type : str
        high - provided extreme values are extreme high values
        low - provided extreme values are extreme low values

    """
    self.extremes: pd.Series = extremes
    self.extremes_type: str = extremes_type

    self.__pivot_point: typing.Optional[float] = (
        None if self.extremes_type == "high" else self.extremes.max()
    )
    self.__transformed_extremes: pd.Series = self.transform(value=extremes)

transform

transform(value: Union[float, Series, None]) -> Union[float, Series, None]

Transform extreme values in either direction.

Parameters:

Name Type Description Default
value float or Series

Value or series of values to be transformed.

required

Returns:

Name Type Description
transformed_value None, float, or pandas.Series

Transformed value or series. If value is None, returns None (a.k.a. null-transform).

Source code in src/pyextremes/extremes/transformation.py
def transform(
    self, value: typing.Union[float, pd.Series, None]
) -> typing.Union[float, pd.Series, None]:
    """
    Transform extreme values in either direction.

    Parameters
    ----------
    value : float or pandas.Series
        Value or series of values to be transformed.

    Returns
    -------
    transformed_value : None, float, or pandas.Series
        Transformed value or series.
        If value is None, returns None (a.k.a. null-transform).

    """
    if value is None or self.pivot_point is None:
        return value
    return 2 * self.pivot_point - value