Ensembler

The Ensembler module provides a flexible framework for constructing multi-panel biomechanical visualizations from time-series data.

It is built around a modular architecture consisting of: data loading, plot specification, and pluggable rendering strategies.

Overview

A typical workflow is:

1. Load data via Ensembler

2. Define subplot configurations using PlotSpec

3. Assign rendering strategies (e.g., lines, mean ± SD, events)

4. Build and display the figure

Example

lines_and_events = CompositeRenderer(
    IndividualLinesRenderer(),
    EventOverlayRenderer()
)

ens = Ensembler(
    in_folder=fld,
    channels=channels,
    n_rows=rows,
    n_cols=cols,
    subj_list=subj_list,
    condition_spec=spec
)

ens.add_subplot(
    PlotSpec(
        'Right Knee Sagittal plane',
        'Kinemat_x',
        companions=['Angles_x'],
        row=1,
        col=1,
        renderer=IndividualLinesRenderer(),
        x_label='% stance',
        y_label='Joint angle (deg)'
    )
)

ens.add_subplot(
    PlotSpec(
        'Right Knee Sagittal plane (mean +/- SD)',
        'Kinemat_x',
        companions=['Angles_x'],
        row=1,
        col=2,
        renderer=MeanSDRenderer(),
        x_label='% stance',
        y_label='Joint angle (deg)'
    )
)

fig = ens.build(title='Kinemat vs Plug-in Gait')
fig.show()

Core Components

Ensembler

class biomechzoo.ensembler.ensembler.Ensembler(in_folder, channels, n_rows, n_cols, condition_spec=None, subj_list=None, str_match=None, events=None)

Bases: object

Parameters:

• in_folder (str)

• channels (list[str])

• n_rows (int)

• n_cols (int)

• condition_spec (ConditionSpec | None)

• subj_list (list[str] | None)

• str_match (list[str] | None)

• events (list[str])

add_subplot(spec)

Parameters:

spec (PlotSpec)

build(title='Ensembler', height=400, width=500)

Parameters:

• title (str)

• height (int)

• width (int)

Return type:

Figure

Plot Specification

class biomechzoo.ensembler.plot_spec.PlotSpec(channel: str, condition: str = None, row: int = 1, col: int = 1, renderer: biomechzoo.ensembler.renderers.Renderer = None, events: list[str] = <factory>, companions: list[str] = <factory>, group_by: str | None = None, group_map: dict[str, str] | None=None, title: str = '', x_label: str = '', y_label: str = '')

Bases: object

Parameters:

• channel (str)

• condition (str)

• row (int)

• col (int)

• renderer (Renderer)

• events (list[str])

• companions (list[str])

• group_by (str | None)

• group_map (dict[str, str] | None)

• title (str)

• x_label (str)

• y_label (str)

channel: str

condition: str = None

row: int = 1

col: int = 1

renderer: Renderer = None

events: list[str]

companions: list[str]

group_by: str | None = None

group_map: dict[str, str] | None = None

title: str = ''

x_label: str = ''

y_label: str = ''

property all_conditions

Rendering System

Base renderers define how data is visualized.

class biomechzoo.ensembler.renderers.IndividualLinesRenderer

Bases: Renderer

render(fig, store, style, spec, row, col)

class biomechzoo.ensembler.renderers.MeanSDRenderer

Bases: Renderer

render(fig, store, style, spec, row, col)

class biomechzoo.ensembler.renderers.EventOverlayRenderer

Bases: Renderer

render(fig, store, style, spec, row, col)

class biomechzoo.ensembler.renderers.CompositeRenderer(*renderers)

Bases: Renderer

Run multiple renderers on the same subplot

Parameters:

renderers (Renderer)

render(fig, store, style, spec, row, col)

Data Management

class biomechzoo.ensembler.data_store.DataStore(fld, condition_spec=None, events=None, subj_list=None, str_match=None)

Bases: object

Loads, indexes and extracts relevant data and information from the zoo files.

Parameters:

condition_spec (ConditionSpec | None)

get_lines(channel, condition)

get_events(channel, condition, event_name)

get_subject_ids(channel, condition)

get_event_values(channel, condition, event_name)

Convenience — y-only, for violin/stats renderers.

Parameters:

• channel (str)

• condition (str)

• event_name (str)

Return type:

list[float]

get_event_subject_ids(channel, condition, event_name)

to_events_dataframe(channels, event_names)

Returns a long-formant DataFrame of all scalar events specified

Parameters:

• channels (list[str])

• event_names (list[str])

to_lines_dataframe(channels)

Returns a long-format DataFrame of all line data. All lines need to be time-normalized

Parameters:

channels (list[str])

Helpers

biomechzoo.ensembler.helpers.match_condition(path, conditions)

biomechzoo.ensembler.helpers.extract_subject_id(f, subj_list, str_pattern)

Extracts the subject ID from the zoo file path and a string match using a regular expression of a known list of subject IDs. :Parameters: * f (str) – File path to the zoo file.

• subj_list (list of str) – List of subject IDs.

• str_pattern (list of str) – String pattern to match the subject IDs.

Returns:

s (str or None) – Subject ID if found, otherwise None.

class biomechzoo.ensembler.helpers.ZooEvent(x, y)

Bases: NamedTuple

Parameters:

• x (float)

• y (float)

x: float

Alias for field number 0

y: float

Alias for field number 1

biomechzoo.ensembler.helpers.extract_events(ch_data, event_name)

Extracts the named event scalers (value and frame) from a zoo file.

biomechzoo.ensembler.helpers.compute_ensemble(arrays)

Compute time normalized mean and standard deviation for a list of arrays.

Parameters:

arrays (list[np.ndarray])

Returns:

• mean (array)

• upper (array) – mean + std

• lower (array) – mean - std

class biomechzoo.ensembler.helpers.ConditionSource(value)

Bases: Enum

Enum defining condition sources.

BETWEEN = 'folder'

WITHIN = 'channel'

class biomechzoo.ensembler.helpers.ConditionSpec(source, conditions=<factory>, channel_map=None, base_channels=<factory>, suffix_map=None)

Bases: object

Describes how the conditions are encoded in the data

Parameters:

• source (ConditionSource)

• conditions (list[str])

• channel_map (dict[str, dict[str, str]] | None)

• base_channels (list[str])

• suffix_map (dict[str, str] | None)

source: ConditionSource

conditions: list[str]

channel_map: dict[str, dict[str, str]] | None = None

base_channels: list[str]

suffix_map: dict[str, str] | None = None

biomechzoo.ensembler.helpers.align_by_subject(vals_a, subjects_a, vals_b, subjects_b)

Parameters:

• vals_a (list[float])

• subjects_a (list[str])

• vals_b (list[float])

• subjects_b (list[str])

biomechzoo.ensembler.helpers.resolve_shade(color)

Styling

class biomechzoo.ensembler.style_content.StyleContext(subjects, conditions)

Bases: object

Owns all color/dash assignments and legend deduplication state. Shared across the entire figure built so assignments are consistent

subject_color(subject)

Parameters:

subject (str)

condition_color(condition)

Parameters:

condition (str)

Return type:

str

condition_dash(condition)

Parameters:

condition (str)

Return type:

str

should_show_legend(namespace, key)

Returns True the first time (namespace, key) is seen,then False