tanat.sequence.type.interval package#

Submodules#

tanat.sequence.type.interval.entity module#

Interval entity implementation.

Bases: Entity

Entity representing one interval row (start/end timestamps).

Unlike StateEntity, intervals are not required to be contiguous: gaps between intervals are allowed, and two intervals may overlap in time.

tanat.sequence.type.interval.pool module#

Interval sequence pool implementation.

class tanat.sequence.type.interval.pool.IntervalSequencePool(store: str | Path | SequenceStore, *, id_column: str = 'id', start_column: str = 'start', end_column: str = 'end', entity_features: list[str] | None = None, static_features: list[str] | None = None, cast_recipe: SequenceCastRecipe | dict | None = None)[source]#

Bases: SequencePool

Pool of interval sequences.

Unlike state sequences, intervals are not required to be contiguous: gaps between intervals are allowed, and two intervals may overlap in time.

SETTINGS_CLASS[source]#: alias of IntervalSequenceSettings

Create an interval sequence pool backed by store.

Parameters:

store – Store path, name, or SequenceStore instance.
id_column – User-facing name for the sequence ID column.
start_column – User-facing name for the interval start column.
end_column – User-facing name for the interval end column.
entity_features – Subset of entity feature names to expose. None → all available from the store.
static_features – Static feature names to expose. None → all available. [] → none.
cast_recipe – Optional cast recipe (or dict) applied at read time. Normalised via SequenceCastRecipe.coerce() and probed eagerly.

Raises:

TypeError – If cast_recipe is not a SequenceCastRecipe, dict, or None.

as_event(anchor: Literal['start', 'end', 'middle'], *, time_column: str = 'time', destination: str | Path | None = None, overwrite: bool = False) → EventSequencePool[source]#

Convert this interval pool to an event pool by anchoring to one timestamp.

Parameters:

anchor – "start", "end", or "middle" - selects which timestamp (or their midpoint) becomes the event timestamp.
time_column – User-facing name for the event timestamp. Defaults to "time".
destination – None → ephemeral result; path → new persistent store.
overwrite – Replace destination if it already exists.

Returns:

A new EventSequencePool.

as_interval() → IntervalSequencePool[source]#

Return this pool unchanged - source and target types are identical.

A warning is emitted to signal the no-op conversion.

Returns:: self (no copy, no I/O).

as_state() → NoReturn[source]#

Not supported: interval → state conversion is ambiguous.

Intervals may overlap or contain gaps; neither property can be resolved into contiguous non-overlapping states without domain-specific merge / fill logic. Apply a manual Polars transformation instead.

Raises:: NotImplementedError – Always.

classmethod builder(*, sort_anchor: Literal['start', 'end', 'middle'] = 'start') → IntervalSequenceStoreBuilder[source]#

Return a fluent builder for constructing an interval sequence store.

Parameters:: sort_anchor – Intra-sequence sort column - "start" (default), "end" for right-censored datasets, or "middle" to sort by the interval midpoint (T_START + T_END) / 2.

tanat.sequence.type.interval.sequence module#

Interval sequence implementation.

class tanat.sequence.type.interval.sequence.IntervalSequence(id_value, store: str | Path | SequenceStore, *, id_column: str = 'id', start_column: str = 'start', end_column: str = 'end', entity_features: list[str] | None = None, static_features: list[str] | None = None)[source]#

Bases: Sequence

A single interval sequence.

Unlike state sequences, intervals are not required to be contiguous: gaps between intervals are allowed, and two intervals may overlap in time.

SETTINGS_CLASS[source]#: alias of IntervalSequenceSettings

__init__(id_value, store: str | Path | SequenceStore, *, id_column: str = 'id', start_column: str = 'start', end_column: str = 'end', entity_features: list[str] | None = None, static_features: list[str] | None = None) → None[source]#

Create an interval sequence for id_value.

Parameters:

id_value – Sequence identifier.
store – Store path, name, or SequenceStore instance.
id_column – User-facing name for the sequence ID column.
start_column – User-facing name for the interval start column.
end_column – User-facing name for the interval end column.
entity_features – Subset of entity feature names to expose. None → all available from the store.
static_features – Static feature names to expose. None → all available. [] → none.

tanat.sequence.type.interval.settings module#

Interval sequence settings.

class tanat.sequence.type.interval.settings.IntervalSequenceSettings(*, id_column: str, entity_features: list[str], static_features: list[str] = <factory>, start_column: str, end_column: str)[source]#

Bases: SequenceSettings

Settings for interval sequences (start + end timestamp columns).

Unlike state sequences, intervals are not required to be contiguous: gaps between intervals are allowed, and two intervals may overlap in time.

__init__(*args: Any, **kwargs: Any) → None[source]#

end_column: str[source]#

get_time_columns() → list[str][source]#: Returns time index columns for Interval sequences [start, end].

id_column: str[source]#

model_dump(*, mode='python', **dump_kwargs)[source]#: Dump settings to a dict via Pydantic serialization.

start_column: str[source]#

Module contents#

Interval sequence subtypes.

Bases: Entity

Entity representing one interval row (start/end timestamps).

Unlike StateEntity, intervals are not required to be contiguous: gaps between intervals are allowed, and two intervals may overlap in time.

class tanat.sequence.type.interval.IntervalSequence(id_value, store: str | Path | SequenceStore, *, id_column: str = 'id', start_column: str = 'start', end_column: str = 'end', entity_features: list[str] | None = None, static_features: list[str] | None = None)[source]#

Bases: Sequence

A single interval sequence.

Unlike state sequences, intervals are not required to be contiguous: gaps between intervals are allowed, and two intervals may overlap in time.

SETTINGS_CLASS[source]#: alias of IntervalSequenceSettings

Create an interval sequence for id_value.

Parameters:

id_value – Sequence identifier.
store – Store path, name, or SequenceStore instance.
id_column – User-facing name for the sequence ID column.
start_column – User-facing name for the interval start column.
end_column – User-facing name for the interval end column.
entity_features – Subset of entity feature names to expose. None → all available from the store.
static_features – Static feature names to expose. None → all available. [] → none.

class tanat.sequence.type.interval.IntervalSequencePool(store: str | Path | SequenceStore, *, id_column: str = 'id', start_column: str = 'start', end_column: str = 'end', entity_features: list[str] | None = None, static_features: list[str] | None = None, cast_recipe: SequenceCastRecipe | dict | None = None)[source]#

Bases: SequencePool

Pool of interval sequences.

Unlike state sequences, intervals are not required to be contiguous: gaps between intervals are allowed, and two intervals may overlap in time.

SETTINGS_CLASS[source]#: alias of IntervalSequenceSettings

Create an interval sequence pool backed by store.

Parameters:

store – Store path, name, or SequenceStore instance.
id_column – User-facing name for the sequence ID column.
start_column – User-facing name for the interval start column.
end_column – User-facing name for the interval end column.
entity_features – Subset of entity feature names to expose. None → all available from the store.
static_features – Static feature names to expose. None → all available. [] → none.
cast_recipe – Optional cast recipe (or dict) applied at read time. Normalised via SequenceCastRecipe.coerce() and probed eagerly.

Raises:

TypeError – If cast_recipe is not a SequenceCastRecipe, dict, or None.

as_event(anchor: Literal['start', 'end', 'middle'], *, time_column: str = 'time', destination: str | Path | None = None, overwrite: bool = False) → EventSequencePool[source]#

Convert this interval pool to an event pool by anchoring to one timestamp.

Parameters:

anchor – "start", "end", or "middle" - selects which timestamp (or their midpoint) becomes the event timestamp.
time_column – User-facing name for the event timestamp. Defaults to "time".
destination – None → ephemeral result; path → new persistent store.
overwrite – Replace destination if it already exists.

Returns:

A new EventSequencePool.

as_interval() → IntervalSequencePool[source]#

Return this pool unchanged - source and target types are identical.

A warning is emitted to signal the no-op conversion.

Returns:: self (no copy, no I/O).

as_state() → NoReturn[source]#

Not supported: interval → state conversion is ambiguous.

Raises:: NotImplementedError – Always.

classmethod builder(*, sort_anchor: Literal['start', 'end', 'middle'] = 'start') → IntervalSequenceStoreBuilder[source]#

Return a fluent builder for constructing an interval sequence store.

Parameters:: sort_anchor – Intra-sequence sort column - "start" (default), "end" for right-censored datasets, or "middle" to sort by the interval midpoint (T_START + T_END) / 2.

class tanat.sequence.type.interval.IntervalSequenceSettings(*, id_column: str, entity_features: list[str], static_features: list[str] = <factory>, start_column: str, end_column: str)[source]#

Bases: SequenceSettings

Settings for interval sequences (start + end timestamp columns).

Unlike state sequences, intervals are not required to be contiguous: gaps between intervals are allowed, and two intervals may overlap in time.

__init__(*args: Any, **kwargs: Any) → None[source]#

end_column: str[source]#

get_time_columns() → list[str][source]#: Returns time index columns for Interval sequences [start, end].

id_column: str[source]#

model_dump(*, mode='python', **dump_kwargs)[source]#: Dump settings to a dict via Pydantic serialization.

start_column: str[source]#