Depict (`sketch.depict`)

sketch.depict orchestrates high-level training and prediction summaries by calling lower-level plotting/helpers and saving artefacts via save_csv() / save_figure() / save_text() from utils.file_utils.

Model type used by this module is DelayedSaturatedMMMv2 (core.mmm_model_v2).

Import style:

from sketch.depict import describe_mmm_training, describe_mmm_prediction
# Compatibility form in some environments:
# from src.sketch.depict import describe_mmm_training, describe_mmm_prediction

describe_mmm_training(config, processed_data, mmm, results_dir)

Generates core training-time summaries and contribution plots.

Primary artefacts and stage folders:

• model_summary.csv → 20_model_fit/
• all_decomp.csv → 40_decomposition/
• media_contribution_mean.png → 40_decomposition/
• media_contribution_median.png → 40_decomposition/
• model_priors_and_posteriors.png → 20_model_fit/
• response_curves.png → 60_response_curves/
• weekly_media_contribution.png (via plot_channel_contributions) → 40_decomposition/
• media_performance_mean.png (via plot_roi) → 40_decomposition/
• media_performance_median.png (via plot_roi) → 40_decomposition/
• performance_distribution.png (via plot_roi_distribution) → 40_decomposition/

Note: all_contributions_plot is currently suppressed in code and does not persist weekly_media_and_baseline_contribution.png.

describe_mmm_prediction(config, input_data_processed, mmm, results_dir)

Generates prediction diagnostics and decomposition outputs for the train/test split.

Primary artefacts and stage folders:

• waterfall_plot_components_decomposition.png → 40_decomposition/
• model_fit_predictions.png (delegated to plot_posterior_predictions) → 30_model_assessment/
• model_fit_metrics.csv (from plot_posterior_predictions) → 30_model_assessment/
• media_performance_effect.csv → 40_decomposition/
• media_contribution_per_spend.csv or media_conversion_efficiency.csv → 40_decomposition/
• media_cost_per_revenue_unit.csv or media_cost_per_conversion.csv → 40_decomposition/
• media_channel_summary.csv → 40_decomposition/

describe_input_data(input_data, results_dir, suffix)

Writes input diagnostics and outlier reporting.

• metrics_{suffix}.png (via plot_all_metrics) → 10_pre_diagnostics/
• outlier report files are written by preprocessing utilities.

describe_config(output_dir, config, git_sha)

Writes run reproducibility text artefacts.

• git_sha.txt → 00_run_metadata/
• config.txt → 00_run_metadata/

Other helpers

Selected utility functions include:

• get_media_effect_df(model)
• compute_roi_summary(model, data, config)
• compute_cost_per_target_summary(model, data, config)
• quick_stats(model)
• weekly_spend_by_channel(model)

Usage example

from sketch.depict import describe_mmm_training, describe_mmm_prediction

describe_mmm_training(config, processed_data, mmm, results_dir)
describe_mmm_prediction(config, processed_data, mmm, results_dir)

Theme note: plotting theme is controlled by config['plot_theme'] ("dark" or default light theme).