bencher.results.composable_container

Submodules

Classes

`Axis`	A spatial composition direction -- the only thing that has an opposite.
`ComposableContainerBase`	A base class for renderer backends. A composable renderer
`ComposeType`	StrEnum is a Python `enum.Enum` that inherits from `str`. The default
`PaneLayout`	Controls how multi-dimensional data is laid out in panel displays.
`ComposableContainerDataset`	A base class for renderer backends. A composable renderer
`ComposableContainerPanel`	A base class for renderer backends. A composable renderer
`ComposableContainerRerun`	Combine complete Rerun recordings into one recording and Blueprint.
`RerunRecording`	One recording and its presentation metadata inside a composition.
`RerunViewKind`	Rerun Blueprint view types supported by recording composition.
`ComposableContainerVideo`	A base class for renderer backends. A composable renderer
`RenderCfg`	Configuration class for video rendering options.

Package Contents

class bencher.results.composable_container.Axis

Bases: strenum.StrEnum

A spatial composition direction – the only thing that has an opposite.

ComposeType has two members that say where the next container goes (right/down) and two that do not (sequence/overlay). Only the first pair can be flipped, so flip() lives here rather than on ComposeType: asking a non-spatial compose type for its opposite is now unrepresentable instead of a RuntimeError raised mid-render (plan 23 C6, phase P8).

The member values match the corresponding ComposeType values, so an Axis compares equal to the ComposeType it maps to.

right

down

flip() → Axis: Return the other axis. Total by construction.

to_compose_type() → ComposeType: Return the ComposeType that composes along this axis.

static from_horizontal(horizontal: bool) → Axis

class bencher.results.composable_container.ComposableContainerBase

A base class for renderer backends. A composable renderer

compose_method: ComposeType

container: list[Any] = []

label_len: int = 0

static label_formatter(var_name: str | None, var_value: float | str | None) → str | None

Take a variable name and values and return a pretty version with approximate fixed width

Parameters:

var_name (str | None) – The name of the variable, usually a dimension
var_value (int | float | str | None) – The value of the dimension

Returns:

Pretty string representation with fixed width, or None when: neither a name nor a value was given (every caller tests for None).

Return type:

str | None

append(obj: Any) → None

Add an object to the container. The relationship between the objects is defined by the ComposeType

Parameters:: obj (Any) – Object to add to the container

render()

Return a representation of the container that can be composed with other render() results. This function can also be used to defer layout and rending options until all the information about the container content is known. You may need to override this method depending on the container. See composable_container_video as an example.

Returns:: Visual representation of the container that can be combined with other containers
Return type:: Any

class bencher.results.composable_container.ComposeType

Bases: strenum.StrEnum

StrEnum is a Python enum.Enum that inherits from str. The default auto() behavior uses the member name as its value.

Example usage:

class Example(StrEnum):
    UPPER_CASE = auto()
    lower_case = auto()
    MixedCase = auto()

assert Example.UPPER_CASE == "UPPER_CASE"
assert Example.lower_case == "lower_case"
assert Example.MixedCase == "MixedCase"

right

down

sequence

overlay

as_axis() → Axis | None

The spatial axis this method composes along, or None if it has none.

sequence and overlay place nothing beside anything, so they have no axis and nothing to flip – hence None rather than a raise.

static from_horizontal(horizontal: bool) → ComposeType

class bencher.results.composable_container.PaneLayout

Bases: strenum.StrEnum

Controls how multi-dimensional data is laid out in panel displays.

grid: Use rows/columns for all dimensions (default, existing behavior) tabs: Use tabs for all outer dimensions, only the innermost uses grid tabs_and_grid: Use tabs for the outermost dimension, grid for inner dimensions

grid

tabs

tabs_and_grid

classmethod all() → list[PaneLayout]: Return all layout values. Use this instead of hard-coded name lists.

class bencher.results.composable_container.ComposableContainerDataset

Bases: bencher.results.composable_container.composable_container_base.ComposableContainerBase

A base class for renderer backends. A composable renderer

var_name: str | None = None

var_value: str | None = None

render(**kwargs)

Return a representation of the container that can be composed with other render() results. This function can also be used to defer layout and rending options until all the information about the container content is known. You may need to override this method depending on the container. See composable_container_video as an example.

Returns:: Visual representation of the container that can be combined with other containers
Return type:: Any

class bencher.results.composable_container.ComposableContainerPanel

Bases: bencher.results.composable_container.composable_container_base.ComposableContainerBase

A base class for renderer backends. A composable renderer

name: str | None = None

var_name: str | None = None

var_value: str | None = None

width: int | None = None

background_col: str | None = None

container: panel.layout.ListLike | list[Any] = []

_tabs: panel.Tabs | None = None

__post_init__() → None

append(obj)

Add an object to the container. The relationship between the objects is defined by the ComposeType

Parameters:: obj (Any) – Object to add to the container

render()

Return a representation of the container that can be composed with other render() results. This function can also be used to defer layout and rending options until all the information about the container content is known. You may need to override this method depending on the container. See composable_container_video as an example.

Returns:: Visual representation of the container that can be combined with other containers
Return type:: Any

class bencher.results.composable_container.ComposableContainerRerun

Bases: bencher.results.composable_container.composable_container_base.ComposableContainerBase

Combine complete Rerun recordings into one recording and Blueprint.

Input entity paths are namespaced under /item_N before being forwarded into a new recording. The generated Blueprint maps Bencher composition onto Rerun as follows:

right -> rrb.Horizontal
down -> rrb.Vertical
overlay -> shared views rooted at /, all items playing together
sequence -> shared views rooted at /, items spliced end to end in time so scrubbing the timeline plays them one after the other

View types are inferred from Rerun archetype metadata. Pass view_kinds to append() when a recording needs an explicit override.

container: list[RerunRecording] = []

output_path: str | pathlib.Path | None = None

name: str | None = None

application_id: str = 'bencher/composed'

static _to_recording(obj: str | pathlib.Path | RerunRecording, *, label: str | None, view_kinds: collections.abc.Iterable[RerunViewKind | str] | None) → RerunRecording

append(obj: str | pathlib.Path | RerunRecording, *, label: str | None = None, view_kinds: collections.abc.Iterable[RerunViewKind | str] | None = None) → None: Append an RRD path or a recording value with optional view metadata.

property _spec: _RerunComposeSpec

How this compose method is presented in Rerun.

The value is normalized first, so an out-of-vocabulary one raises a ValueError naming it rather than a bare KeyError.

_output_file() → pathlib.Path

_views(rrb, kinds: collections.abc.Iterable[RerunViewKind], *, origin: str, label: str): Build the view (or vertical stack of views) that displays one origin.

_layout(rrb, items: list[_ComposedItem]): Map the compose method onto a Blueprint layout of per-item views.

_read_items() → list[_ComposedItem]

_send_spliced(recording, items: list[_ComposedItem]) → None: Send items end to end in time, clearing each one as the next begins.

render(**_kwargs: Any) → str: Materialize the composition as one path-backed .rrd artifact.

class bencher.results.composable_container.RerunRecording

One recording and its presentation metadata inside a composition.

path: str | pathlib.Path

label: str | None = None

view_kinds: tuple[RerunViewKind, Ellipsis] | None = None

__post_init__() → None

class bencher.results.composable_container.RerunViewKind

Bases: strenum.StrEnum

Rerun Blueprint view types supported by recording composition.

spatial_2d = 'spatial_2d'

spatial_3d = 'spatial_3d'

time_series = 'time_series'

bar_chart = 'bar_chart'

tensor = 'tensor'

text_document = 'text_document'

text_log = 'text_log'

map = 'map'

graph = 'graph'

state_timeline = 'state_timeline'

class bencher.results.composable_container.ComposableContainerVideo

Bases: bencher.results.composable_container.composable_container_base.ComposableContainerBase

A base class for renderer backends. A composable renderer

append(obj: moviepy.VideoClip | moviepy.ImageClip | str | numpy.ndarray) → None

Appends an image or video to the container

Parameters:: obj (VideoClip | ImageClip | str | np.ndarray) – Any representation of an image or video
Raises:: RuntimeWarning – if file format is not recognised

calculate_duration(frames, render_cfg: RenderCfg)

render(render_cfg: RenderCfg | None = None, **kwargs) → moviepy.CompositeVideoClip

Composes the images/videos into a single image/video based on the type of compose method

Parameters:: compose_method (ComposeType, optional) – optionally override the default compose type. Defaults to None.
Returns:: A composite video clip containing the images/videos added via append()
Return type:: CompositeVideoClip

to_video(render_args: RenderCfg | None = None) → str

Returns the composite video clip as a webm file path

Returns:: webm filepath
Return type:: str

deep()

extend_clip(clip: moviepy.VideoClip, desired_duration: float)

class bencher.results.composable_container.RenderCfg

Configuration class for video rendering options.

This class controls how videos and images are composed and rendered together. It provides options for timing, layout, appearance, and labeling of the output.

compose_method

Method to compose multiple clips (sequence, right, down, overlay). Defaults to ComposeType.sequence.

Type:: ComposeType

var_name

Variable name for labeling. Defaults to None.

Type:: str, optional

var_value

Variable value for labeling. Defaults to None.

Type:: str, optional

background_col

RGB color for background. Defaults to white (255, 255, 255).

Type:: tuple[int, int, int]

duration

Target duration for the composed video in seconds. Defaults to 10.0.

Type:: float

default_duration

Fallback duration when duration is None. Defaults to 10.0.

Type:: float

duration_target

If True, tries to match target duration while respecting frame duration constraints. If False, uses exact duration. Defaults to True.

Type:: bool

min_frame_duration

Minimum duration for each frame in seconds. Defaults to 1/30.

Type:: float

max_frame_duration

Maximum duration for each frame in seconds. Defaults to 2.0.

Type:: float

margin

Margin size in pixels to add around clips. Defaults to 0.

Type:: int

compose_method: bencher.results.composable_container.composable_container_base.ComposeType

var_name: str | None = None

var_value: str | None = None

background_col: tuple[int, int, int] = (255, 255, 255)

duration: float = 10.0

default_duration: float = 10.0

duration_target: bool = True

min_frame_duration: float = 0.03333333333333333

max_frame_duration: float = 2.0

margin: int = 0