tanat.visualization.sequence.type.spanplot package#

Submodules#

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

SpanplotVizBuilder: duration distribution visualizer for a SequencePool or Sequence.

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

Bases: BaseSequenceVizBuilder

Builds duration distribution charts from a SequencePool or an individual Sequence.

Each point in the resulting chart represents one segment (interval or state occurrence). Distributions can be grouped by category label or by sequence ID.

Only compatible with state and interval sequence types: duration is undefined for events.

Typical usage via SequenceVisualizer:

SequenceVisualizer.spanplot(kind="violin", display_unit="hours") \
    .title("ICU stay durations by status") \
    .colors("Set2") \
    .draw(pool, entity_feature="status") \
    .show()
MAX_IDS: int = 30[source]#
SETTINGS_CLASS[source]#

alias of SpanplotSettings

__init__(settings: Any | None = None, *, allow_large: bool = False) → None[source]#
marker(*, alpha: float | None = None, edge_color: str | None = None, point_size: float | None = None, line_width: float | None = None) → SpanplotVizBuilder[source]#

Configure marker visual properties. Chainable.

Parameters:

  • alpha – Opacity (0–1).

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

  • point_size – Scatter point diameter in points (strip kind only).

  • line_width – Box or violin outline thickness.

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

Configure the x (horizontal) axis. Chainable.

Role depends on orientation:

  • "vertical" (default): group labels on x, durations on y.

  • "horizontal": durations on x, group labels on y. Use limit_min/limit_max to clip outliers.

Parameters:

  • show – Hide the axis entirely when False.

  • label – Axis label text.

  • rotation – Tick label rotation in degrees.

  • limit_min – Minimum x value (meaningful in horizontal orientation).

  • limit_max – Maximum x value (meaningful in horizontal orientation).

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

Configure the y (vertical) axis. Chainable.

Role depends on orientation:

  • "vertical" (default): durations on y, group labels on x. Use limit_min/limit_max to clip outliers.

  • "horizontal": group labels on y, durations on x.

Parameters:

  • show – Hide the axis entirely when False.

  • label – Axis label text (e.g. "Duration (hours)")..

  • rotation – Tick label rotation in degrees.

  • limit_min – Minimum y value (meaningful in vertical orientation).

  • limit_max – Maximum y value (meaningful in vertical orientation).

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

Pure Polars data-preparation functions for the spanplot builder.

tanat.visualization.sequence.type.spanplot.data.extract_durations(lf: LazyFrame, display_unit: Literal['days', 'hours', 'minutes', 'seconds'] | None, *, extra_cols: list[str] | None = None) → LazyFrame[source]#

Compute per-row __DURATION__ from __END__ - __START__.

  • display_unit=None: raw numeric difference (timestep sequences).

  • display_unit=<unit>: datetime difference converted to the requested unit via total milliseconds.

The caller is responsible for ensuring consistency between the time column dtype and display_unit (see IncompatibleDisplayUnitError).

Parameters:

  • lf – LazyFrame with __ID__, __LABEL__, __START__, __END__.

  • display_unit – Target duration unit, or None for raw numeric values.

  • extra_cols – Additional columns to keep in the output (e.g. ["__FACET__"] when faceting is active). Columns that are absent from lf are silently ignored.

Returns:

LazyFrame with columns [__ID__, __LABEL__, __DURATION__] plus any extra_cols that were present.

Raises:

ValueError – If display_unit is not in MS_PER_DISPLAY_UNIT.

tanat.visualization.sequence.type.spanplot.data.sort_ids(df: DataFrame, sort: str) → list[str][source]#

Return __ID__ values (as strings) in the requested sort order.

Parameters:

  • df – Collected DataFrame with __ID__ and __DURATION__ columns.

  • sort – One of "ascending" (ascending median), "descending" (descending median), or "alphabetic" (string sort).

Returns:

Ordered list of unique ID strings.

tanat.visualization.sequence.type.spanplot.data.sort_labels(df: DataFrame, sort: str) → list[str][source]#

Return __LABEL__ values in the requested sort order.

Parameters:

  • df – Collected DataFrame with __LABEL__ and __DURATION__ columns.

  • sort – One of "ascending" (ascending median), "descending" (descending median), or "alphabetic" (string sort).

Returns:

Ordered list of unique label strings.

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

Spanplot settings.

class tanat.visualization.sequence.type.spanplot.settings.SpanAesthetics(*, group_by: GroupBy = 'category', kind: SpanKind = 'box', display_unit: DisplayUnit | None = None, sort: SortOrder = 'ascending', orientation: Orientation = 'vertical')[source]#

Bases: object

Visual aesthetics for the spanplot builder.

group_by[source]#

Dimension to group distributions along. "category": one distribution per label value (default). "id": one distribution per sequence ID.

Type:

Literal[‘category’, ‘id’]

kind[source]#

Chart style. "box" (default), "violin", or "strip".

Type:

Literal[‘box’, ‘violin’, ‘strip’]

display_unit[source]#

Duration output unit for datetime-based pools. None keeps raw numeric values (correct for timestep sequences).

Type:

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

sort[source]#

Sort order for groups. "ascending": ascending median duration (default). "descending": descending median duration. "alphabetic": alphabetical order of label / ID strings.

Type:

Literal[‘alphabetic’, ‘ascending’, ‘descending’]

orientation[source]#

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

Type:

Literal[‘vertical’, ‘horizontal’]

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

Dump settings to a dict via Pydantic serialization.

orientation: Literal['vertical', 'horizontal'] = 'vertical'[source]#
sort: Literal['alphabetic', 'ascending', 'descending'] = 'ascending'[source]#
class tanat.visualization.sequence.type.spanplot.settings.SpanMarkerSettings(*, alpha: float = 0.75, edge_color: str | None = None, point_size: float = 4.0, line_width: float = 1.5)[source]#

Bases: object

Marker visual properties for the spanplot builder.

alpha[source]#

Global opacity (0–1).

Type:

float

edge_color[source]#

Marker/box border color. None means no explicit border.

Type:

str | None

point_size[source]#

Scatter point diameter in points (strip kind only).

Type:

float

line_width[source]#

Box/violin outline thickness.

Type:

float

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

Dump settings to a dict via Pydantic serialization.

point_size: float = 4.0[source]#
class tanat.visualization.sequence.type.spanplot.settings.SpanplotSettings(*, 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: SpanAesthetics = <factory>, null_handling: NullHandling = <factory>, marker: SpanMarkerSettings = <factory>)[source]#

Bases: BaseVizSettings

Full settings for the spanplot builder.

__init__(*args: Any, **kwargs: Any) → None[source]#
aesthetics: SpanAesthetics[source]#
legend: LegendSettings[source]#
marker: SpanMarkerSettings[source]#
model_dump(*, mode='python', **dump_kwargs)[source]#

Dump settings to a dict via Pydantic serialization.

null_handling: NullHandling[source]#

Module contents#

Spanplot package.

class tanat.visualization.sequence.type.spanplot.SpanAesthetics(*, group_by: GroupBy = 'category', kind: SpanKind = 'box', display_unit: DisplayUnit | None = None, sort: SortOrder = 'ascending', orientation: Orientation = 'vertical')[source]#

Bases: object

Visual aesthetics for the spanplot builder.

group_by[source]#

Dimension to group distributions along. "category": one distribution per label value (default). "id": one distribution per sequence ID.

Type:

Literal[‘category’, ‘id’]

kind[source]#

Chart style. "box" (default), "violin", or "strip".

Type:

Literal[‘box’, ‘violin’, ‘strip’]

display_unit[source]#

Duration output unit for datetime-based pools. None keeps raw numeric values (correct for timestep sequences).

Type:

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

sort[source]#

Sort order for groups. "ascending": ascending median duration (default). "descending": descending median duration. "alphabetic": alphabetical order of label / ID strings.

Type:

Literal[‘alphabetic’, ‘ascending’, ‘descending’]

orientation[source]#

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

Type:

Literal[‘vertical’, ‘horizontal’]

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

Dump settings to a dict via Pydantic serialization.

orientation: Literal['vertical', 'horizontal'] = 'vertical'[source]#
sort: Literal['alphabetic', 'ascending', 'descending'] = 'ascending'[source]#
class tanat.visualization.sequence.type.spanplot.SpanMarkerSettings(*, alpha: float = 0.75, edge_color: str | None = None, point_size: float = 4.0, line_width: float = 1.5)[source]#

Bases: object

Marker visual properties for the spanplot builder.

alpha[source]#

Global opacity (0–1).

Type:

float

edge_color[source]#

Marker/box border color. None means no explicit border.

Type:

str | None

point_size[source]#

Scatter point diameter in points (strip kind only).

Type:

float

line_width[source]#

Box/violin outline thickness.

Type:

float

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

Dump settings to a dict via Pydantic serialization.

point_size: float = 4.0[source]#
class tanat.visualization.sequence.type.spanplot.SpanplotSettings(*, 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: SpanAesthetics = <factory>, null_handling: NullHandling = <factory>, marker: SpanMarkerSettings = <factory>)[source]#

Bases: BaseVizSettings

Full settings for the spanplot builder.

__init__(*args: Any, **kwargs: Any) → None[source]#
aesthetics: SpanAesthetics[source]#
legend: LegendSettings[source]#
marker: SpanMarkerSettings[source]#
model_dump(*, mode='python', **dump_kwargs)[source]#

Dump settings to a dict via Pydantic serialization.

null_handling: NullHandling[source]#
class tanat.visualization.sequence.type.spanplot.SpanplotVizBuilder(settings: Any | None = None, *, allow_large: bool = False)[source]#

Bases: BaseSequenceVizBuilder

Builds duration distribution charts from a SequencePool or an individual Sequence.

Each point in the resulting chart represents one segment (interval or state occurrence). Distributions can be grouped by category label or by sequence ID.

Only compatible with state and interval sequence types: duration is undefined for events.

Typical usage via SequenceVisualizer:

SequenceVisualizer.spanplot(kind="violin", display_unit="hours") \
    .title("ICU stay durations by status") \
    .colors("Set2") \
    .draw(pool, entity_feature="status") \
    .show()
MAX_IDS: int = 30[source]#
SETTINGS_CLASS[source]#

alias of SpanplotSettings

__init__(settings: Any | None = None, *, allow_large: bool = False) → None[source]#
marker(*, alpha: float | None = None, edge_color: str | None = None, point_size: float | None = None, line_width: float | None = None) → SpanplotVizBuilder[source]#

Configure marker visual properties. Chainable.

Parameters:

  • alpha – Opacity (0–1).

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

  • point_size – Scatter point diameter in points (strip kind only).

  • line_width – Box or violin outline thickness.

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

Configure the x (horizontal) axis. Chainable.

Role depends on orientation:

  • "vertical" (default): group labels on x, durations on y.

  • "horizontal": durations on x, group labels on y. Use limit_min/limit_max to clip outliers.

Parameters:

  • show – Hide the axis entirely when False.

  • label – Axis label text.

  • rotation – Tick label rotation in degrees.

  • limit_min – Minimum x value (meaningful in horizontal orientation).

  • limit_max – Maximum x value (meaningful in horizontal orientation).

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

Configure the y (vertical) axis. Chainable.

Role depends on orientation:

  • "vertical" (default): durations on y, group labels on x. Use limit_min/limit_max to clip outliers.

  • "horizontal": group labels on y, durations on x.

Parameters:

  • show – Hide the axis entirely when False.

  • label – Axis label text (e.g. "Duration (hours)")..

  • rotation – Tick label rotation in degrees.

  • limit_min – Minimum y value (meaningful in vertical orientation).

  • limit_max – Maximum y value (meaningful in vertical orientation).

On this page