Panels¶

Panel components: one trame template per dock panel, built inside its DivLayout with state namespaced by panel id.

Modules:

• artifacts –

  The artifact browser: the telemetry artifact index in a table, with one artifact's record, files and spec beside it.

• browsers –

  The browsers workbench: the run index over one run's detail, beside the artifact index over one artifact's detail.

• field_viewer –

  The field viewer: a controller that opens a run's VTU as a FieldScene, the controls that steer it, and the 3D and plotly 2D views that show it.

• figure –

  The plotly panel: a figure that fills its dock tab, updated in place and bound to plotly events.

• launcher –

  The launcher panel: the catalogue as cards that open docks and renderables and run and stop scripts.

• log –

  The log panel: an xterm terminal fed line by line from the server loop, with a ring buffer replayed to clients that mount later.

• log_browser –

  The log browser: the telemetry log frame narrowed in polars, and a live mode following this process's tap and every other process's journal.

• monitors –

  The live monitors workbench: the run monitor beside the sweep monitor, over the log browser and the terminal as tabs.

• outputs –

  The outputs panel: one toggle per declared output of a catalogue card, each shown by its kind, the whole set swapped by show().

• run_monitor –

  The run monitor: the selected run's heartbeat, stage strip, convergence chart and a log tail, polled every second while visible.

• runs –

  The run browser: the telemetry run index in a table, with one bundle's stages, results, files and retention beside it.

• scene –

  The scene panels: one off-screen pyvista plotter each, mirrored in the browser by VTK.wasm or streamed by trame-rca, under a preset toolbar.

• sweep_monitor –

  The sweep monitor: a sweep's progress, its points grouped by state with dead workers marked stalled, and the failures with their tracebacks.

• table –

  The table panel: a TanStack table over a polars frame that sorts, filters, facets, hides and groups in the client, with the layout persisted per panel.

• terminal –

  The terminal panel: an xterm attached to a local shell or an Elmer container through a pseudo-terminal bridged on the server loop.

Type Aliases:

• Handler –

  A client event handler, called with the values its JS arguments evaluate to.

• Listener –

  A state listener, called with the changed state as keyword arguments.

Classes:

• Cls –

  Tailwind compositions the panels share; the strings appear literally so the stylesheet build scans them.

• Shared –

  The state keys panels share: a selection made in one panel is read by the others.

• ItemField –

  The keys of a picker item: the label shown, the value chosen and, optionally, whether it is offered but unavailable.

• Carry –

  What a disposed panel leaves in legacy for the panel rebuilt in its place.

• PanelComponent –

  A dock panel: its template is built once inside layout; state variables go through key.

Functions:

• labelled –

  A caption beside the control built inside the returned field: a toolbar row has no room for a floating label.

• chooser –

  A single-choice select over fixed values, bound to a state variable.

• picker –

  A single-choice select over the {title, value} items a state variable holds, bound to another.

• select_run –

  Publishes run_id as the shared selection; picking the selected run again still notifies every listener, so each one re-reads the run.

Attributes:

• FILL –

  The style of a panel's root: a column filling the dock body.

• TRIGGER_WIDTH –

  The default width of a toolbar select; a picker over long ids widens it.

• ITEM –

  The loop variable a picker's items are named by.

FILL = {'height': '100%', 'width': '100%', 'display': 'flex', 'flexDirection': 'column', 'minHeight': '0'}

TRIGGER_WIDTH = 'w-36'

ITEM = 'item'

Listener = Callable[..., object]

Handler = Callable[..., object]

PanelComponent(app: Workbench, id: str, title: str)

168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192

def __init__(self, app: "Workbench", id: str, title: str) -> None:
    """Builds the panel's template inside its own layout.

    Args:
        app: The workbench shell the panel is built in.
        id: The panel id, which names its template and namespaces its state.
        title: The panel's tab title.
    """
    self.listeners: list[Listener] = []
    """The state listeners registered through `listen`, dropped again by `dispose`."""
    self.bound: list[Handler] = []
    """The callables handed to `callback`, whose triggers `dispose` unregisters."""
    self.legacy: dict[Carry, object] = {}
    """What `dispose` leaves for a successor; read by its `succeed`, never through the reloadable classes."""

    super().__init__(app.server)
    self.app = app
    self.id = id
    self.title = title
    self.template_name = template_name(id)
    self.layout = DivLayout(app.server, template_name=self.template_name, style=FILL)

    with self.layout:
        _ = app.theme()
        self.build()

listeners: list[Listener] = []

bound: list[Handler] = []

legacy: dict[Carry, object] = {}

build() -> None

194
195
196

def build(self) -> None:
    """Adds the panel's widgets to its layout."""
    raise NotImplementedError

key(name: str) -> str

198
199
200

def key(self, name: str) -> str:
    """A state variable or trigger name namespaced to this panel."""
    return f"{self.id}_{name}".replace("-", "_")

status(message: str) -> None

202
203
204

def status(self, message: str) -> None:
    """Reports in the shell's status line."""
    self.app.status(message)

refresh() -> None

206
207
208

def refresh(self) -> None:
    """Pushes the template again after its widgets changed."""
    self.layout.flush_content()

callback(fn: Handler, args: str | None = None) -> Callback

210
211
212
213
214

def callback(self, fn: Handler, args: str | None = None) -> react.Callback:
    """A client event handler calling `fn` with the JS `args`, unregistered again when the panel is disposed."""
    self.bound.append(fn)

    return react.Callback(fn, args=args)

listen(*names: str) -> Callable[[L], L]

216
217
218
219
220
221
222
223
224
225

def listen[L: Listener](self, *names: str) -> Callable[[L], L]:
    """Registers a state listener like `state.change`, one the panel drops again when disposed."""

    def register(listener: L) -> L:
        _ = self.state.change(*names)(listener)
        self.listeners.append(listener)

        return listener

    return register

dispose() -> None

227
228
229
230
231
232
233
234
235
236
237
238
239
240

def dispose(self) -> None:
    """Releases what the panel registered on the server once it left the dock: triggers, state listeners and controller slots."""
    self._unbind_annotated_methods()

    # trame offers no public removal of a listener, nor a list of the triggers it named for a widget's callbacks; its own unbind reaches into the same dicts.
    for registered in self.state._change_callbacks.values():
        registered[:] = [(fn, translator) for fn, translator in registered if fn not in self.listeners]

    owned = [fn for fn in self.ctrl._triggers_fn2name if getattr(fn, "__self__", None) is self or fn in self.bound]
    for fn in owned:
        _ = self.ctrl.trigger_unregister(fn)

    self.listeners.clear()
    self.bound.clear()

succeed(previous: PanelComponent) -> None

242
243

def succeed(self, previous: "PanelComponent") -> None:
    """Called on a panel rebuilt under the id of `previous`, already disposed, to carry over what a fresh build would lose."""

on_visible(visible: bool) -> None

245
246

def on_visible(self, visible: bool) -> None:
    """Called when dockview shows or hides the panel."""

on_layout_changed() -> None

248
249

def on_layout_changed(self) -> None:
    """Called after the dock re-laid out its groups."""

labelled(label: str) -> Field

107
108
109
110
111
112
113
114

def labelled(label: str) -> Field:
    """A caption beside the control built inside the returned field: a toolbar row has no room for a floating label."""
    field = Field(orientation="horizontal", classes="w-auto gap-1")
    with field:
        # A crowded app bar would otherwise break a two-word caption over two lines and grow the bar.
        FieldLabel(title(label), classes=f"{Cls.CAPTION} whitespace-nowrap")

    return field

chooser(model: str, values: Sequence[str], *, width: str = TRIGGER_WIDTH, disabled: bool = False, label: Callable[[str], str] = title) -> None

117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133

def chooser(model: str, values: Sequence[str], *, width: str = TRIGGER_WIDTH, disabled: bool = False, label: Callable[[str], str] = title) -> None:
    """A single-choice select over fixed values, bound to a state variable.

    Args:
        model: The state variable the choice is bound to.
        values: The values offered, in order.
        width: The trigger's Tailwind width class.
        disabled: Whether the select is disabled.
        label: Makes the text each value reads as; Title Case by default.
    """
    with Select(model=model, disabled=disabled):
        with SelectTrigger(size=TRIGGER_SIZE, classes=width):
            SelectValue()

        with SelectContent():
            for value in values:
                SelectItem(label(value), value=value)

picker(model: str, items: str, *, placeholder: str = '', width: str = TRIGGER_WIDTH, disabled: bool = False) -> None

136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155

def picker(model: str, items: str, *, placeholder: str = "", width: str = TRIGGER_WIDTH, disabled: bool = False) -> None:
    """A single-choice select over the `{title, value}` items a state variable holds, bound to another.

    Args:
        model: The state variable the choice is bound to.
        items: The state variable holding the items.
        placeholder: The text shown while nothing is chosen.
        width: The trigger's Tailwind width class.
        disabled: Whether the select is disabled.
    """
    with Select(model=model, disabled=disabled):
        with SelectTrigger(size=TRIGGER_SIZE, classes=width):
            SelectValue(placeholder=placeholder)

        with SelectContent(), react.For(items=items, name=ITEM):
            SelectItem(
                [react.Bind(f"{ITEM}.{ItemField.TITLE}")],
                value=react.Bind(f"{ITEM}.{ItemField.VALUE}"),
                disabled=react.Bind(f"{ITEM}.{ItemField.DISABLED}"),
            )

select_run(state: State, run_id: str) -> None

158
159
160
161
162

def select_run(state: State, run_id: str) -> None:
    """Publishes `run_id` as the shared selection; picking the selected run again still notifies every listener, so each one re-reads the run."""
    with state:
        state[Shared.SELECTED_RUN_ID] = run_id
        state.dirty(Shared.SELECTED_RUN_ID)

A build123d Compound as a Renderable: instanced VTK actors with view-dependent silhouettes.

Classes:

• CompoundRenderable –

  A Renderable over a build123d Compound; the push to the OCP CAD Viewer is opt-in through ocp_vscode or FEMFORGE_OCP_VSCODE.

CompoundRenderable(compound: Compound, *, ocp_vscode: bool | None = None)

21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50

def __init__(self, compound: b3d.Compound, *, ocp_vscode: bool | None = None) -> None:
    """Instances the compound, or a placeholder label when it is empty, and pushes it to the OCP CAD Viewer when asked."""

    def placeholder() -> b3d.Compound:
        """A red label standing in for a compound with nothing to draw."""
        text = b3d.Text(EMPTY_TEXT, font_size=EMPTY_FONT_SIZE, font=EMPTY_FONT)

        return b3d.Compound(children=[text], label=EMPTY_LABEL, color=b3d.Color(1, 0, 0, 1))

    self.compound = compound if compound.children else placeholder()  # pyright: ignore[reportUnknownMemberType]  # build123d ships no type information

    to_viewer = enabled(Setting.OCP_VSCODE) if ocp_vscode is None else ocp_vscode
    if to_viewer:
        try:
            from ocp_vscode import show  # pyright: ignore[reportUnknownVariableType]  # ocp_vscode ships no type information
        except ModuleNotFoundError as error:
            if error.name != "ocp_vscode":
                raise

            raise ModuleNotFoundError('Showing compounds in the OCP CAD Viewer needs the ocp extra: pip install "femforge-workbench[ocp]".', name="ocp_vscode") from error

        show(
            self.compound,
            edge_accuracy=VIEWER_EDGE_ACCURACY,
            render_edges=True,
            tree_width=VIEWER_TREE_WIDTH,
            glass=False,
        )

    self.inst = Build123Instancer().parse(self.compound)

render(plotter: Plotter) -> None

52
53
54
55
56
57
58
59
60
61
62
63
64
65

def render(self, plotter: pv.Plotter) -> None:
    """Draw the compound into `plotter` under a top-down parallel projection; the plotter keeps its own background and anti-aliasing."""
    plotter.clear()
    plotter.suppress_rendering = True
    plotter.parallel_projection = True

    _ = self.inst.add_to_plotter(plotter)
    _ = self.inst.add_silhouettes(plotter)

    plotter.view_xy()  # pyright: ignore[reportCallIssue, reportUnknownMemberType]  # pyvista forwards the renderer method onto the plotter at runtime
    plotter.reset_camera()  # pyright: ignore[reportCallIssue, reportUnknownMemberType]

    plotter.suppress_rendering = False
    plotter.render()

Instanced VTK actors for a build123d Compound, with silhouettes and feature edges drawn over them.

Classes:

• Build123Instancer –

  Converts a build123d Compound hierarchy into instanced VTK actors: each unique shape meshed once, every occurrence an actor with its own world matrix and color.

Build123Instancer(tolerance: float = 0.1, angular_tolerance: float = 0.5, default_color: tuple[float, float, float] = (0.9137, 0.6941, 0.1529))

21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45

def __init__(
    self,
    tolerance: float = 0.1,
    angular_tolerance: float = 0.5,
    default_color: tuple[float, float, float] = (0.9137, 0.6941, 0.1529),
):
    """Sets the meshing tolerances and the color of a shape that carries none.

    Args:
        tolerance: The linear deflection the shapes are meshed to.
        angular_tolerance: The angular deflection the shapes are meshed to, in radians.
        default_color: The RGB color of a shape that carries none.
    """
    self.tolerance = tolerance
    self.angular_tolerance = angular_tolerance
    self.default_color = tuple(default_color)

    # TShape -> shared vtkPolyDataMapper (None if the shape produced no geometry)
    self._mapper_cache: dict = {}
    # canonical location-free PolyData per unique mapper, kept alive for export/picking
    self._geom: dict = {}
    # canonical-mesh id -> shared feature-edge mapper (see add_feature_edges)
    self._edge_mapper_cache: dict = {}
    # one actor per leaf occurrence
    self.actors: list[vtk.vtkActor] = []

parse(obj: Compound) -> Build123Instancer

49
50
51
52
53

def parse(self, obj: "b3d.Compound") -> "Build123Instancer":
    """Replaces the actors with one per leaf of `obj`'s hierarchy."""
    self.actors.clear()
    self._walk(obj, np.eye(4))
    return self

add_to_plotter(plotter: Plotter) -> Plotter

55
56
57
58
59

def add_to_plotter(self, plotter: pv.Plotter) -> pv.Plotter:
    """Adds every actor to `plotter`."""
    for actor in self.actors:
        plotter.add_actor(actor)
    return plotter

show(**kwargs) -> Plotter

61
62
63
64
65
66

def show(self, **kwargs) -> pv.Plotter:
    """Shows the actors in a new plotter window, passing `kwargs` to its show."""
    pl = pv.Plotter()
    self.add_to_plotter(pl)
    pl.show(**kwargs)
    return pl

add_silhouettes(plotter: Plotter, color: str | tuple[float, float, float] = 'black', line_width: float = 1.5, opacity: float = 1.0, feature_angle: float | None = 70.0, border_edges: bool = True) -> list[vtkActor]

 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124

def add_silhouettes(
    self,
    plotter: pv.Plotter,
    color: str | tuple[float, float, float] = "black",
    line_width: float = 1.5,
    opacity: float = 1.0,
    feature_angle: "float | None" = 70.0,  # None -> pure view rim, no crease edges
    border_edges: bool = True,
) -> list[vtk.vtkActor]:
    """Adds a view-dependent silhouette per instance, recomputed on every camera move, so `add_feature_edges` suits large assemblies better.

    Args:
        plotter: The plotter to add the silhouettes to.
        color: The line color.
        line_width: The line width, in pixels.
        opacity: The line opacity.
        feature_angle: The angle above which a crease draws too, in degrees; None draws the rim alone.
        border_edges: Draws the mesh's border edges too.
    """
    cam = plotter.renderer.GetActiveCamera()
    col = pv.Color(color).float_rgb
    sil_actors: list[vtk.vtkActor] = []

    for actor in self.actors:
        mesh = actor.GetMapper().GetInput()  # shared canonical PolyData

        sil = vtk.vtkPolyDataSilhouette()
        sil.SetInputData(mesh)
        sil.SetCamera(cam)
        sil.SetProp3D(actor)
        sil.SetBorderEdges(border_edges)
        if feature_angle is None:
            sil.SetEnableFeatureAngle(0)
        else:
            sil.SetEnableFeatureAngle(1)
            sil.SetFeatureAngle(feature_angle)

        smap = vtk.vtkPolyDataMapper()
        smap.SetInputConnection(sil.GetOutputPort())
        smap.ScalarVisibilityOff()

        sa = vtk.vtkActor()
        sa.SetMapper(smap)
        sa.SetUserMatrix(actor.GetUserMatrix())  # silhouette output is in local frame
        prop = sa.GetProperty()
        prop.SetColor(*col)
        prop.SetLineWidth(line_width)
        prop.SetOpacity(opacity)
        prop.LightingOff()
        sa.SetPickable(False)

        plotter.add_actor(sa)
        sil_actors.append(sa)

    return sil_actors

add_feature_edges(plotter: Plotter, color: str | tuple[float, float, float] = 'black', line_width: float = 1.5, opacity: float = 1.0, feature_angle: float = 30.0, boundary_edges: bool = True) -> list[vtkActor]

126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181

def add_feature_edges(
    self,
    plotter: pv.Plotter,
    color: str | tuple[float, float, float] = "black",
    line_width: float = 1.5,
    opacity: float = 1.0,
    feature_angle: float = 30.0,
    boundary_edges: bool = True,
) -> list[vtk.vtkActor]:
    """Adds each instance's crease and boundary edges, computed once per unique shape; smooth bodies show little.

    Args:
        plotter: The plotter to add the edges to.
        color: The line color.
        line_width: The line width, in pixels.
        opacity: The line opacity.
        feature_angle: The angle above which a crease draws, in degrees.
        boundary_edges: Draws the mesh's boundary edges too.
    """
    col = pv.Color(color).float_rgb
    edge_actors: list[vtk.vtkActor] = []

    for actor in self.actors:
        mesh = actor.GetMapper().GetInput()
        key = id(mesh)  # one shared canonical mesh per unique TShape

        edge_mapper = self._edge_mapper_cache.get(key)
        if edge_mapper is None:
            fe = vtk.vtkFeatureEdges()
            fe.SetInputData(mesh)
            fe.SetBoundaryEdges(boundary_edges)
            fe.FeatureEdgesOn()
            fe.SetFeatureAngle(feature_angle)
            fe.NonManifoldEdgesOff()
            fe.ManifoldEdgesOff()
            fe.ColoringOff()
            fe.Update()
            edge_mapper = vtk.vtkPolyDataMapper()
            edge_mapper.SetInputData(fe.GetOutput())  # bake once, not a live pipeline
            edge_mapper.ScalarVisibilityOff()
            self._edge_mapper_cache[key] = edge_mapper

        ea = vtk.vtkActor()
        ea.SetMapper(edge_mapper)
        ea.SetUserMatrix(actor.GetUserMatrix())
        prop = ea.GetProperty()
        prop.SetColor(*col)
        prop.SetLineWidth(line_width)
        prop.SetOpacity(opacity)
        prop.LightingOff()
        ea.SetPickable(False)

        plotter.add_actor(ea)
        edge_actors.append(ea)

    return edge_actors

Figure conventions in the dock: the tab carries the title on screen, layout.meta.title names the figure for export.

Functions:

• layout_json –

  The figure's layout as plain JSON.

• title_of –

  The name a figure gives itself: layout.meta.title, else its on-screen title, else empty.

• export_options –

  The modebar's toImageButtonOptions: a 2x PNG named after the figure's title.

• with_title –

  A copy of the figure carrying its export title centred at the top, with the margin that needs.

layout_json(figure: Figure) -> Json

20
21
22
23
24
25
26
27

def layout_json(figure: go.Figure) -> Json:
    """The figure's layout as plain JSON."""
    encoded = cast("Json", figure.to_plotly_json())
    layout = encoded.get("layout")
    if not isinstance(layout, Mapping):
        return {}

    return dict(cast("Mapping[str, object]", layout))

title_of(figure: Figure) -> str

30
31
32
33
34
35
36
37
38
39
40

def title_of(figure: go.Figure) -> str:
    """The name a figure gives itself: layout.meta.title, else its on-screen title, else empty."""
    layout = layout_json(figure)
    named = text(section(layout, "meta"), "title", "")
    if named:
        return named

    title = layout.get("title")
    plain = title if isinstance(title, str) else ""

    return text(section(layout, "title"), "text", plain)

export_options(figure: Figure) -> Json

43
44
45
46
47

def export_options(figure: go.Figure) -> Json:
    """The modebar's toImageButtonOptions: a 2x PNG named after the figure's title."""
    stem = re.sub(r"[^A-Za-z0-9._-]+", "-", title_of(figure)).strip("-")

    return {"format": EXPORT_FORMAT, "scale": EXPORT_SCALE, "filename": stem or DEFAULT_NAME}

with_title(figure: Figure) -> Figure

50
51
52
53
54
55
56
57
58
59

def with_title(figure: go.Figure) -> go.Figure:
    """A copy of the figure carrying its export title centred at the top, with the margin that needs."""
    text = title_of(figure)
    titled = go.Figure(figure)
    if not text:
        return titled

    titled.update_layout(title={"text": text, "x": 0.5, "xanchor": "center"}, margin={"t": TITLED_TOP_MARGIN})

    return titled

Figure helpers: the regular grid a scatter of samples needs before it can draw as a surface.

Functions:

• xyz_to_meshgrid –

  Cubic-interpolates scattered (x, y, z) samples onto a regular grid for surface plotting.

xyz_to_meshgrid(x: PlotData, y: PlotData, z: PlotData, grid_points: int = 100) -> tuple[PlotData, PlotData, PlotData]

12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

def xyz_to_meshgrid(x: PlotData, y: PlotData, z: PlotData, grid_points: int = 100) -> tuple[PlotData, PlotData, PlotData]:
    """Cubic-interpolates scattered (x, y, z) samples onto a regular grid for surface plotting.

    Args:
        x: The samples' x coordinates.
        y: The samples' y coordinates.
        z: The sample values.
        grid_points: The grid's point count along each axis.
    """
    from scipy.interpolate import griddata  # pyright: ignore[reportUnknownVariableType]

    grid_x = np.linspace(min(x), max(x), grid_points)
    grid_y = np.linspace(min(y), max(y), grid_points)
    x2, y2 = np.meshgrid(grid_x, grid_y)
    grid_z = cast(
        np.ndarray,
        griddata(
            points=(x, y),
            values=z,
            xi=(x2, y2),
            method="cubic",
        ),
    )
    return grid_x, grid_y, grid_z

Grouped rows on polars frames: a composite label per group for the tables to group by.

Type Aliases:

• Row –

  A table row: each column's value by name.

Functions:

• group_rows –

  The frame with a group label per by value: the value, the first of each first column, the row count and the maximum of each max_ column.

Attributes:

• GROUP_COLUMN –

  The column group_rows adds and the tables group by; reserved in every frame a table shows.

GROUP_COLUMN = 'group'

Row = dict[str, object]

group_rows(frame: DataFrame, by: str, first: Sequence[str] = (), max_: Sequence[str] = ()) -> DataFrame

18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

def group_rows(frame: pl.DataFrame, by: str, first: Sequence[str] = (), max_: Sequence[str] = ()) -> pl.DataFrame:
    """The frame with a group label per `by` value: the value, the first of each `first` column, the row count and the maximum of each `max_` column.

    Args:
        frame: The rows to label.
        by: The column whose values form the groups.
        first: Columns whose first value per group joins the label.
        max_: Columns whose maximum per group joins the label.
    """
    firsts = [pl.first(name).alias(f"first {name}") for name in first]
    maxima = [pl.max(name).alias(f"max {name}") for name in max_]
    groups = frame.group_by(by, maintain_order=True).agg(*firsts, *maxima, pl.len().alias("count"))

    parts: list[pl.Expr] = [pl.col(by).cast(pl.String)]
    parts.extend(pl.col(f"first {name}").cast(pl.String) for name in first)
    parts.append(pl.format("{} rows", pl.col("count")))
    parts.extend(pl.format("max " + name + " {}", pl.col(f"max {name}").round(DECIMALS)) for name in max_)
    labelled = groups.select(pl.col(by), pl.concat_str(parts, separator=LABEL_SEPARATOR).alias(GROUP_COLUMN))

    return frame.join(labelled, on=by, how="left", maintain_order="left")