tanat.sequence.type.state package#

Submodules#

tanat.sequence.type.state.entity module#

State entity implementation.

class tanat.sequence.type.state.entity.StateEntity(id_value, store: str | Path | SequenceStore, features: list[str] | None = None, *, rank: int, store_index: int, cast_recipe: SequenceCastRecipe | dict | None = None, virtual_id: str | None = None, parent_metadata: SequenceMetadata | None = None)[source]#

Bases: Entity

Entity representing one state row (start/end).

States are contiguous and non-overlapping: the end of one state is always the start of the next, with no gaps in between.

tanat.sequence.type.state.pool module#

State sequence pool implementation.

class tanat.sequence.type.state.pool.StateSequencePool(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 state sequences.

States are contiguous and non-overlapping: the end of one state is always the start of the next, with no gaps in between.

SETTINGS_CLASS[source]#

alias of StateSequenceSettings

__init__(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) → None[source]#

Create a state 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 state start column.

  • end_column – User-facing name for the state 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 state 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(*, start_column: str | None = None, end_column: str | None = None, destination: str | Path | None = None, overwrite: bool = False) → IntervalSequencePool[source]#

Convert this state pool to an interval pool.

States and intervals share the same (_t_start, _t_end) physical layout - no temporal recomputation needed.

Parameters:

  • start_column – User-facing name for the start column. None inherits this pool’s current setting.

  • end_column – User-facing name for the end column. None inherits this pool’s current setting.

  • destination – None → ephemeral result; path → new persistent store.

  • overwrite – Replace destination if it already exists.

Returns:

A new IntervalSequencePool.

as_state() → StateSequencePool[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).

classmethod builder(*, end_value: datetime | int | float | None = None, validate_continuity: bool = True) → StateSequenceStoreBuilder[source]#

Return a fluent builder for constructing a state sequence store.

Parameters:

  • end_value – Sentinel for T_END of the last state in each sequence when end_column is not provided at source registration time. None → leaves the last T_END as null.

  • validate_continuity – When end_column is provided, verify that states are truly contiguous (T_END[i] == T_START[i+1]) before writing. Defaults to True. Set to False on large datasets where the cost of a full collect() is unacceptable.

filter_entities(criterion, *, inplace=False, verbose=True)[source]#

Not supported on state pools.

States are contiguous and non-overlapping by definition: removing individual rows would leave temporal gaps and break the invariant T_END[i] == T_START[i+1].

tanat.sequence.type.state.sequence module#

State sequence implementation.

class tanat.sequence.type.state.sequence.StateSequence(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 state sequence.

States are contiguous and non-overlapping: the end of one state is always the start of the next, with no gaps in between.

SETTINGS_CLASS[source]#

alias of StateSequenceSettings

__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 a state 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 state start column.

  • end_column – User-facing name for the state 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.

filter_entities(criterion, *, inplace=False, verbose=True)[source]#

Not supported on state sequences.

States are contiguous and non-overlapping by definition: removing individual rows would leave temporal gaps and break the invariant T_END[i] == T_START[i+1].

tanat.sequence.type.state.settings module#

State sequence settings.

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

Bases: SequenceSettings

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

States are contiguous and non-overlapping: the end of one state is always the start of the next, with no gaps in between.

__init__(*args: Any, **kwargs: Any) → None[source]#
end_column: str[source]#
get_time_columns() → list[str][source]#

Returns time index columns for State sequences [start, end].

model_dump(*, mode='python', **dump_kwargs)[source]#

Dump settings to a dict via Pydantic serialization.

start_column: str[source]#

Module contents#

State sequence subtypes.

class tanat.sequence.type.state.StateEntity(id_value, store: str | Path | SequenceStore, features: list[str] | None = None, *, rank: int, store_index: int, cast_recipe: SequenceCastRecipe | dict | None = None, virtual_id: str | None = None, parent_metadata: SequenceMetadata | None = None)[source]#

Bases: Entity

Entity representing one state row (start/end).

States are contiguous and non-overlapping: the end of one state is always the start of the next, with no gaps in between.

class tanat.sequence.type.state.StateSequence(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 state sequence.

States are contiguous and non-overlapping: the end of one state is always the start of the next, with no gaps in between.

SETTINGS_CLASS[source]#

alias of StateSequenceSettings

__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 a state 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 state start column.

  • end_column – User-facing name for the state 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.

filter_entities(criterion, *, inplace=False, verbose=True)[source]#

Not supported on state sequences.

States are contiguous and non-overlapping by definition: removing individual rows would leave temporal gaps and break the invariant T_END[i] == T_START[i+1].

class tanat.sequence.type.state.StateSequencePool(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 state sequences.

States are contiguous and non-overlapping: the end of one state is always the start of the next, with no gaps in between.

SETTINGS_CLASS[source]#

alias of StateSequenceSettings

__init__(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) → None[source]#

Create a state 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 state start column.

  • end_column – User-facing name for the state 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 state 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(*, start_column: str | None = None, end_column: str | None = None, destination: str | Path | None = None, overwrite: bool = False) → IntervalSequencePool[source]#

Convert this state pool to an interval pool.

States and intervals share the same (_t_start, _t_end) physical layout - no temporal recomputation needed.

Parameters:

  • start_column – User-facing name for the start column. None inherits this pool’s current setting.

  • end_column – User-facing name for the end column. None inherits this pool’s current setting.

  • destination – None → ephemeral result; path → new persistent store.

  • overwrite – Replace destination if it already exists.

Returns:

A new IntervalSequencePool.

as_state() → StateSequencePool[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).

classmethod builder(*, end_value: datetime | int | float | None = None, validate_continuity: bool = True) → StateSequenceStoreBuilder[source]#

Return a fluent builder for constructing a state sequence store.

Parameters:

  • end_value – Sentinel for T_END of the last state in each sequence when end_column is not provided at source registration time. None → leaves the last T_END as null.

  • validate_continuity – When end_column is provided, verify that states are truly contiguous (T_END[i] == T_START[i+1]) before writing. Defaults to True. Set to False on large datasets where the cost of a full collect() is unacceptable.

filter_entities(criterion, *, inplace=False, verbose=True)[source]#

Not supported on state pools.

States are contiguous and non-overlapping by definition: removing individual rows would leave temporal gaps and break the invariant T_END[i] == T_START[i+1].

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

Bases: SequenceSettings

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

States are contiguous and non-overlapping: the end of one state is always the start of the next, with no gaps in between.

__init__(*args: Any, **kwargs: Any) → None[source]#
end_column: str[source]#
get_time_columns() → list[str][source]#

Returns time index columns for State sequences [start, end].

model_dump(*, mode='python', **dump_kwargs)[source]#

Dump settings to a dict via Pydantic serialization.

start_column: str[source]#