figures

Plotly figure builder functions, one module per dashboard section.

fstg_toolkit.app.figures.common.hex_to_rgba(hex_color: str, alpha: float) → str

Convert a hex colour string to an RGBA CSS string.

Parameters:

• hex_color (str) – Colour in #RRGGBB format (e.g. '#636EFA').

• alpha (float) – Opacity in the range [0, 1].

Returns:

Colour in rgba(R, G, B, alpha) format suitable for Plotly.

Return type:

str

fstg_toolkit.app.figures.common.integer_tick_step(max_val: int, max_range: int = 5) → int

Return a tick step so that ticks land only on integers.

For small ranges (≤ max_range) every integer is shown. For larger ranges the step is chosen so that roughly 8 ticks appear, avoiding float tick values.

fstg_toolkit.app.figures.common.norm_min_max_size(s: list[float], new_min: float = 0, new_max: float = 1) → list[float]

fstg_toolkit.app.figures.data.areas_per_region_figure(records: list[dict[str, str]]) → Figure

fstg_toolkit.app.figures.data.subjects_per_factors_figure(records: list[dict[str, str]], factors: list[str]) → Figure

fstg_toolkit.app.figures.matrices.break_width_to_cols(break_name: str) → int

fstg_toolkit.app.figures.matrices.build_matrices_figure(matrices, t, desc, n_cols=3, vs_ratio=0.1, hs_ratio=0.2, matrix_height=300)

fstg_toolkit.app.figures.metrics.build_distribution_comparison_plot(metric: DataFrame, factors: list[str])

fstg_toolkit.app.figures.metrics.build_longitudinal_scalar_comparison_plot(metric: Series, factors: list[str])

Build a longitudinal line plot with 95 % confidence-interval bands.

For each time point the population mean and 95 % CI (mean ± 1.96 × std / sqrt(n)) are computed across subjects. The result is a Plotly figure where each group defined by factors is drawn as a coloured mean line surrounded by a semi-transparent uncertainty band.

Factor assignment follows Plotly Express conventions:

• factors[0] → line colour

• factors[1] → subplot rows (optional)

• factors[2] → subplot columns (optional)

Parameters:

• metric (pd.Series) – Per-subject, per-time-point scalar values. The index must contain a level named 'Time' and may contain additional factor levels.

• factors (list of str) – Names of index levels used to split the population into groups. Up to three factors are supported (colour, row, column).

Returns:

A Plotly figure with mean lines and 95 % CI bands, optionally faceted into a subplot grid when two or more factors are supplied.

Return type:

go.Figure

fstg_toolkit.app.figures.metrics.build_metrics_plot(metric: DataFrame | Series, factors: list[str])

fstg_toolkit.app.figures.metrics.build_scalar_comparison_plot(metric: Series, factors: list[str])

fstg_toolkit.app.figures.subject.build_spatial_figure(props: dict[str, Any], gap_size: float = 0.005, thickness: float = 0.1, radius: float = 1.0) → Figure

fstg_toolkit.app.figures.subject.build_subject_figure(props: dict[str, Any], areas: Series) → Figure

fstg_toolkit.app.figures.subject.generate_spatial_graph_props(graph: SpatioTemporalGraph, areas_desc: DataFrame, regions: list[str]) → dict[str, Any]

fstg_toolkit.app.figures.subject.generate_temporal_graph_props(graph: SpatioTemporalGraph, regions: list[str], color_prop: str = 'internal_strength', size_prop: str = 'efficiency') → dict[str, Any]

class fstg_toolkit.app.figures.frequent.FrequentFigureBuilderRegistry

Bases: object

Registry for frequent pattern analysis figure builders.

Builders self-register via the @FrequentFigureBuilderRegistry.register(name) decorator. Look up by the registered display-name string.

Each builder may optionally declare compatible modes (e.g. {'s', 'st'}) and a tooltip type. A mode of None means the builder is available in all modes. A tooltip of None means no custom tooltip is shown.

Tooltip types

None

No custom tooltip.

'pattern'

Hover point carries a 1-based pattern index on x; show the corresponding pattern graph and its count.

'pattern-pair'

Hover point carries 1-based pattern indices on both x and y (heatmap cell); show both pattern graphs and the co-occurrence count.

classmethod get(name: str) → Callable[[FrequentPatternsPopulationAnalysis, list[str]], Figure]

Look up a builder by its registered name.

Parameters:

name (str) – The registered display name.

Returns:

The registered figure builder callable.

Return type:

FrequentAnalysisBuilder

Raises:

KeyError – If no builder is registered under this name.

classmethod get_description(name: str) → str | None

Return the description declared for the given figure builder.

Parameters:

name (str) – The registered display name.

Returns:

The human-readable description, or None if not set.

Return type:

str or None

Raises:

KeyError – If no builder is registered under this name.

classmethod names(mode: str | None = None) → list[str]

Return the names of builders compatible with the given mode.

Parameters:

mode (str) – The current mode (e.g. 's', 't', or 'st').

Returns:

Sorted list of compatible builder display names.

Return type:

list[str]

classmethod register(name: str, modes: set[str] | None = None, tooltip: str | None = None, description: str | None = None) → Callable[[Callable[[FrequentPatternsPopulationAnalysis, list[str]], Figure]], Callable[[FrequentPatternsPopulationAnalysis, list[str]], Figure]]

Class decorator factory that registers a builder under the given name.

Parameters:

• name (str) – The display name to register the builder under.

• modes (set[str] or None, optional) – Set of compatible modes (e.g. {'s', 'st'}). None means the builder is available in all modes.

• tooltip (str or None, optional) – Tooltip type for this figure. One of 'pattern', 'pattern-pair', or None (no tooltip).

• description (str or None, optional) – Short human-readable description of what the figure shows.

Returns:

Decorator that stores the builder and returns it unchanged.

Return type:

Callable

classmethod tooltip_type(name: str) → str | None

Return the tooltip type declared for the given figure builder.

Parameters:

name (str) – The registered display name.

Returns:

The tooltip type ('pattern', 'pattern-pair', or None).

Return type:

str or None

Raises:

KeyError – If no builder is registered under this name.

fstg_toolkit.app.figures.frequent.build_occurrence_histogram_plot(analysis: FrequentPatternsPopulationAnalysis, factors: list[str]) → Figure

Histogram of pattern occurrence counts.

Parameters:

• analysis (FrequentPatternsPopulationAnalysis) – The population analysis to visualize.

• factors (list[str]) – Factor columns to facet by.

Returns:

A Plotly bar chart with occurrence counts on x-axis and number of patterns on y-axis.

Return type:

go.Figure

fstg_toolkit.app.figures.frequent.build_pattern_co_occurrence_plot(analysis: FrequentPatternsPopulationAnalysis, factors: list[str]) → Figure

Symmetric heatmap of pattern co-occurrence across subjects.

Parameters:

• analysis (FrequentPatternsPopulationAnalysis) – The population analysis to visualize.

• factors (list[str]) – Factor columns to facet by.

Returns:

A Plotly heatmap where cell (i, j) = number of subjects with both patterns.

Return type:

go.Figure

fstg_toolkit.app.figures.frequent.build_pattern_complexity_plot(analysis: FrequentPatternsPopulationAnalysis, factors: list[str]) → Figure

Histogram of pattern sizes (node counts).

Parameters:

• analysis (FrequentPatternsPopulationAnalysis) – The population analysis to visualize.

• factors (list[str]) – Factor columns to facet by.

Returns:

A Plotly bar chart with pattern size on x-axis and count on y-axis.

Return type:

go.Figure

fstg_toolkit.app.figures.frequent.build_pattern_figure(pattern: FrequentPattern) → Figure

Build a small Plotly figure visualizing a single frequent pattern graph.

Parameters:

pattern (FrequentPattern) – The frequent pattern to visualize.

Returns:

A Plotly figure showing the pattern as a directed graph.

Return type:

go.Figure

fstg_toolkit.app.figures.frequent.build_pattern_frequency_plot(analysis: FrequentPatternsPopulationAnalysis, factors: list[str]) → Figure

fstg_toolkit.app.figures.frequent.build_patterns_per_region_plot(analysis: FrequentPatternsPopulationAnalysis, factors: list[str]) → Figure

Bar chart of pattern counts per brain region.

Parameters:

• analysis (FrequentPatternsPopulationAnalysis) – The population analysis to visualize.

• factors (list[str]) – Factor columns to facet by.

Returns:

A Plotly bar chart with regions on x-axis and pattern counts on y-axis.

Return type:

go.Figure

fstg_toolkit.app.figures.frequent.build_region_co_occurrence_plot(analysis: FrequentPatternsPopulationAnalysis, factors: list[str]) → Figure

Symmetric heatmap of region co-occurrence via spatial edges.

Parameters:

• analysis (FrequentPatternsPopulationAnalysis) – The population analysis to visualize.

• factors (list[str]) – Factor columns to facet by.

Returns:

A Plotly heatmap with region pairs as axes.

Return type:

go.Figure

fstg_toolkit.app.figures.frequent.build_temporal_dynamics_plot(analysis: FrequentPatternsPopulationAnalysis, factors: list[str]) → Figure

Stacked bar chart of RC5 transition types per brain region.

Parameters:

• analysis (FrequentPatternsPopulationAnalysis) – The population analysis to visualize.

• factors (list[str]) – Factor columns to facet by.

Returns:

A Plotly figure with regions on x-axis and transition type counts as stacked bars.

Return type:

go.Figure