plot_subseasonality

yohou.plotting.diagnostics.plot_subseasonality(df, *, columns=None, seasonality='month', kind='mean', show_mean=True, groups=None, facet_n_cols=4, color_palette=None, title=None, x_label=None, y_label=None, width=None, height=None, connect_gaps=False, show_legend=True, resampler=None, line_width=2.0, marker_size=4, marker_opacity=0.8, overlay_opacity=0.15, mean_width=2.0, mean_dash='dash')

Plot seasonal subseries.

Creates one mini subplot per season (e.g. 12 for months, 4 for quarters). Within each subplot the values for that season across all cycles are connected chronologically, with an optional horizontal mean line. This view highlights both the level differences between seasons and any trends within each season over time.

For panel data, returns one figure per member with groups overlaid by colour. When only a single member exists, a plain go.Figure is returned instead of a dict.

Parameters

Name	Type	Description	Default
df	DataFrame	Input DataFrame with 'time' column and numeric columns.	required
columns	str | list[str] | None	Column(s) to plot. If None, uses all numeric columns except 'time'.	None
seasonality	str	Seasonal frequency: "month", "quarter", "weekday", "week", "hour".	"month"
kind	(mean, lines, box, violin)	Visualization style within each season subplot: "mean" - aggregated mean-per-cycle line with markers (default). "lines" - one thin line per cycle at overlay_opacity, with the mean line overlaid on top. "box" - one box per cycle showing value distribution. "violin" - one violin per cycle showing value distribution.	"mean"
show_mean	bool	Show a horizontal mean line within each season subplot.	True
groups	list[str] | None	Panel group prefixes to plot.	None
facet_n_cols	int	Number of columns in the subplot grid.	4
color_palette	list[str] | None	Custom color palette (one color per group).	None
title	str | None	Plot title.	None
x_label	str | None	X-axis label.	None
y_label	str | None	Y-axis label.	None
width	int | None	Plot width in pixels.	None
height	int | None	Plot height in pixels.	None
connect_gaps	bool	If True, connect lines across missing data gaps.	False
show_legend	bool	Whether to display the legend.	True
resampler	bool | Literal['widget'] | None	Enable plotly-resampler for large datasets. True returns a FigureResampler, "widget" a FigureWidgetResampler, None reads from get_config.	None
line_width	float	Line width for cycle traces.	2.0
marker_size	float	Marker size for data points.	4
marker_opacity	float	Opacity of scatter markers.	0.8
overlay_opacity	float	Opacity of per-cycle lines when kind="lines".	0.15
mean_width	float	Line width for the horizontal mean line.	2.0
mean_dash	str	Dash style for the mean line.	"dash"

Returns

Type	Description
Figure | dict[str, Figure]	Plotly figure for non-panel or single-member data. For panel data with multiple members, a dict keyed by member name.

Examples

>>> import polars as pl
>>> from yohou.plotting import plot_subseasonality

>>> # Create sample time series
>>> df = pl.DataFrame({
...     "time": pl.date_range(pl.date(2020, 1, 1), pl.date(2022, 12, 31), "1d", eager=True),
...     "y": [100 + (i % 30) + (i // 30) * 5 for i in range(1096)],
... })

>>> # Plot monthly subseries
>>> fig = plot_subseasonality(df, columns="y", seasonality="month")
>>> len(fig.data) > 0
True

See Also

plot_seasonality : Plot seasonal overlay. plot_time_series : Plot basic time series.

Source Code

View on GitHub

Show/Hide source

def plot_subseasonality(
    df: pl.DataFrame,
    *,
    columns: str | list[str] | None = None,
    seasonality: str = "month",
    kind: Literal["mean", "lines", "box", "violin"] = "mean",
    show_mean: bool = True,
    groups: list[str] | None = None,
    facet_n_cols: int = 4,
    color_palette: list[str] | None = None,
    title: str | None = None,
    x_label: str | None = None,
    y_label: str | None = None,
    width: int | None = None,
    height: int | None = None,
    connect_gaps: bool = False,
    show_legend: bool = True,
    resampler: bool | Literal["widget"] | None = None,
    line_width: float = 2.0,
    marker_size: float = 4,
    marker_opacity: float = 0.8,
    overlay_opacity: float = 0.15,
    mean_width: float = 2.0,
    mean_dash: str = "dash",
) -> go.Figure | dict[str, go.Figure]:
    """Plot seasonal subseries.

    Creates one mini subplot per season (e.g. 12 for months, 4 for quarters).
    Within each subplot the values for that season across all cycles are
    connected chronologically, with an optional horizontal mean line.  This
    view highlights both the *level* differences between seasons and any
    *trends within* each season over time.

    For panel data, returns one figure per member with groups overlaid by
    colour.  When only a single member exists, a plain ``go.Figure`` is
    returned instead of a dict.

    Parameters
    ----------
    df : pl.DataFrame
        Input DataFrame with 'time' column and numeric columns.
    columns : str | list[str] | None, default=None
        Column(s) to plot. If None, uses all numeric columns except 'time'.
    seasonality : str, default="month"
        Seasonal frequency: "month", "quarter", "weekday", "week", "hour".
    kind : {"mean", "lines", "box", "violin"}, default="mean"
        Visualization style within each season subplot:

        - ``"mean"`` - aggregated mean-per-cycle line with markers (default).
        - ``"lines"`` - one thin line per cycle at *overlay_opacity*, with
          the mean line overlaid on top.
        - ``"box"`` - one box per cycle showing value distribution.
        - ``"violin"`` - one violin per cycle showing value distribution.
    show_mean : bool, default=True
        Show a horizontal mean line within each season subplot.
    groups : list[str] | None, default=None
        Panel group prefixes to plot.
    facet_n_cols : int, default=4
        Number of columns in the subplot grid.
    color_palette : list[str] | None, default=None
        Custom color palette (one color per group).
    title : str | None, default=None
        Plot title.
    x_label : str | None, default=None
        X-axis label.
    y_label : str | None, default=None
        Y-axis label.
    width : int | None, default=None
        Plot width in pixels.
    height : int | None, default=None
        Plot height in pixels.
    connect_gaps : bool, default=False
        If True, connect lines across missing data gaps.
    show_legend : bool, default=True
        Whether to display the legend.
    resampler : bool | Literal["widget"] | None, default=None
        Enable plotly-resampler for large datasets.  ``True`` returns a
        ``FigureResampler``, ``"widget"`` a ``FigureWidgetResampler``,
        ``None`` reads from `get_config`.
    line_width : float, default=2.0
        Line width for cycle traces.
    marker_size : float, default=4
        Marker size for data points.
    marker_opacity : float, default=0.8
        Opacity of scatter markers.
    overlay_opacity : float, default=0.15
        Opacity of per-cycle lines when ``kind="lines"``.
    mean_width : float, default=2.0
        Line width for the horizontal mean line.
    mean_dash : str, default="dash"
        Dash style for the mean line.

    Returns
    -------
    go.Figure | dict[str, go.Figure]
        Plotly figure for non-panel or single-member data.  For panel
        data with multiple members, a dict keyed by member name.

    Examples
    --------
    >>> import polars as pl
    >>> from yohou.plotting import plot_subseasonality

    >>> # Create sample time series
    >>> df = pl.DataFrame({
    ...     "time": pl.date_range(pl.date(2020, 1, 1), pl.date(2022, 12, 31), "1d", eager=True),
    ...     "y": [100 + (i % 30) + (i // 30) * 5 for i in range(1096)],
    ... })

    >>> # Plot monthly subseries
    >>> fig = plot_subseasonality(df, columns="y", seasonality="month")
    >>> len(fig.data) > 0
    True

    See Also
    --------
    [`plot_seasonality`][yohou.plotting.plot_seasonality] : Plot seasonal overlay.
    [`plot_time_series`][yohou.plotting.plot_time_series] : Plot basic time series.
    """
    validate_plotting_data(df, min_rows=2)
    validate_plotting_params(
        kind=kind,
        valid_kinds={"mean", "lines", "box", "violin"},
        width=width,
        height=height,
    )

    if _auto_detect_panel(df) and groups is None and columns is None:
        groups = []

    if groups is not None:
        plot_columns = resolve_panel_columns(df, groups, columns)
    else:
        plot_columns = validate_plotting_data(df, columns=columns, exclude=["time"])
    df_aug = _add_season_and_cycle(df, seasonality)
    seasons = sorted(df_aug["season"].unique().to_list())
    season_labels = _SEASON_LABELS_MAP.get(seasonality)

    n_seasons = len(seasons)
    nrow = math.ceil(n_seasons / facet_n_cols)

    # Build per-subplot titles
    subplot_titles: list[str] = []
    for s in seasons:
        if season_labels and 1 <= s <= len(season_labels):
            subplot_titles.append(season_labels[s - 1])
        else:
            subplot_titles.append(str(s))

    if groups is not None:
        from yohou.plotting._utils import _group_panel_columns  # noqa: PLC0415

        grouped, all_members = _group_panel_columns(plot_columns)

        # Build one figure per member, groups overlaid by colour.
        figures: dict[str, go.Figure] = {}

        for member in all_members:
            color_mgr = PanelColorManager(color_palette)
            legend_tracker = LegendTracker(show_legend=show_legend)

            mfig = _create_subplots(
                resampler,
                rows=nrow,
                cols=facet_n_cols,
                subplot_titles=subplot_titles,
                shared_yaxes=True,
                vertical_spacing=max(0.04, 0.3 / nrow),
            )

            for si, season_val in enumerate(seasons):
                r = si // facet_n_cols + 1
                c_pos = si % facet_n_cols + 1
                season_df = df_aug.filter(pl.col("season") == season_val)

                for gname, group_cols in grouped.items():
                    # Find this member's column within the group.
                    col_name = next(
                        (c for c in group_cols if _member_name(c) == member),
                        None,
                    )
                    if col_name is None or col_name not in season_df.columns:
                        continue

                    display_name = gname
                    col_color = color_mgr.get_color(gname)

                    lines_info = None
                    if kind != "mean":
                        lines_info = _add_kind_traces(
                            mfig,
                            kind=kind,
                            season_df=season_df,
                            col_name=col_name,
                            display_name=display_name,
                            col_color=col_color,
                            overlay_opacity=overlay_opacity,
                            line_width=line_width,
                            row=r,
                            col=c_pos,
                            legend_tracker=legend_tracker,
                        )

                    if kind in ("mean", "lines"):
                        agg_df = season_df.group_by("cycle").agg(pl.col(col_name).mean()).sort("cycle")
                        cycles = agg_df["cycle"].to_list()
                        values = agg_df[col_name].to_list()
                        if not cycles:
                            continue

                        if lines_info is not None:
                            x_vals = lines_info["midpoints"]
                            x_mean_range = [0.0, lines_info["total"][0]]
                        else:
                            x_vals = cycles
                            x_mean_range = [cycles[0], cycles[-1]]

                        mfig.add_trace(
                            go.Scatter(
                                x=x_vals,
                                y=values,
                                mode="lines+markers",
                                line={"color": col_color, "width": line_width},
                                marker={"size": marker_size, "opacity": marker_opacity},
                                connectgaps=connect_gaps,
                                hovertemplate=_make_hovertemplate(
                                    display_name,
                                    "Cycle",
                                    "Value",
                                ),
                                name=display_name,
                                legendgroup=display_name,
                                showlegend=legend_tracker.should_show(display_name),
                            ),
                            row=r,
                            col=c_pos,
                        )

                        if show_mean:
                            mean_val = agg_df[col_name].mean()
                            if mean_val is not None and len(cycles) >= 2:
                                mfig.add_trace(
                                    go.Scatter(
                                        x=x_mean_range,
                                        y=[mean_val, mean_val],
                                        mode="lines",
                                        line={
                                            "color": col_color,
                                            "width": mean_width,
                                            "dash": mean_dash,
                                        },
                                        name=f"Mean ({display_name})",
                                        legendgroup=display_name,
                                        showlegend=False,
                                        hovertemplate=f"Mean: {mean_val:.2f}<extra></extra>",
                                    ),
                                    row=r,
                                    col=c_pos,
                                )

            mfig = apply_default_layout(
                mfig,
                title=title or f"Seasonal Subseries - {member}",
                x_label=x_label,
                y_label=y_label,
                width=width,
                height=height if height is not None else max(450, nrow * 280),
            )
            mfig.update_layout(showlegend=show_legend)
            figures[member] = mfig

        if len(figures) == 1:
            return next(iter(figures.values()))
        return figures

    # Non-panel path
    fig = _create_subplots(
        resampler,
        rows=nrow,
        cols=facet_n_cols,
        subplot_titles=subplot_titles,
        shared_yaxes=True,
        vertical_spacing=max(0.04, 0.3 / nrow),
    )

    colors = resolve_color_palette(color_palette, len(plot_columns))
    legend_tracker = LegendTracker(show_legend=show_legend)

    for si, season_val in enumerate(seasons):
        r = si // facet_n_cols + 1
        c = si % facet_n_cols + 1
        season_df = df_aug.filter(pl.col("season") == season_val)

        for ci, col_name in enumerate(plot_columns):
            col_color = colors[ci % len(colors)]

            lines_info = None
            if kind != "mean":
                lines_info = _add_kind_traces(
                    fig,
                    kind=kind,
                    season_df=season_df,
                    col_name=col_name,
                    display_name=col_name,
                    col_color=col_color,
                    overlay_opacity=overlay_opacity,
                    line_width=line_width,
                    row=r,
                    col=c,
                    legend_tracker=legend_tracker,
                )

            if kind in ("mean", "lines"):
                agg_df = season_df.group_by("cycle").agg(pl.col(col_name).mean()).sort("cycle")
                cycles = agg_df["cycle"].to_list()
                values = agg_df[col_name].to_list()
                if not cycles:
                    continue

                # When kind="lines", remap x-values to the numeric axis.
                if lines_info is not None:
                    x_vals = lines_info["midpoints"]
                    x_mean_range = [0.0, lines_info["total"][0]]
                else:
                    x_vals = cycles
                    x_mean_range = [cycles[0], cycles[-1]]

                fig.add_trace(
                    go.Scatter(
                        x=x_vals,
                        y=values,
                        mode="lines+markers",
                        line={"color": col_color, "width": line_width},
                        marker={"size": marker_size, "opacity": marker_opacity},
                        connectgaps=connect_gaps,
                        hovertemplate=_make_hovertemplate(col_name, "Cycle", "Value"),
                        name=col_name,
                        legendgroup=col_name,
                        showlegend=legend_tracker.should_show(col_name),
                    ),
                    row=r,
                    col=c,
                )

                if show_mean:
                    mean_val = agg_df[col_name].mean()
                    if mean_val is not None and len(cycles) >= 2:
                        fig.add_trace(
                            go.Scatter(
                                x=x_mean_range,
                                y=[mean_val, mean_val],
                                mode="lines",
                                line={
                                    "color": col_color,
                                    "width": mean_width,
                                    "dash": mean_dash,
                                },
                                name=f"Mean ({col_name})",
                                legendgroup=col_name,
                                showlegend=False,
                                hovertemplate=f"Mean: {mean_val:.2f}<extra></extra>",
                            ),
                            row=r,
                            col=c,
                        )

    fig = apply_default_layout(
        fig,
        title=title or "Seasonal Subseries",
        x_label=x_label,
        y_label=y_label,
        width=width,
        height=height if height is not None else max(450, nrow * 280),
    )
    fig.update_layout(showlegend=show_legend)

    return fig

Tutorials

The following example notebooks use this component:

• Exploratory Visualization

  ---

  Visualization

  Exploratory time series visualisation with raw series plots, rolling statistics overlays, seasonal overlays, subseries diagnostics, distribution boxplots, missing data pattern auditing, outlier detection, and resampling comparison.

  View · Open in marimo

• Seasonal Analysis

  ---

  Visualization

  Seasonal overlays, subseasonal structure, ACF/PACF correlation patterns, and STL decomposition for monthly, quarterly, and long-cycle datasets.

  View · Open in marimo