tanat.visualization.sequence.type.timeline package#

Submodules#

tanat.visualization.sequence.type.timeline.builder module#

TimelineVizBuilder: timeline visualizer for a SequencePool or individual Sequence.

class tanat.visualization.sequence.type.timeline.builder.TimelineVizBuilder(settings: Any | None = None, *, allow_large: bool = False)[source]#

Bases: BaseSequenceVizBuilder

Builds timeline charts from a SequencePool or an individual Sequence.

Typical usage via SequenceVisualizer:

SequenceVisualizer.timeline() \
    .title("Status over time") \
    .draw(pool, entity_feature="status") \
    .show()
MAX_IDS: int = 30[source]#
MAX_MARKERS: int = 1000[source]#
SETTINGS_CLASS[source]#

alias of TimelineSettings

__init__(settings: Any | None = None, *, allow_large: bool = False) → None[source]#
marker(*, alpha: float | None = None, edge_color: str | None = None, size: float | None = None, bar_height: float | None = None, shape: str | None = None) → TimelineVizBuilder[source]#

Configure marker visual properties. Chainable.

Parameters:

  • alpha – Opacity (0–1).

  • edge_color – Marker border color. None means no border.

  • size – Scatter point size (event sequence only).

  • bar_height – Height fraction of each row slot, 0–1 (interval/state pools only).

  • shape – Matplotlib marker string, e.g. "o", "s", "^" (event sequence only).

x_axis(*, show: bool | None = None, label: str | None = None, rotation: int | None = None, limit_min: float | None = None, limit_max: float | None = None, autofmt_xdate: bool | None = None) → TimelineVizBuilder[source]#

Configure the time (x) axis. Chainable.

Parameters:

  • show – Hide the axis entirely when False.

  • label – Axis label text.

  • rotation – Tick label rotation in degrees.

  • limit_min – Left bound (zooms into a time window).

  • limit_max – Right bound (zooms into a time window).

  • autofmt_xdate – Auto-rotate date tick labels (useful for dense datetime scales).

y_axis(*, show: bool | None = None, label: str | None = None) → TimelineVizBuilder[source]#

Configure the sequence / category (y) axis. Chainable.

rotation and limit_min/limit_max are intentionally not exposed: y-positions are integer ranks managed internally, so rotating string labels or constraining numeric limits is not meaningful here.

Parameters:

  • show – Hide the axis entirely when False (useful when y-axis labels are too dense to read).

  • label – Axis label text.

tanat.visualization.sequence.type.timeline.data module#

Pure Polars data-preparation functions for the timeline builder.

tanat.visualization.sequence.type.timeline.data.assign_y_positions(lf: LazyFrame, mode: Literal['category', 'id']) → LazyFrame[source]#

Add __Y_POSITION__ (0-based integer) based on mode.

  • "id" -> dense rank on __ID__.

  • "category" -> dense rank on __LABEL__.

Parameters:

  • lf – Input LazyFrame (must contain __ID__ and __LABEL__).

  • mode – Grouping mode.

Returns:

LazyFrame with an additional __Y_POSITION__ integer column.

tanat.visualization.sequence.type.timeline.data.build_y_tick_map(df: DataFrame, mode: Literal['category', 'id']) → dict[int, str][source]#

Return {y_position: tick_label} for y-axis formatting.

  • "id" -> {pos: str(id_value)}.

  • "category" -> {pos: label_string}.

Parameters:

  • df – Collected DataFrame (must contain __Y_POSITION__, __ID__, and __LABEL__).

  • mode – Grouping mode used for y-position assignment.

Returns:

Mapping from integer y position to its tick label string.

tanat.visualization.sequence.type.timeline.data.rename_time_index_columns(lf: LazyFrame, time_cols: list[str]) → LazyFrame[source]#

Rename pool time index columns to internal standard names.

  • 1 column -> renamed to __TIME__ (event pool).

  • 2 columns -> first renamed to __TIME__, second to __END__ (interval/state).

Parameters:

  • lf – Input LazyFrame.

  • time_cols – List of time index column names (1 or 2 elements).

Returns:

LazyFrame with time index columns renamed to __TIME__ (and __END__).

tanat.visualization.sequence.type.timeline.settings module#

Timeline settings.

class tanat.visualization.sequence.type.timeline.settings.TimelineAesthetics(*, group_by: GroupBy = 'id', time_mode: TimeMode = 'absolute', display_unit: DisplayUnit | None = None)[source]#

Bases: object

Visual aesthetics for the timeline.

group_by[source]#

Row organisation. "id" (default) for one row per sequence ID, or "category" for one row per unique label value.

Type:

Literal[‘category’, ‘id’]

time_mode[source]#

"absolute" (default) displays real timestamps on the x-axis. "relative" aligns all sequences to their per-ID T0 reference date; the x-axis shows a numeric offset from T0. Requires set_t0() to have been called (or uses the lazy default of position=0).

Type:

Literal[‘absolute’, ‘relative’]

display_unit[source]#

Target unit for the x-axis when time_mode="relative" and the pool is datetime-based. One of "days" (default), "hours", "minutes", or "seconds". Ignored for timestep pools (a UserWarning is emitted if explicitly set).

Type:

Literal[‘days’, ‘hours’, ‘minutes’, ‘seconds’] | None

__init__(*args: Any, **kwargs: Any) → None[source]#
display_unit: Literal['days', 'hours', 'minutes', 'seconds'] | None = None[source]#
group_by: Literal['category', 'id'] = 'id'[source]#
model_dump(*, mode='python', **dump_kwargs)[source]#

Dump settings to a dict via Pydantic serialization.

time_mode: Literal['absolute', 'relative'] = 'absolute'[source]#
class tanat.visualization.sequence.type.timeline.settings.TimelineMarkerSettings(*, size: float = 4.0, bar_height: float = 0.6, alpha: float = 0.75, edge_color: str | None = None, shape: str = 'o')[source]#

Bases: object

Marker visual properties for the timeline.

size[source]#

Scatter point size (event pools).

Type:

float

bar_height[source]#

Height fraction of each row slot (interval/state pools).

Type:

float

alpha[source]#

Opacity of markers.

Type:

float

edge_color[source]#

Marker edge color. None means no edge.

Type:

str | None

shape[source]#

Any matplotlib marker string (e.g. “o”, “s”, “^”). Validated by matplotlib at render time.

Type:

str

__init__(*args: Any, **kwargs: Any) → None[source]#
alpha: float = 0.75[source]#
bar_height: float = 0.6[source]#
edge_color: str | None = None[source]#
model_dump(*, mode='python', **dump_kwargs)[source]#

Dump settings to a dict via Pydantic serialization.

shape: str = 'o'[source]#
size: float = 4.0[source]#
class tanat.visualization.sequence.type.timeline.settings.TimelineSettings(*, title: TitleSettings = <factory>, colors: str | dict | list | None = None, figsize: tuple[float, float]=(10.0, 5.0), grid: GridSettings = <factory>, x_axis: XAxisSettings = <factory>, y_axis: YAxisSettings = <factory>, legend: LegendSettings = <factory>, facet: FacetSettings = <factory>, aesthetics: TimelineAesthetics = <factory>, null_handling: NullHandling = <factory>, marker: TimelineMarkerSettings = <factory>)[source]#

Bases: BaseVizSettings

Full settings for the timeline builder.

__init__(*args: Any, **kwargs: Any) → None[source]#
aesthetics: TimelineAesthetics[source]#
marker: TimelineMarkerSettings[source]#
model_dump(*, mode='python', **dump_kwargs)[source]#

Dump settings to a dict via Pydantic serialization.

null_handling: NullHandling[source]#
x_axis: XAxisSettings[source]#
y_axis: YAxisSettings[source]#

Module contents#

Timeline package.

class tanat.visualization.sequence.type.timeline.TimelineAesthetics(*, group_by: GroupBy = 'id', time_mode: TimeMode = 'absolute', display_unit: DisplayUnit | None = None)[source]#

Bases: object

Visual aesthetics for the timeline.

group_by[source]#

Row organisation. "id" (default) for one row per sequence ID, or "category" for one row per unique label value.

Type:

Literal[‘category’, ‘id’]

time_mode[source]#

"absolute" (default) displays real timestamps on the x-axis. "relative" aligns all sequences to their per-ID T0 reference date; the x-axis shows a numeric offset from T0. Requires set_t0() to have been called (or uses the lazy default of position=0).

Type:

Literal[‘absolute’, ‘relative’]

display_unit[source]#

Target unit for the x-axis when time_mode="relative" and the pool is datetime-based. One of "days" (default), "hours", "minutes", or "seconds". Ignored for timestep pools (a UserWarning is emitted if explicitly set).

Type:

Literal[‘days’, ‘hours’, ‘minutes’, ‘seconds’] | None

__init__(*args: Any, **kwargs: Any) → None[source]#
display_unit: Literal['days', 'hours', 'minutes', 'seconds'] | None = None[source]#
group_by: Literal['category', 'id'] = 'id'[source]#
model_dump(*, mode='python', **dump_kwargs)[source]#

Dump settings to a dict via Pydantic serialization.

time_mode: Literal['absolute', 'relative'] = 'absolute'[source]#
class tanat.visualization.sequence.type.timeline.TimelineMarkerSettings(*, size: float = 4.0, bar_height: float = 0.6, alpha: float = 0.75, edge_color: str | None = None, shape: str = 'o')[source]#

Bases: object

Marker visual properties for the timeline.

size[source]#

Scatter point size (event pools).

Type:

float

bar_height[source]#

Height fraction of each row slot (interval/state pools).

Type:

float

alpha[source]#

Opacity of markers.

Type:

float

edge_color[source]#

Marker edge color. None means no edge.

Type:

str | None

shape[source]#

Any matplotlib marker string (e.g. “o”, “s”, “^”). Validated by matplotlib at render time.

Type:

str

__init__(*args: Any, **kwargs: Any) → None[source]#
alpha: float = 0.75[source]#
bar_height: float = 0.6[source]#
edge_color: str | None = None[source]#
model_dump(*, mode='python', **dump_kwargs)[source]#

Dump settings to a dict via Pydantic serialization.

shape: str = 'o'[source]#
size: float = 4.0[source]#
class tanat.visualization.sequence.type.timeline.TimelineSettings(*, title: TitleSettings = <factory>, colors: str | dict | list | None = None, figsize: tuple[float, float]=(10.0, 5.0), grid: GridSettings = <factory>, x_axis: XAxisSettings = <factory>, y_axis: YAxisSettings = <factory>, legend: LegendSettings = <factory>, facet: FacetSettings = <factory>, aesthetics: TimelineAesthetics = <factory>, null_handling: NullHandling = <factory>, marker: TimelineMarkerSettings = <factory>)[source]#

Bases: BaseVizSettings

Full settings for the timeline builder.

__init__(*args: Any, **kwargs: Any) → None[source]#
aesthetics: TimelineAesthetics[source]#
marker: TimelineMarkerSettings[source]#
model_dump(*, mode='python', **dump_kwargs)[source]#

Dump settings to a dict via Pydantic serialization.

null_handling: NullHandling[source]#
x_axis: XAxisSettings[source]#
y_axis: YAxisSettings[source]#
class tanat.visualization.sequence.type.timeline.TimelineVizBuilder(settings: Any | None = None, *, allow_large: bool = False)[source]#

Bases: BaseSequenceVizBuilder

Builds timeline charts from a SequencePool or an individual Sequence.

Typical usage via SequenceVisualizer:

SequenceVisualizer.timeline() \
    .title("Status over time") \
    .draw(pool, entity_feature="status") \
    .show()
MAX_IDS: int = 30[source]#
MAX_MARKERS: int = 1000[source]#
SETTINGS_CLASS[source]#

alias of TimelineSettings

__init__(settings: Any | None = None, *, allow_large: bool = False) → None[source]#
marker(*, alpha: float | None = None, edge_color: str | None = None, size: float | None = None, bar_height: float | None = None, shape: str | None = None) → TimelineVizBuilder[source]#

Configure marker visual properties. Chainable.

Parameters:

  • alpha – Opacity (0–1).

  • edge_color – Marker border color. None means no border.

  • size – Scatter point size (event sequence only).

  • bar_height – Height fraction of each row slot, 0–1 (interval/state pools only).

  • shape – Matplotlib marker string, e.g. "o", "s", "^" (event sequence only).

x_axis(*, show: bool | None = None, label: str | None = None, rotation: int | None = None, limit_min: float | None = None, limit_max: float | None = None, autofmt_xdate: bool | None = None) → TimelineVizBuilder[source]#

Configure the time (x) axis. Chainable.

Parameters:

  • show – Hide the axis entirely when False.

  • label – Axis label text.

  • rotation – Tick label rotation in degrees.

  • limit_min – Left bound (zooms into a time window).

  • limit_max – Right bound (zooms into a time window).

  • autofmt_xdate – Auto-rotate date tick labels (useful for dense datetime scales).

y_axis(*, show: bool | None = None, label: str | None = None) → TimelineVizBuilder[source]#

Configure the sequence / category (y) axis. Chainable.

rotation and limit_min/limit_max are intentionally not exposed: y-positions are integer ranks managed internally, so rotating string labels or constraining numeric limits is not meaningful here.

Parameters:

  • show – Hide the axis entirely when False (useful when y-axis labels are too dense to read).

  • label – Axis label text.

On this page