linked_legendgroup_kwargs

yohou.plotting._utils.linked_legendgroup_kwargs(member_name, legend_tracker, *, is_primary)

Build legendgroup / showlegend kwargs for linked traces.

All traces that share the same member_name legendgroup are toggled together when the user clicks the legend entry. Only the primary trace (typically the line) should carry showlegend=True (once); secondary traces (outlier markers, threshold lines, confidence bands, ...) set showlegend=False while still belonging to the same group.

Parameters

Name	Type	Description	Default
member_name	str	Legend group identifier (e.g. panel member display name).	required
legend_tracker	LegendTracker	Tracker used to de-duplicate legend entries across subplots.	required
is_primary	bool	True for the main trace that should appear in the legend; False for auxiliary traces (markers, bands, ...).	required

Returns

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

Examples

>>> from yohou.plotting import linked_legendgroup_kwargs
>>> tracker = LegendTracker()
>>> linked_legendgroup_kwargs("sales", tracker, is_primary=True)
{'legendgroup': 'sales', 'showlegend': True, 'name': 'sales'}
>>> linked_legendgroup_kwargs("sales", tracker, is_primary=False)
{'legendgroup': 'sales', 'showlegend': False}

See Also

grouped_legend_kwargs : Build kwargs for titled legend groups. [LegendTracker][yohou.plotting._utils.LegendTracker] : Track which legend entries have been shown.

Source Code

View on GitHub

Show/Hide source

def linked_legendgroup_kwargs(
    member_name: str,
    legend_tracker: LegendTracker,
    *,
    is_primary: bool,
) -> dict:
    """Build ``legendgroup`` / ``showlegend`` kwargs for linked traces.

    All traces that share the same *member_name* ``legendgroup`` are
    toggled together when the user clicks the legend entry.  Only the
    *primary* trace (typically the line) should carry
    ``showlegend=True`` (once); secondary traces (outlier markers,
    threshold lines, confidence bands, ...) set ``showlegend=False``
    while still belonging to the same group.

    Parameters
    ----------
    member_name : str
        Legend group identifier (e.g. panel member display name).
    legend_tracker : LegendTracker
        Tracker used to de-duplicate legend entries across subplots.
    is_primary : bool
        ``True`` for the main trace that should appear in the legend;
        ``False`` for auxiliary traces (markers, bands, ...).

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

    Examples
    --------
    >>> from yohou.plotting import linked_legendgroup_kwargs
    >>> tracker = LegendTracker()
    >>> linked_legendgroup_kwargs("sales", tracker, is_primary=True)
    {'legendgroup': 'sales', 'showlegend': True, 'name': 'sales'}
    >>> linked_legendgroup_kwargs("sales", tracker, is_primary=False)
    {'legendgroup': 'sales', 'showlegend': False}

    See Also
    --------
    [`grouped_legend_kwargs`][yohou.plotting._utils.grouped_legend_kwargs] : Build kwargs for titled legend groups.
    [`LegendTracker`][yohou.plotting._utils.LegendTracker] : Track which legend entries have been shown.
    """
    if is_primary:
        return {
            "legendgroup": member_name,
            "showlegend": legend_tracker.should_show(member_name),
            "name": member_name,
        }
    return {
        "legendgroup": member_name,
        "showlegend": False,
    }