# `_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

```python
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

```python
    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`

```python
    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`

```python
    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`

```python
    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`

```python
    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`

```python
    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`

```python
    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`

```python
    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`

```python
    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`

```python
    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.