`_depict` Module (Internal)¶

This internal module provides helper functions primarily focused on calculating and summarizing key performance indicators (KPIs) like media effect, ROI, and cost per target from the posterior distributions of a fitted Lightweight Marketing Mix Model (LMMM). It also includes functions to orchestrate the generation and saving of various diagnostic plots and summary files related to model training and prediction.

Functions

get_lmmm_media_effect_df

def get_lmmm_media_effect_df(
    data_to_fit: DataToFit, media_effect_hat: np.ndarray
) -> pd.DataFrame:

Calculates summary statistics (5th percentile, 95th percentile, median, mean) for the media contribution percentage (media effect) for each channel and a blended overall effect.

Parameters:

data_to_fit (DataToFit): The DataToFit object containing processed data and metadata (like media names).
media_effect_hat (np.ndarray): A 2D NumPy array containing posterior samples of the media effect (contribution percentage) per channel. Shape: [sample, channel].

Returns:

pd.DataFrame: A DataFrame indexed by media channel names (plus “blended”), with columns “0.05”, “0.95”, “median”, “mean” representing the summary statistics of the media effect distribution.

get_lmmm_roi_df

def get_lmmm_roi_df(
    data_to_fit: DataToFit, media_effect_hat: np.ndarray, roi_hat: np.ndarray
) -> pd.DataFrame:

Calculates summary statistics (5th percentile, 95th percentile, median, mean) for the Return on Investment (ROI) for each channel and a blended overall ROI.

Parameters:

data_to_fit (DataToFit): The DataToFit object containing processed data and metadata. Used for calculating the blended ROI.
media_effect_hat (np.ndarray): A 2D NumPy array containing posterior samples of the media effect. Shape: [sample, channel]. Used for calculating blended ROI.
roi_hat (np.ndarray): A 2D NumPy array containing posterior samples of the ROI per channel. Shape: [sample, channel].

Returns:

pd.DataFrame: A DataFrame indexed by media channel names (plus “blended”), with columns “0.05”, “0.95”, “median”, “mean” representing the summary statistics of the ROI distribution.

get_cost_per_target_df

def get_cost_per_target_df(
    data_to_fit: DataToFit,
    media_effect_hat: np.ndarray,
    roi_hat: np.ndarray,
    cost_per_target_hat: np.ndarray,
) -> pd.DataFrame:

Calculates summary statistics (5th percentile, 95th percentile, median, mean) for the Cost Per Target (CPT) for each channel and a blended overall CPT.

Parameters:

data_to_fit (DataToFit): The DataToFit object containing processed data and metadata. Used for calculating the blended CPT.
media_effect_hat (np.ndarray): A 2D NumPy array containing posterior samples of the media effect. Shape: [sample, channel]. Used for calculating blended CPT.
roi_hat (np.ndarray): A 2D NumPy array containing posterior samples of the ROI per channel. Shape: [sample, channel]. Used for calculating blended CPT.
cost_per_target_hat (np.ndarray): A 2D NumPy array containing posterior samples of the CPT per channel. Shape: [sample, channel].

Returns:

pd.DataFrame: A DataFrame indexed by media channel names (plus “blended”), with columns “0.05”, “0.95”, “median”, “mean” representing the summary statistics of the CPT distribution.

describe_lmmm_training

def describe_lmmm_training(
    mmm, input_data, data_to_fit, degrees_seasonality, results_dir, include_response_curves=True
):

Orchestrates the generation and saving of various diagnostic plots and summary files related to the MMM training process. It calls various plotting functions (likely from abacus.sketch._plot or similar modules) and saves the outputs to the specified results_dir.

Generated Outputs (Examples):

model_coefficients.txt: Summary of model parameters.
model_fit_in_sample.png: Plot showing model fit against training data.
model_media_posteriors.png: Plots of posterior distributions for media parameters.
response_curves_target.png (optional): Response curves showing target vs. spend.
response_curves_cost_per_target.png (optional): Response curves showing CPT vs. spend.
model_priors_and_posteriors.png: Comparison of prior and posterior distributions.
media_performance_effect.csv: CSV with media effect summary statistics.
media_performance_roi.csv: CSV with ROI summary statistics.
media_performance_cost_per_target.csv: CSV with CPT summary statistics.
media_contribution_mean.png/median.png: Bar plots of media contribution.
media_roi_mean.png/median.png: Bar plots of media ROI.
media_cost_per_target_mean.png/median.png: Bar plots of media CPT.
baseline_breakdown.csv: CSV detailing baseline components.
all_breakdown.csv: CSV detailing all model components.
weekly_media_and_baseline_contribution.png: Area plot showing contribution over time.

Parameters:

mmm: The fitted LightweightMMM model instance.
input_data (InputData): The original InputData object.
data_to_fit (DataToFit): The DataToFit object used for training.
degrees_seasonality (int): Degrees of seasonality used during fitting (likely for breakdown calculations).
results_dir (str): The directory path where output files will be saved.
include_response_curves (bool, optional): Whether to generate and save response curve plots (can be slow). Defaults to True.

Returns:

None: The function saves files to disk.

describe_lmmm_prediction

def describe_lmmm_prediction(mmm, data_to_fit, results_dir):

Generates and saves a plot comparing the model’s out-of-sample predictions against the actual target values from the test set.

Parameters:

mmm: The fitted LightweightMMM model instance.
data_to_fit (DataToFit): The DataToFit object containing the test data split (media_data_test_scaled, extra_features_test_scaled, target_test_scaled).
results_dir (str): The directory path where the output plot (model_fit_out_of_sample.png) will be saved.

Returns:

None: The function saves a plot file to disk.

(Note: This module also contains internal helper functions like _compute_blended_media_effect_hat, _compute_blended_roi_hat, and _compute_blended_cost_per_target_hat used for calculating the overall blended metrics. There is also a potentially duplicated/incomplete get_roi_df function at the end of the file.)

_depict Module (Internal)¶

`_depict` Module (Internal)¶