tanat.visualization.sequence package#

Subpackages#

Submodules#

tanat.visualization.sequence.core module#

SequenceVisualizer: fluent entry point for sequence visualizations.

class tanat.visualization.sequence.core.SequenceVisualizer[source]#

Bases: object

Factory for sequence visualization builders.

All class methods return a configured builder ready for chaining.

Example:

SequenceVisualizer.barplot(show_as="rate") \
    .title("Relative frequencies") \
    .draw(pool) \
    .show()
classmethod barplot(*, show_as: ShowAs = 'count', sort: SortOrder = 'alphabetic', orientation: Orientation = 'vertical', display_unit: DisplayUnit | None = None, na_time_index: NaTimeIndex = 'drop', na_label: NaLabel = 'drop', allow_large: bool = False) → BarplotVizBuilder[source]#

Create a barplot builder.

Parameters:

  • show_as – What each bar represents: “count”, “rate”, or “duration”.

  • sort – Bar sort order: “alphabetic”, “ascending”, or “descending”.

  • orientation – “vertical” (default) or “horizontal”.

  • display_unit – Output unit for DURATION mode (“days”, “hours”, “minutes”, “seconds”). None keeps raw ms / raw timestep. Only meaningful when show_as=”duration” and the pool is datetime-based.

  • na_time_index – Strategy for null time index columns (only relevant for show_as="duration"): "drop" (default) removes with warning, "raise" raises immediately.

  • na_label – Strategy for null entity feature labels: "drop" (default) removes with warning, "raise" raises immediately, "category" renders nulls as "N/A".

  • allow_large – Bypass the MAX_CATEGORY safety guard.

Returns:

A configured BarplotVizBuilder.

classmethod distribution(*, mode: DistributionMode = 'percentage', bin_size: str | int | float = '1d', stacked: bool = True, time_mode: TimeMode = 'absolute', display_unit: DisplayUnit | None = None, na_time_index: NaTimeIndex = 'drop', na_label: NaLabel = 'drop', allow_large: bool = False) → DistributionVizBuilder[source]#

Create a distribution builder.

Only compatible with state sequence types. Passing any other pool type raises UnsupportedSequenceTypeError.

The chart shows how many (or what fraction of) sequences occupy each state at each point in time, using occupancy-based binning: a segment contributes to every bin it overlaps.

Parameters:

  • mode –

    What each area represents:

    • "count": raw number of sequences per state per bin.

    • "proportion": fraction of sequences per state (0-1 per bin).

    • "percentage": same as proportion expressed as 0-100 (default).

  • bin_size –

    Width of each time bin.

    • Datetime pools: a Polars duration string such as "1d", "12h", "1w", "1mo".

    • Timestep pools: a numeric step value (int or float).

  • stacked – True (default) renders a stacked area chart. False renders overlapping transparent fills.

  • time_mode – "absolute" (default) uses 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.

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

  • na_time_index – Strategy for null time index columns: "drop" (default) removes with warning, "raise" raises immediately.

  • na_label – Strategy for null entity feature labels: "drop" (default) removes with warning, "raise" raises immediately, "category" renders nulls as "N/A".

  • allow_large – Bypass the MAX_CATEGORY safety guard.

Returns:

A configured DistributionVizBuilder.

classmethod spanplot(*, group_by: GroupBy = 'category', kind: SpanKind = 'box', display_unit: DisplayUnit | None = None, sort: SortOrder = 'ascending', orientation: Orientation = 'vertical', na_time_index: NaTimeIndex = 'drop', na_label: NaLabel = 'drop', allow_large: bool = False) → SpanplotVizBuilder[source]#

Create a spanplot (duration distribution) builder.

Only compatible with state and interval sequence types. Duration is undefined for event sequences; passing one raises UnsupportedSequenceTypeError.

Parameters:

  • group_by –

    Grouping dimension:

    • "category": one column per unique label value (default).

    • "id": one column per sequence ID.

  • kind –

    Chart variety:

    • "box": standard box-and-whisker (default).

    • "violin": kernel-density violin.

    • "strip": individual points with horizontal jitter.

  • display_unit – Output unit for datetime-based pools: "days", "hours", "minutes", or "seconds". Required when the pool is datetime-based; must be None for numeric timestep pools.

  • sort –

    Sort order for x-axis groups:

    • "ascending": ascending median duration (default).

    • "descending": descending median duration.

    • "alphabetic": alphabetical order of labels or IDs.

  • orientation –

    Chart orientation:

    • "vertical": groups on the x-axis, durations on y (default).

    • "horizontal": groups on the y-axis, durations on x.

  • na_time_index – Strategy for null time index columns: "drop" (default) removes with warning, "raise" raises immediately.

  • na_label – Strategy for null entity feature labels: "drop" (default) removes with warning, "raise" raises immediately, "category" renders nulls as "N/A".

  • allow_large – Bypass the MAX_CATEGORY / MAX_IDS safety guards.

Returns:

A configured SpanplotVizBuilder.

classmethod timeline(*, group_by: GroupBy = 'id', time_mode: TimeMode = 'absolute', display_unit: DisplayUnit | None = None, na_time_index: NaTimeIndex = 'drop', na_label: NaLabel = 'drop', allow_large: bool = False) → TimelineVizBuilder[source]#

Create a timeline builder.

Parameters:

  • group_by –

    Row organisation:

    • "id": one row per sequence ID (default).

    • "category": one row per unique label value.

  • time_mode – "absolute" (real timestamps as-is) or "relative" (all sequences aligned to their per-ID T0 reference date).

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

  • na_time_index – Strategy for null time index columns: "drop" (default) removes with warning, "raise" raises immediately.

  • na_label – Strategy for null entity feature labels: "drop" (default) removes with warning, "raise" raises immediately, "category" renders nulls as "N/A".

  • allow_large – Bypass the MAX_MARKERS and MAX_IDS safety guards.

Returns:

A configured TimelineVizBuilder.

Module contents#

Sequence visualization module.

class tanat.visualization.sequence.SequenceVisualizer[source]#

Bases: object

Factory for sequence visualization builders.

All class methods return a configured builder ready for chaining.

Example:

SequenceVisualizer.barplot(show_as="rate") \
    .title("Relative frequencies") \
    .draw(pool) \
    .show()
classmethod barplot(*, show_as: ShowAs = 'count', sort: SortOrder = 'alphabetic', orientation: Orientation = 'vertical', display_unit: DisplayUnit | None = None, na_time_index: NaTimeIndex = 'drop', na_label: NaLabel = 'drop', allow_large: bool = False) → BarplotVizBuilder[source]#

Create a barplot builder.

Parameters:

  • show_as – What each bar represents: “count”, “rate”, or “duration”.

  • sort – Bar sort order: “alphabetic”, “ascending”, or “descending”.

  • orientation – “vertical” (default) or “horizontal”.

  • display_unit – Output unit for DURATION mode (“days”, “hours”, “minutes”, “seconds”). None keeps raw ms / raw timestep. Only meaningful when show_as=”duration” and the pool is datetime-based.

  • na_time_index – Strategy for null time index columns (only relevant for show_as="duration"): "drop" (default) removes with warning, "raise" raises immediately.

  • na_label – Strategy for null entity feature labels: "drop" (default) removes with warning, "raise" raises immediately, "category" renders nulls as "N/A".

  • allow_large – Bypass the MAX_CATEGORY safety guard.

Returns:

A configured BarplotVizBuilder.

classmethod distribution(*, mode: DistributionMode = 'percentage', bin_size: str | int | float = '1d', stacked: bool = True, time_mode: TimeMode = 'absolute', display_unit: DisplayUnit | None = None, na_time_index: NaTimeIndex = 'drop', na_label: NaLabel = 'drop', allow_large: bool = False) → DistributionVizBuilder[source]#

Create a distribution builder.

Only compatible with state sequence types. Passing any other pool type raises UnsupportedSequenceTypeError.

The chart shows how many (or what fraction of) sequences occupy each state at each point in time, using occupancy-based binning: a segment contributes to every bin it overlaps.

Parameters:

  • mode –

    What each area represents:

    • "count": raw number of sequences per state per bin.

    • "proportion": fraction of sequences per state (0-1 per bin).

    • "percentage": same as proportion expressed as 0-100 (default).

  • bin_size –

    Width of each time bin.

    • Datetime pools: a Polars duration string such as "1d", "12h", "1w", "1mo".

    • Timestep pools: a numeric step value (int or float).

  • stacked – True (default) renders a stacked area chart. False renders overlapping transparent fills.

  • time_mode – "absolute" (default) uses 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.

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

  • na_time_index – Strategy for null time index columns: "drop" (default) removes with warning, "raise" raises immediately.

  • na_label – Strategy for null entity feature labels: "drop" (default) removes with warning, "raise" raises immediately, "category" renders nulls as "N/A".

  • allow_large – Bypass the MAX_CATEGORY safety guard.

Returns:

A configured DistributionVizBuilder.

classmethod spanplot(*, group_by: GroupBy = 'category', kind: SpanKind = 'box', display_unit: DisplayUnit | None = None, sort: SortOrder = 'ascending', orientation: Orientation = 'vertical', na_time_index: NaTimeIndex = 'drop', na_label: NaLabel = 'drop', allow_large: bool = False) → SpanplotVizBuilder[source]#

Create a spanplot (duration distribution) builder.

Only compatible with state and interval sequence types. Duration is undefined for event sequences; passing one raises UnsupportedSequenceTypeError.

Parameters:

  • group_by –

    Grouping dimension:

    • "category": one column per unique label value (default).

    • "id": one column per sequence ID.

  • kind –

    Chart variety:

    • "box": standard box-and-whisker (default).

    • "violin": kernel-density violin.

    • "strip": individual points with horizontal jitter.

  • display_unit – Output unit for datetime-based pools: "days", "hours", "minutes", or "seconds". Required when the pool is datetime-based; must be None for numeric timestep pools.

  • sort –

    Sort order for x-axis groups:

    • "ascending": ascending median duration (default).

    • "descending": descending median duration.

    • "alphabetic": alphabetical order of labels or IDs.

  • orientation –

    Chart orientation:

    • "vertical": groups on the x-axis, durations on y (default).

    • "horizontal": groups on the y-axis, durations on x.

  • na_time_index – Strategy for null time index columns: "drop" (default) removes with warning, "raise" raises immediately.

  • na_label – Strategy for null entity feature labels: "drop" (default) removes with warning, "raise" raises immediately, "category" renders nulls as "N/A".

  • allow_large – Bypass the MAX_CATEGORY / MAX_IDS safety guards.

Returns:

A configured SpanplotVizBuilder.

classmethod timeline(*, group_by: GroupBy = 'id', time_mode: TimeMode = 'absolute', display_unit: DisplayUnit | None = None, na_time_index: NaTimeIndex = 'drop', na_label: NaLabel = 'drop', allow_large: bool = False) → TimelineVizBuilder[source]#

Create a timeline builder.

Parameters:

  • group_by –

    Row organisation:

    • "id": one row per sequence ID (default).

    • "category": one row per unique label value.

  • time_mode – "absolute" (real timestamps as-is) or "relative" (all sequences aligned to their per-ID T0 reference date).

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

  • na_time_index – Strategy for null time index columns: "drop" (default) removes with warning, "raise" raises immediately.

  • na_label – Strategy for null entity feature labels: "drop" (default) removes with warning, "raise" raises immediately, "category" renders nulls as "N/A".

  • allow_large – Bypass the MAX_MARKERS and MAX_IDS safety guards.

Returns:

A configured TimelineVizBuilder.