Plot Results (`sketch.plot_results`)

This module provides decomposition and channel-performance plotting helpers.

It imports DelayedSaturatedMMMv2 as DelayedSaturatedMMM and saves artefacts with save_figure() / save_csv() to STAGE_DECOMPOSITION.

Import style:

from sketch.plot_results import (
    all_contributions_plot,
    plot_channel_contributions,
    plot_roi,
    plot_roi_distribution,
    plot_waterfall_components_decomposition,
)
# Compatibility form in some environments:
# from src.sketch.plot_results import ...

`all_contributions_plot(model, config, results_dir)`

Prepares baseline + channel contribution data.

Current status:

Baseline stacked-area persistence is suppressed in code (negative-baseline issue noted in TODO comments).
No plot file is currently saved by this function.

`plot_channel_contributions(model, config, results_dir)`

Plots channel-only stacked contributions over time.

Saved artefact:

weekly_media_contribution.png → 40_decomposition/

`plot_roi(model, data, config, results_dir)`

Plots mean and median ROI (or conversion efficiency, depending on target_type).

Saved artefacts:

media_performance_mean.png → 40_decomposition/
media_performance_median.png → 40_decomposition/

`plot_roi_distribution(model, data, config, results_dir)`

Plots ROI/efficiency distributions per channel.

Saved artefact:

performance_distribution.png → 40_decomposition/

`plot_waterfall_components_decomposition(model, ..., results_dir=None, mode="absolute")`

Builds component decomposition visualisation with two modes:

absolute: traditional cumulative waterfall.
incremental: variance-contribution bar chart.

Behaviour:

Returns a Matplotlib Figure.
If results_dir is provided, writes decomposition table CSV:
- waterfall_decomposition_data.csv → 40_decomposition/
Figure persistence is caller-managed in this function.

In the high-level pipeline (sketch.depict.describe_mmm_prediction), the returned figure is saved as:

waterfall_plot_components_decomposition.png → 40_decomposition/

Usage example

from sketch.plot_results import plot_channel_contributions, plot_waterfall_components_decomposition

plot_channel_contributions(model=mmm, config=config, results_dir=results_dir)

fig = plot_waterfall_components_decomposition(
    model=mmm,
    results_dir=results_dir,
    mode="absolute",
)