_assess Module (Internal)

This internal module provides the Analyser class, designed to encapsulate methods for assessing and visualising the results of a fitted Abacus Marketing Mix Model.

Analyser Class

class Analyser:
    """
    Provides methods for analyzing and visualizing MMM results.
    """

This class takes the model configuration, processed data, fitted model instance, and results directory as inputs and offers methods to generate various diagnostic plots and metrics.

Initialization

    def __init__(
        self,
        config: dict,
        processed_data: pd.DataFrame,
        input_data: Any, # Type depends on prepro output
        data_to_fit: Any, # Type depends on prepro output
        model: Any, # Typically DelayedSaturatedMMM
        results_dir: str
    ) -> None:

Initialises the Analyser instance.

Parameters:

  • config (dict): The configuration dictionary used for the model run.

  • processed_data (pd.DataFrame): The DataFrame containing the processed data used for training/testing.

  • input_data (Any): The InputData object (from abacus.prepro).

  • data_to_fit (Any): The DataToFit object (from abacus.prepro).

  • model (Any): The fitted Abacus MMM instance (e.g., DelayedSaturatedMMM).

  • results_dir (str): The path to the directory where results are stored.

Methods

split_data

    def split_data(self) -> tuple:

Splits the processed_data into training and testing sets based on the ratio defined in the config. Uses abacus.prepro.prepro.split_data.

Returns:

  • tuple: Contains (X, y, X_train, y_train, X_test, y_test).

plot_model_structure

    def plot_model_structure(self) -> Any: # graphviz.Digraph

Generates a graphviz visualisation of the underlying PyMC model structure using pymc.model_to_graphviz.

Returns:

  • graphviz.Digraph: The model structure graph.

plot_model_trace

    def plot_model_trace(self) -> plt.Figure:

Plots the trace diagnostics (posterior distributions and chain history) for key model parameters (intercept, likelihood_sigma, beta_channel, alpha, lam, gamma_control) using arviz.plot_trace.

Returns:

  • matplotlib.figure.Figure: The figure containing the trace plot.

predict

    def predict(self, dataset: pd.DataFrame) -> Any: # xr.DataArray

Generates posterior predictive samples for a given input dataset using the model’s sample_posterior_predictive method. Includes handling for adstock carry-over.

Parameters:

  • dataset (pd.DataFrame): The input features (X) for which to generate predictions.

Returns:

  • xr.DataArray or Any: Posterior predictive samples.

display_image

    def display_image(self, image_filename: str) -> Any: # IPython.display.Image

Displays an image file located within the results_dir. Requires IPython.

Parameters:

  • image_filename (str): The name of the image file.

Returns:

  • IPython.core.display.Image: The image object for display in environments like Jupyter.

calculate_r_squared

    def calculate_r_squared(self, x_dataset: pd.DataFrame, y_dataset: pd.Series) -> float:

Calculates the R-squared metric by comparing the model’s mean posterior predictions for x_dataset against the actual y_dataset.

Parameters:

  • x_dataset (pd.DataFrame): Input features.

  • y_dataset (pd.Series): Actual target values.

Returns:

  • float: The calculated R-squared value.

plot_posterior_predictive

    def plot_posterior_predictive(self, x_dataset: pd.DataFrame, y_dataset: pd.Series) -> plt.Figure:

Plots the posterior predictive check for a given dataset. Uses the model’s plot_posterior_predictive method and adds the calculated R-squared value to the title.

Parameters:

  • x_dataset (pd.DataFrame): Input features.

  • y_dataset (pd.Series): Actual target values.

Returns:

  • matplotlib.figure.Figure: The figure containing the posterior predictive plot.

plot_components_contributions

    def plot_components_contributions(self) -> plt.Figure:

Plots the contribution of each model component over time using the model’s plot_components_contributions method.

Returns:

  • matplotlib.figure.Figure: The figure containing the component contributions plot.

plot_posterior_predictions

    def plot_posterior_predictions(self) -> plt.Figure:

Plots the in-sample (training) and out-of-sample (testing) posterior predictions against actual values using abacus.sketch.plot.plot_posterior_predictions. Requires the instance to have access to the split data (e.g., via self.split_data()).

Returns:

  • matplotlib.figure.Figure: The figure containing the posterior predictions plot.