# Abacus Sketch: Plot Diagnostics (`plot_diagnostics.py`)

This module provides functions for generating diagnostic plots to evaluate the fitted Abacus Marketing Mix Model (MMM). These plots help assess model fit, convergence of the sampling algorithm, and the model's predictive capabilities.

::: abacus.sketch.plot_diagnostics

## Functions

### `plot_posterior_predictions`

```python
def plot_posterior_predictions(
    X: pd.DataFrame,
    y: pd.Series,
    X_test: pd.DataFrame,
    y_test: pd.Series,
    mmm, # Fitted MMM instance
    config: dict,
    output_dir: str,
    n_points: int = 52
) -> None:
```

Plots the model's posterior predictions against actual observed values for both in-sample and (if available) out-of-sample data.

This function generates a time series plot showing:
-   Actual observed target values (points).
-   Median posterior prediction (dashed line).
-   95% Highest Density Interval (HDI) of the posterior predictions (shaded area).

It plots the last `n_points` of the in-sample data and all available out-of-sample data. It also calculates and includes the R-squared values for both in-sample and out-of-sample predictions in the plot title.

**Parameters:**

-   `X` (`pd.DataFrame`): Full feature DataFrame (including date column).
-   `y` (`pd.Series`): Full target variable Series.
-   `X_test` (`pd.DataFrame`): Feature DataFrame for the test/out-of-sample period. Can be empty.
-   `y_test` (`pd.Series`): Target variable Series for the test/out-of-sample period. Can be empty.
-   `mmm`: The fitted Abacus MMM instance. Must have a `sample_posterior_predictive` method.
-   `config` (`dict`): Configuration dictionary (used for date and target column names).
-   `output_dir` (`str`): Directory where the plot (`model_fit_predictions.png`) will be saved.
-   `n_points` (`int`, optional): Number of recent in-sample data points to include in the plot. Defaults to 52.

**Returns:**

-   `None`: Saves the plot to the specified directory.

**Raises:**

-   `AttributeError`: If `mmm` lacks the `sample_posterior_predictive` method.
-   `ValueError`: If date columns are missing or have incorrect types.

---

### `plot_model_structure`

```python
def plot_model_structure(model) -> Optional['graphviz.Digraph']:
```

Generates a visual representation of the PyMC model structure using Graphviz.

Requires the `graphviz` library and its backend (e.g., the Graphviz executables) to be installed.

**Parameters:**

-   `model`: The fitted Abacus MMM instance containing the PyMC model object (expected at `model.model`).

**Returns:**

-   `graphviz.Digraph` or `None`: The Graphviz object representing the model graph if successful, otherwise `None` (e.g., if Graphviz is not installed).

---

### `plot_model_trace`

```python
def plot_model_trace(model, results_dir: str) -> None:
```

Generates trace plots for key model parameters using ArviZ's `plot_trace`.

Trace plots show the time series of samples for each parameter across all chains (left column) and the corresponding posterior density estimate (right column). They are essential for diagnosing MCMC convergence issues.

**Parameters:**

-   `model`: The fitted Abacus MMM instance containing the `idata` (InferenceData) attribute with posterior samples.
-   `results_dir` (`str`): Directory where the plot (`model_trace.png`) will be saved.

**Returns:**

-   `None`: Saves the plot to the specified directory.

**Raises:**

-   `AttributeError`: If `model` does not have an `idata` attribute.
-   `ValueError`: If `model.idata` is `None` or lacks posterior samples.

---

### `plot_posterior_distributions`

```python
def plot_posterior_distributions(
    idata: az.InferenceData,
    results_dir: str,
    filename: str = 'posterior_distributions.png'
) -> None:
```

Plots the marginal posterior distributions for all parameters found in the `posterior` group of the InferenceData object.

Uses ArviZ's `plot_posterior` function to create histograms or kernel density estimates for each parameter.

**Parameters:**

-   `idata` (`az.InferenceData`): The InferenceData object containing the posterior samples.
-   `results_dir` (`str`): Directory where the plot will be saved.
-   `filename` (`str`, optional): Name for the output PNG file. Defaults to `'posterior_distributions.png'`.

**Returns:**

-   `None`: Saves the plot to the specified directory.