grouped_legend_kwargs

yohou.plotting._utils.grouped_legend_kwargs(group_title, entry_name, legend_tracker, *, is_first_in_group)

Build kwargs for a trace that belongs to a titled legend group.

Plotly's legendgrouptitle displays a header above a group of legend entries. All traces sharing the same legendgroup toggle together; each trace gets its own visible name in the legend.

Parameters

Name	Type	Description	Default
group_title	str	Title shown above the legend group (e.g. member name "a").	required
entry_name	str	Individual trace label (e.g. "mean", "std").	required
legend_tracker	LegendTracker	De-duplicates entries across subplots.	required
is_first_in_group	bool	When True, attaches the legendgrouptitle dict.	required

Returns

Type	Description
dict	Ready-to-unpack kwargs for fig.add_trace(go.Scatter(..., **kw)).

Examples

>>> tracker = LegendTracker()
>>> grouped_legend_kwargs("sensor_a", "mean", tracker, is_first_in_group=True)
{'legendgroup': 'sensor_a', 'showlegend': True, 'name': 'mean', 'legendgrouptitle': {'text': 'sensor_a'}}
>>> grouped_legend_kwargs("sensor_a", "std", tracker, is_first_in_group=False)
{'legendgroup': 'sensor_a', 'showlegend': True, 'name': 'std'}

See Also

linked_legendgroup_kwargs : Build kwargs for linked (ungrouped) legend entries. [LegendTracker][yohou.plotting._utils.LegendTracker] : Track which legend entries have been shown.

Source Code

View on GitHub

Show/Hide source

def grouped_legend_kwargs(
    group_title: str,
    entry_name: str,
    legend_tracker: LegendTracker,
    *,
    is_first_in_group: bool,
) -> dict:
    """Build kwargs for a trace that belongs to a titled legend group.

    Plotly's ``legendgrouptitle`` displays a header above a group of
    legend entries.  All traces sharing the same ``legendgroup`` toggle
    together; each trace gets its own visible ``name`` in the legend.

    Parameters
    ----------
    group_title : str
        Title shown above the legend group (e.g. member name ``"a"``).
    entry_name : str
        Individual trace label (e.g. ``"mean"``, ``"std"``).
    legend_tracker : LegendTracker
        De-duplicates entries across subplots.
    is_first_in_group : bool
        When ``True``, attaches the ``legendgrouptitle`` dict.

    Returns
    -------
    dict
        Ready-to-unpack kwargs for ``fig.add_trace(go.Scatter(..., **kw))``.

    Examples
    --------
    >>> tracker = LegendTracker()
    >>> grouped_legend_kwargs("sensor_a", "mean", tracker, is_first_in_group=True)
    {'legendgroup': 'sensor_a', 'showlegend': True, 'name': 'mean', 'legendgrouptitle': {'text': 'sensor_a'}}
    >>> grouped_legend_kwargs("sensor_a", "std", tracker, is_first_in_group=False)
    {'legendgroup': 'sensor_a', 'showlegend': True, 'name': 'std'}

    See Also
    --------
    [`linked_legendgroup_kwargs`][yohou.plotting._utils.linked_legendgroup_kwargs] : Build kwargs for linked (ungrouped) legend entries.
    [`LegendTracker`][yohou.plotting._utils.LegendTracker] : Track which legend entries have been shown.
    """
    key = f"{group_title}::{entry_name}"
    kw: dict = {
        "legendgroup": group_title,
        "showlegend": legend_tracker.should_show(key),
        "name": entry_name,
    }
    if is_first_in_group:
        kw["legendgrouptitle"] = {"text": group_title}
    return kw