tanat.visualization.sequence.type.barplot package#

Submodules#

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

BarplotVizBuilder: bar chart visualizer for a SequencePool or individual Sequence.

class tanat.visualization.sequence.type.barplot.builder.BarplotVizBuilder(settings: dict | BaseVizSettings | None = None, *, allow_large: bool = False)[source]#

Bases: BaseSequenceVizBuilder

Builds bar charts from a SequencePool or an individual Sequence.

Typical usage via SequenceVisualizer:

SequenceVisualizer.barplot(show_as="count") \
    .title("Event counts") \
    .draw(pool, entity_feature="status") \
    .show()
SETTINGS_CLASS[source]#

alias of BarplotSettings

marker(*, alpha: float | None = None, edge_color: str | None = None, bar_width: float | None = None) → BarplotVizBuilder[source]#

Configure bar visual properties. Chainable.

Parameters:

  • alpha – Opacity (0–1).

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

  • bar_width – Width fraction of available slot, 0–1 (default 0.8).

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

Configure the x (horizontal) axis. Chainable.

Role depends on orientation:

  • "vertical" (default): categories on x, values on y → limit_min/limit_max are not meaningful here.

  • "horizontal": values on x, categories on y → use limit_min/limit_max to constrain the value range.

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 only).

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

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

Configure the y (vertical) axis. Chainable.

Role depends on orientation:

  • "vertical" (default): values on y, categories on x → use limit_min/limit_max to constrain the value range (e.g. limit_max=1.0 for rates).

  • "horizontal": categories on y, values on x → limit_min/limit_max are not meaningful here.

Parameters:

  • show – Hide the axis entirely when False.

  • label – Axis label text.

  • rotation – Tick label rotation in degrees.

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

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

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

Pure Polars data-preparation functions for the barplot builder.

tanat.visualization.sequence.type.barplot.data.aggregate_count(lf: LazyFrame, label_col: str, *, facet_col: str | None = None) → LazyFrame[source]#

Count rows per category (and optionally per facet).

Returns a LazyFrame with columns [label_col, __VALUE__] or [facet_col, label_col, __VALUE__] when facet_col is set.

tanat.visualization.sequence.type.barplot.data.aggregate_duration(lf: LazyFrame, label_col: str, start_col: str, end_col: str, display_unit: Literal['days', 'hours', 'minutes', 'seconds'] | None = None, *, facet_col: str | None = None) → LazyFrame[source]#

Summed (end - start) duration per category (and optionally per facet).

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

  • display_unit=<unit>: datetime difference converted through milliseconds into the requested unit.

The caller is responsible for ensuring consistency between the temporal type and display_unit (see IncompatibleDisplayUnitError).

Raises:

ValueError – If display_unit is not in MS_PER_DISPLAY_UNIT.

tanat.visualization.sequence.type.barplot.data.aggregate_rate(lf: LazyFrame, label_col: str, *, facet_col: str | None = None) → LazyFrame[source]#

Relative frequency per category (and optionally per facet).

Rates sum to 1 within each facet (or globally when facet_col is None). Single-pass: one group_by + window division.

Returns a LazyFrame with columns [label_col, __VALUE__] or [facet_col, label_col, __VALUE__].

tanat.visualization.sequence.type.barplot.data.apply_sort(lf: LazyFrame, order: Literal['alphabetic', 'ascending', 'descending']) → LazyFrame[source]#

Sort lf according to order.

Keeps the sort inside the lazy plan so Polars can optimise it (e.g. push-down on columnar sources).

  • "alphabetic" -> ascending __LABEL__ string sort.

  • "ascending" -> ascending __VALUE__.

  • "descending" -> descending __VALUE__.

tanat.visualization.sequence.type.barplot.exception module#

Barplot visualization exceptions.

exception tanat.visualization.sequence.type.barplot.exception.UnsupportedShowAsError(show_as: str, pool_type: str)[source]#

Bases: TanaTException, ValueError

Raised when show_as=’duration’ is used with a pool type that has no duration.

__init__(show_as: str, pool_type: str) → None[source]#

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

Barplot settings.

class tanat.visualization.sequence.type.barplot.settings.BarAesthetics(*, show_as: ShowAs = 'count', sort: SortOrder = 'alphabetic', orientation: Orientation = 'vertical', display_unit: DisplayUnit | None = None)[source]#

Bases: object

Visual aesthetics for the barplot.

show_as[source]#

What each bar represents. "count" (default), "rate", or "duration".

Type:

Literal[‘count’, ‘rate’, ‘duration’]

sort[source]#

Bar sort order. "alphabetic" (default), "ascending", or "descending".

Type:

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

orientation[source]#

"vertical" (default) or "horizontal".

Type:

Literal[‘vertical’, ‘horizontal’]

display_unit[source]#

Output unit for datetime-based pools when show_as="duration". None keeps raw timestep values (required for numeric timestep pools).

Type:

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

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

Dump settings to a dict via Pydantic serialization.

orientation: Literal['vertical', 'horizontal'] = 'vertical'[source]#
show_as: Literal['count', 'rate', 'duration'] = 'count'[source]#
sort: Literal['alphabetic', 'ascending', 'descending'] = 'alphabetic'[source]#
class tanat.visualization.sequence.type.barplot.settings.BarMarkerSettings(*, alpha: float = 0.85, edge_color: str | None = None, bar_width: float = 0.8)[source]#

Bases: object

Bar marker visual properties.

alpha[source]#

Opacity (0.0 to 1.0).

Type:

float

edge_color[source]#

Bar border color. None means no border.

Type:

str | None

bar_width[source]#

Width fraction of the available slot (0 to 1).

Type:

float

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

Dump settings to a dict via Pydantic serialization.

class tanat.visualization.sequence.type.barplot.settings.BarplotSettings(*, 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: BarAesthetics = <factory>, null_handling: NullHandling = <factory>, marker: BarMarkerSettings = <factory>)[source]#

Bases: BaseVizSettings

Full settings for the barplot builder.

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

Dump settings to a dict via Pydantic serialization.

null_handling: NullHandling[source]#

Module contents#

Barplot package.

class tanat.visualization.sequence.type.barplot.BarAesthetics(*, show_as: ShowAs = 'count', sort: SortOrder = 'alphabetic', orientation: Orientation = 'vertical', display_unit: DisplayUnit | None = None)[source]#

Bases: object

Visual aesthetics for the barplot.

show_as[source]#

What each bar represents. "count" (default), "rate", or "duration".

Type:

Literal[‘count’, ‘rate’, ‘duration’]

sort[source]#

Bar sort order. "alphabetic" (default), "ascending", or "descending".

Type:

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

orientation[source]#

"vertical" (default) or "horizontal".

Type:

Literal[‘vertical’, ‘horizontal’]

display_unit[source]#

Output unit for datetime-based pools when show_as="duration". None keeps raw timestep values (required for numeric timestep pools).

Type:

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

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

Dump settings to a dict via Pydantic serialization.

orientation: Literal['vertical', 'horizontal'] = 'vertical'[source]#
show_as: Literal['count', 'rate', 'duration'] = 'count'[source]#
sort: Literal['alphabetic', 'ascending', 'descending'] = 'alphabetic'[source]#
class tanat.visualization.sequence.type.barplot.BarMarkerSettings(*, alpha: float = 0.85, edge_color: str | None = None, bar_width: float = 0.8)[source]#

Bases: object

Bar marker visual properties.

alpha[source]#

Opacity (0.0 to 1.0).

Type:

float

edge_color[source]#

Bar border color. None means no border.

Type:

str | None

bar_width[source]#

Width fraction of the available slot (0 to 1).

Type:

float

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

Dump settings to a dict via Pydantic serialization.

class tanat.visualization.sequence.type.barplot.BarplotSettings(*, 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: BarAesthetics = <factory>, null_handling: NullHandling = <factory>, marker: BarMarkerSettings = <factory>)[source]#

Bases: BaseVizSettings

Full settings for the barplot builder.

__init__(*args: Any, **kwargs: Any) → None[source]#
aesthetics: BarAesthetics[source]#
legend: LegendSettings[source]#
marker: BarMarkerSettings[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.barplot.BarplotVizBuilder(settings: dict | BaseVizSettings | None = None, *, allow_large: bool = False)[source]#

Bases: BaseSequenceVizBuilder

Builds bar charts from a SequencePool or an individual Sequence.

Typical usage via SequenceVisualizer:

SequenceVisualizer.barplot(show_as="count") \
    .title("Event counts") \
    .draw(pool, entity_feature="status") \
    .show()
SETTINGS_CLASS[source]#

alias of BarplotSettings

marker(*, alpha: float | None = None, edge_color: str | None = None, bar_width: float | None = None) → BarplotVizBuilder[source]#

Configure bar visual properties. Chainable.

Parameters:

  • alpha – Opacity (0–1).

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

  • bar_width – Width fraction of available slot, 0–1 (default 0.8).

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

Configure the x (horizontal) axis. Chainable.

Role depends on orientation:

  • "vertical" (default): categories on x, values on y → limit_min/limit_max are not meaningful here.

  • "horizontal": values on x, categories on y → use limit_min/limit_max to constrain the value range.

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 only).

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

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

Configure the y (vertical) axis. Chainable.

Role depends on orientation:

  • "vertical" (default): values on y, categories on x → use limit_min/limit_max to constrain the value range (e.g. limit_max=1.0 for rates).

  • "horizontal": categories on y, values on x → limit_min/limit_max are not meaningful here.

Parameters:

  • show – Hide the axis entirely when False.

  • label – Axis label text.

  • rotation – Tick label rotation in degrees.

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

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

exception tanat.visualization.sequence.type.barplot.UnsupportedShowAsError(show_as: str, pool_type: str)[source]#

Bases: TanaTException, ValueError

Raised when show_as=’duration’ is used with a pool type that has no duration.

__init__(show_as: str, pool_type: str) → None[source]#
On this page