Sketch: Depict (`depict.py`)

Purpose: high-level plotting/report helpers used by the V2 workflow.

Import

Preferred:

from sketch.depict import (
    describe_mmm_training,
    describe_mmm_prediction,
    describe_input_data,
    describe_config,
)

Compatibility:

from src.sketch.depict import (
    describe_mmm_training,
    describe_mmm_prediction,
    describe_input_data,
    describe_config,
)

Core Functions

describe_mmm_training(config, processed_data, mmm, results_dir)

Generates model-fit and decomposition summaries after training.

Primary artefacts:

• 20_model_fit/model_summary.csv
• 20_model_fit/model_priors_and_posteriors.png
• 40_decomposition/all_decomp.csv
• 40_decomposition/media_contribution_mean.png
• 40_decomposition/media_contribution_median.png
• 40_decomposition/weekly_media_contribution.png
• 40_decomposition/media_performance_mean.png
• 40_decomposition/media_performance_median.png
• 40_decomposition/performance_distribution.png
• 60_response_curves/response_curves.png

describe_mmm_prediction(config, input_data_processed, mmm, results_dir)

Generates predictive diagnostics and decomposition outputs for fitted models.

Primary artefacts:

• 30_model_assessment/model_fit_predictions.png
• 30_model_assessment/model_fit_metrics.csv
• 40_decomposition/waterfall_plot_components_decomposition.png
• 40_decomposition/media_performance_effect.csv
• 40_decomposition/media_channel_summary.csv
• Efficiency/cost outputs by target type:
  • revenue: media_contribution_per_spend.csv, media_cost_per_revenue_unit.csv
  • conversion: media_conversion_efficiency.csv, media_cost_per_conversion.csv

describe_input_data(input_data, results_dir, suffix)

Generates input-data overview plots.

Primary artefact:

• 10_pre_diagnostics/metrics_{suffix}.png

describe_config(output_dir, config, git_sha)

Persists run metadata.

Primary artefacts:

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

Notes

• Saving uses save_figure, save_csv, and save_text from utils.file_utils.
• Stage routing is automatic via stage constants from utils.file_utils.
• For convergence/calibration/Pareto-k diagnostic plots, see Diagnostics reference.