Skip to content

Time inputs and utilities

Check the dtypes first. These aliases describe accepted time arrays, group labels, and horizon values. Use the utilities to validate timestamps or convert a duration. Concrete splitters bind prediction and evaluation times at construction.

Input type aliases

purgedcv.TimesLike module-attribute 

TimesLike: TypeAlias = ArrayLike1D

Time inputs for prediction_times and evaluation_times.

Accepts the same containers as ArrayLike1D. After coercion, inputs must have a datetime64 or timedelta64 dtype, not strings or numeric timestamps. Examples include pandas DatetimeIndex or Series, NumPy temporal arrays, Python lists of datetime/timedelta objects, and polars temporal Series. Timezone-aware pandas inputs are normalized to UTC.

validate_times checks lengths, temporal dtype families, missing values, and label ordering. Splitters also require non-decreasing prediction times.

purgedcv.ArrayLike1D module-attribute 

ArrayLike1D: TypeAlias = NDArrayAny | Sequence[Any] | SupportsToNumpy

A 1-D array-like of arbitrary elements: a NumPy array, a Python sequence, or a sized object exposing .to_numpy() (including pandas and polars containers).

This is the container contract shared by time inputs and group labels; only the element semantics differ. Public functions coerce inputs to 1-D NumPy arrays and validate the shape at runtime.

Unlike a bare Any, this alias rejects unrelated types (an int, a mapping) statically. It is a concrete union rather than a string, so typing.get_type_hints can resolve annotations on public functions.

purgedcv.HorizonLike module-attribute 

HorizonLike = str | pd.Timedelta | timedelta | np.timedelta64

A purge or embargo duration accepted as text or a timedelta scalar.

Use a fixed-duration string such as "2D", "6h", or "30min", a pandas Timedelta, a Python datetime.timedelta, or a NumPy timedelta64. parse_horizon rejects negative or missing durations and ambiguous calendar offsets such as months or years. None is not part of this alias; individual parameters may accept it with their own default semantics.

Time and horizon utilities

purgedcv.parse_horizon 

parse_horizon(value: HorizonLike) -> pd.Timedelta

Coerce a horizon-like input to a non-negative pd.Timedelta.

Accepts pandas offset strings ("2D", "6h", "30min"), pd.Timedelta, datetime.timedelta, and numpy.timedelta64. Rejects missing/NaT values, negative durations, and calendar-ambiguous offsets such as "M" (month) or "Y" (year), which do not represent a fixed duration in seconds.

Parameters:

Name Type Description Default
value HorizonLike

The horizon to parse.

 required

Returns:

Type Description
Timedelta

A non-negative pd.Timedelta.

Raises:

Type Description
ValueError

if the input is missing/NaT, negative, or a calendar-ambiguous string.
TypeError

if the input is not one of the supported types.

Examples:

>>> from purgedcv import parse_horizon
>>> parse_horizon("2D")
Timedelta('2 days 00:00:00')
>>> parse_horizon("6h")
Timedelta('0 days 06:00:00')

purgedcv.horizons_overlap 

horizons_overlap(a_start: Timestamp, a_end: Timestamp, b_start: Timestamp, b_end: Timestamp) -> bool

Return True iff half-open intervals [a_start, a_end) and [b_start, b_end) overlap.

Touching intervals (a_end == b_start) do NOT overlap. The function is symmetric in its arguments.

Examples:

>>> import pandas as pd
>>> from purgedcv import horizons_overlap
>>> horizons_overlap(
...     pd.Timestamp("2024-01-01"), pd.Timestamp("2024-01-03"),
...     pd.Timestamp("2024-01-02"), pd.Timestamp("2024-01-04"),
... )
True
>>> horizons_overlap(
...     pd.Timestamp("2024-01-01"), pd.Timestamp("2024-01-02"),
...     pd.Timestamp("2024-01-02"), pd.Timestamp("2024-01-03"),
... )
False

purgedcv.validate_times 

validate_times(prediction_times: TimesLike, evaluation_times: TimesLike, *, require_monotonic: bool = True) -> None

Validate that prediction_times and evaluation_times are well-formed.

Raises:

Type Description
ValueError

on length mismatch, non-temporal dtype, NaT values, evaluation_times < prediction_times at any row, or (when require_monotonic) non-monotonic prediction times. The error message names the offending row index when applicable.

Examples:

>>> import pandas as pd
>>> from purgedcv import validate_times
>>> pred = pd.Series(pd.date_range("2024-01-01", periods=5, freq="D"))
>>> evalu = pred + pd.Timedelta(days=1)
>>> validate_times(pred, evalu)