frames

frames ¤

Input checks shared by every public function outside the detectors.

The detectors in :mod:ts_shape.events get their input checks from :class:~ts_shape.utils.base.Base. Transforms, features, signals, the event log and the context helpers use these functions, so a missing column, an untyped time column or a time bound in another timezone is handled the same way everywhere:

:func:require_columns -- a missing column raises :class:~ts_shape.errors.ColumnNotFoundError naming the function.
:func:as_datetime -- a time column as datetime64 (text parsed, pyarrow timestamps converted, an empty untyped column typed).
:func:same_time_axis -- two time columns with one unit and the same timezone handling, so they can be merged or compared.
:func:localize_like -- a time bound (data_end, start) in the timezone of the data.
:func:ffill_values -- forward-fill that keeps the dtype (no silent downcasting of object columns).
:func:to_ns -- times as int64 nanoseconds since the epoch (UTC instants for tz-aware values), for NumPy searches and sorts.
:func:signal_frame_input -- decorator: a computing classmethod works on a normalized copy of its input frame.

require_columns ¤

require_columns(
    dataframe: DataFrame,
    columns: Iterable[str | None],
    *,
    where: str | None
) -> None

Raise when dataframe lacks any of columns.

Parameters:

Name	Type	Description	Default
`dataframe`	`DataFrame`	Input frame.	required
`columns`	`Iterable[str \| None]`	Required column names; `None` entries are skipped.	required
`where`	`str \| None`	Name of the calling function, used as the message prefix; `None` leaves the prefix out.	required

Raises:

Type	Description
`ColumnNotFoundError`	Naming the missing columns and the available ones. Subclasses `ValueError`.

as_datetime ¤

as_datetime(series: Series, *, where: str) -> pd.Series

Return series as a NumPy datetime64 Series.

Text is parsed, a pyarrow timestamp becomes datetime64 with the same timezone, and an empty column of any dtype becomes datetime64[ns].

Parameters:

Name	Type	Description	Default
`series`	`Series`	Time values.	required
`where`	`str`	Name of the calling function, used in the message.	required

Returns:

Type	Description
`Series`	The values as `datetime64` (tz-aware when the input is).

Raises:

Type	Description
`ValueError`	When non-empty values cannot be read as times.

same_time_axis ¤

same_time_axis(
    left: Series, right: Series, *, where: str
) -> tuple[pd.Series, pd.Series]

Bring two time columns to one unit, so they can be merged.

Parameters:

Name	Type	Description	Default
`left`	`Series`	Time values of the first frame.	required
`right`	`Series`	Time values of the second frame.	required
`where`	`str`	Name of the calling function, used in the message.	required

Returns:

Type	Description
`Series`	Both Series as `datetime64[ns]`, in the timezone of `left` when
`Series`	both are tz-aware.

Raises:

Type	Description
`ValueError`	When one side is tz-aware and the other is naive.

localize_like ¤

localize_like(
    value: Any, reference: Series
) -> pd.Timestamp

Return value as a Timestamp in the timezone of reference.

A naive bound on tz-aware data is read as local time of the data; an aware bound on naive data is converted to UTC and made naive.

Parameters:

Name	Type	Description	Default
`value`	`Any`	A time bound (string, datetime, Timestamp).	required
`reference`	`Series`	The time column the bound is compared with.	required

Returns:

Type	Description
`Timestamp`	The bound, comparable with `reference`.

localize_in ¤

localize_in(value: Any, tz: Any) -> pd.Timestamp

Return value as a Timestamp in tz (naive when tz is None).

The rule of :func:localize_like, for a timezone instead of a column: a naive value is read as wall-clock time in tz (an ambiguous time is read as standard time, a nonexistent one is shifted forward); an aware value is converted. With tz=None an aware value is converted to UTC and made naive.

Parameters:

Name	Type	Description	Default
`value`	`Any`	A time (string, datetime, Timestamp).	required
`tz`	`Any`	Target timezone, or None for naive.	required

Returns:

Type	Description
`Timestamp`	The value as a Timestamp.

to_ns ¤

to_ns(values: Series | Index) -> npt.NDArray[np.int64]

Times as int64 nanoseconds since the epoch.

Works for naive and tz-aware values of any unit: an aware value gives the nanoseconds of its UTC instant, a naive value those of its wall-clock reading. NaT becomes the minimum int64 (numpy's NaT), which sorts first.

Parameters:

Name	Type	Description	Default
`values`	`Series \| Index`	Datetime Series or Index.	required

Returns:

Type	Description
`NDArray[int64]`	One int64 per value, in input order.

ffill_values ¤

ffill_values(series: Series) -> pd.Series

Forward-fill series and keep its dtype.

Series.ffill on an object column infers a narrower dtype for the result, which pandas 2.2 reports as deprecated silent downcasting. This takes every missing value from the last value before it instead and leaves the dtype alone; leading missing values stay missing.

Parameters:

Name	Type	Description	Default
`series`	`Series`	Values to fill.	required

Returns:

Type	Description
`Series`	The filled Series, same index, name and dtype.

signal_frame_input ¤

signal_frame_input(
    *,
    time_column: str = "time_column",
    default_time: str = "systime"
) -> Callable[[F], F]

Run a computing classmethod on a normalized copy of its frame.

The first positional argument after cls is copied and passed through :func:~ts_shape.utils.normalize.normalize_signal_frame, so nullable, pyarrow and text-number columns compute like NumPy columns. Use it for functions that compute on the values; functions that return input rows unchanged (filters) keep the caller's dtypes and do not use it.

Parameters:

Name	Type	Description	Default
`time_column`	`str`	Name of the keyword that holds the time column.	`'time_column'`
`default_time`	`str`	Time column when the keyword is not passed.	`'systime'`

Returns:

Type	Description
`Callable[[F], F]`	A decorator for a `(cls, dataframe, ...)` method.

window_offset ¤

window_offset(window: Any) -> Any

The pandas offset of window, with "D" as a calendar day.

pandas 3 reads "1D" as a calendar day (23 h or 25 h on a DST change); pandas 2 reads it as a fixed 24 h. Window ends are computed the pandas-3 way on both, so a daily window on a DST day has its real length.

Parameters:

Name	Type	Description	Default
`window`	`Any`	Offset string (`"1h"`, `"1D"`, `"MS"`) or offset.	required

Returns:

Type	Description
`Any`	A pandas offset; for a day frequency one that adds `n` calendar
`Any`	days. On pandas 3 that is `to_offset(window)` itself (pandas' own
`Any`	calendar `Day`, e.g. `<3 * Days>`); on pandas 2, where `Day`
`Any`	is a fixed 24 h `Tick`, it is `pd.DateOffset(days=n)`. Any other
`Any`	window gives `to_offset(window)` (e.g. `<24 * Hours>` for
`Any`	`"24h"`). A `Timedelta` window converts to a fixed offset on
`Any`	pandas 3 (`Timedelta("2D")` -> `<48 * Hours>`) but to a day
`Any`	offset on pandas 2.