diagnostics¶

This guide provides solutions and tips for common issues encountered while using the AMMM library.

Installation & Setup Issues¶

Missing Dependencies¶

Symptom: ModuleNotFoundError: No module named 'X' (e.g., No module named 'jinja2').
Solution: Ensure all dependencies listed in pyproject.toml (and optionally requirements-dev.txt for development/docs) are installed in your environment.
- Recommended (editable install):
```
pip install -e .
# Optional:
pip install -e .[dev]
pip install -e .[docs]
```
- If using the pinned requirements files:
```
pip install -r requirements.txt
# or for development/doc builds
pip install -r requirements-dev.txt
```

Unsupported Python version¶

Symptom: Installation or runtime errors on Python 3.13.
Cause: PyTensor compatibility issues on 3.13.

Solution: Use Python 3.10–3.12. On Windows, prefer Conda:

conda create -n ammm python=3.11 pip -y
conda activate ammm
conda install -c conda-forge prophet m2w64-toolchain -y
pip install -e .

Graphviz not installed¶

Symptom: Errors when plotting model structure: graphviz executables not found or blank structure plots.
Solution: Install Graphviz at the OS level (Python package alone is not sufficient):
Ubuntu/Debian: sudo apt-get install graphviz
macOS: brew install graphviz
Windows: use Conda (conda install -c conda-forge graphviz) or install from graphviz.org and add to PATH.

Cache Management¶

AMMM Cache CLI (Recommended)¶

AMMM ships a dedicated CLI to inspect and manage compilation caches used during modelling.

# Show cache statistics (use --verbose for details)
ammm-cache info

# Prune caches using defaults (max size 5GB, max 50 caches, max age 30 days)
ammm-cache prune

# Prune to a specific size (e.g., 3GB)
ammm-cache prune --max-size 3000

# Clear all caches (with confirmation prompt)
ammm-cache clear

# Use a custom cache root if needed
ammm-cache info --cache-root ~/.ammm/compiled

Default cache root: ~/.ammm/compiled.

Configuration Validation Errors¶

Silent Configuration Failures (Historical Issue)¶

Symptom: Custom prior parameters (e.g., saturation_beta) appear to be ignored, and the model uses default values without warning.
Cause: Prior to version 2.3, the system would silently ignore unrecognized parameter names.
Solution: Version 2.3+ includes a configuration validation system that:
- Validates all parameter names
- Supports user-friendly aliases (e.g., saturation_beta → lam)
- Provides helpful error messages with typo suggestions
- Fails fast with clear errors instead of silent fallbacks

Configuration Parameter Name Errors¶

Symptom: ValueError: Invalid parameter 'saturaton_beta'. Did you mean 'saturation_beta'?
Cause: Typo in parameter name or using an unrecognized parameter.
Solution:
- Check the spelling of your parameter names
- Refer to the Configuration Reference for valid parameter names and aliases
- Use the suggested correction if provided

Invalid Distribution Errors¶

Symptom: ValueError: Invalid distribution 'Norml'. Did you mean 'Normal'?
Cause: Typo in distribution name or using an unsupported distribution.
Solution:
- Check the spelling of distribution names
- Use PyMC distribution names exactly as documented
- Common distributions: Normal, HalfNormal, Beta, Gamma, Laplace, LogNormal

Missing Distribution Arguments¶

Symptom: ValueError: Distribution 'Beta' requires arguments: alpha, beta
Cause: Required arguments for a distribution are missing in the kwargs section.
Solution:
- Check PyMC documentation for required arguments for each distribution
- Ensure all required arguments are provided in the kwargs dictionary

Data Input & Preprocessing Errors¶

`FileNotFoundError` during data loading¶

Symptom: FileNotFoundError when demo/runme.py or other scripts try to load input data (e.g., gcol.csv, demo_data.csv).
Solution:
- Verify that the specified file paths in your configuration (demo_config.yml) or script are correct relative to the execution directory.
- Ensure the data files actually exist at the expected locations.

Issues with `StandardScaler` or `MaxAbsScaler`¶

Symptom: ValueError: Input contains NaN or ValueError: Input array is empty or TypeError: Input must be a pandas DataFrame or Series, or a NumPy array.
Cause: These errors were introduced as robustness checks in the custom scaler implementations (ammm/prepro/prepro.py).
Solution:
- Inspect your input data for NaN values before passing it to scalers.
- Ensure data passed to fit() or transform() is not empty.
- Ensure data is of the correct type (Pandas DataFrame/Series or NumPy array).

`pytest.raises` `match` parameter in tests¶

Symptom: Unit tests using pytest.raises with a match argument fail if the expected error message contains regex metacharacters (e.g., parentheses, brackets).
Solution: Regex-escape any special characters in the string passed to the match parameter. For example, \(, \[.

Model Fitting & Convergence Problems¶

`TypeError` or `AttributeError` during model building/fitting¶

Symptom: Various TypeError or AttributeError messages, often related to incorrect data types being passed to PyMC model components, or issues with how data is handled by mixins.
- Example: TypeError: Cannot interpret '...' as a data type if a PyMC distribution receives an unexpected input.
- Example: AttributeError if a mixin expects an attribute (e.g., self.idata) that hasn’t been set yet.
Debugging Steps:
- Carefully check the data types of all inputs to your model.
- Ensure data transformations (scaling, adstock, saturation) are applied correctly and consistently.
- Verify that the model fitting process (pm.sample()) is called only after the model is fully defined and data is correctly set.
- When debugging demo/runme.py, ensure that all necessary data attributes are available on the MMM instance before methods are called (e.g., X_train_transformed, y_train_transformed).

Arviz `plot_trace` x-axis rendering issue¶

Symptom: The x-axis labels for some variables (e.g., likelihood_sigma) in Arviz plot_trace may not render correctly or might be missing.
Status: This was noted as a minor visual issue and deferred. It typically does not affect the underlying sampling or model results.
Workaround: Focus on the numerical summaries and other diagnostic plots if this occurs.

Plotting & Visualization Issues¶

Placeholder Plots in `demo/runme.py`¶

Symptom: Some plots generated by demo/runme.py appear as empty figures with text like “Plot Disabled (Debugging)”.
Cause: During initial debugging of demo/runme.py (Phase 1.1), complex plotting functions within ContributionPlottingMixin, PredictivePlottingMixin, and ScenarioPlottingMixin were simplified to return placeholder matplotlib.figure.Figure objects to allow the main pipeline to run to completion.
Solution: Full plotting functionality is deferred to a later development phase. These placeholders confirm that the plotting methods are being called correctly within the pipeline.

`AttributeError` in plotting functions¶

Symptom: AttributeError when calling plotting functions, often related to missing data (e.g., fit_result not yet generated) or incorrect data structures being passed.
- Example: AttributeError: 'NoneType' object has no attribute 'posterior' if fit_result is None.
Solution: Ensure the model has been successfully fitted and the fit_result (or idata) attribute is populated before calling plotting methods that depend on it.

`KeyError` in plotting functions¶

Symptom: KeyError when plotting functions try to access specific variables from fit_result or other data structures.
- Example: KeyError: 'channel_contributions' if this variable is missing from the posterior samples.
Solution:
- Verify that the expected variables are present in your fit_result. This can be checked by inspecting idata.posterior.data_vars.
- Ensure variable names used in plotting code match those defined in the PyMC model.

Test Failures & Debugging Tests¶

Patching Issues in `pytest`¶

Symptom: Tests fail due to incorrect patching of modules or functions.
- Example: Patching ammm.core.utils.some_function when it’s imported as from ammm.core import utils and called as utils.some_function in the module under test. The patch target should be where the object is looked up, not where it’s defined.
Solution:
- Use autospec=True with mocker.patch or unittest.mock.patch to ensure the mock has the same signature as the original object.
- Be precise with patch targets. If a module a.b.c imports d.e.f and uses f(), you usually need to patch a.b.c.f, not d.e.f.
- For complex mocking scenarios, especially with chained calls or methods returning mocks, consider using side_effect with a custom function to control behaviour.

`AttributeError: 'NoneType' object has no attribute 'model'` in `tests/sketch/test_plot_diagnostics.py`¶

Symptom: test_plot_model_structure fails because the mocked model fixture doesn’t have a .model attribute that is an instance of pymc.Model.
Solution: Ensure the mock object assigned to mock_model_fixture.model is itself a MagicMock or an instance of the mocked type if type checking is involved.

Issues with `matplotlib.pyplot.style.context` in tests¶

Symptom: Tests for plotting functions fail if matplotlib.pyplot.style.context is mocked incorrectly or unnecessarily.
Solution: Often, this context manager does not need to be mocked for the test to pass, especially if the test is focused on data transformations or calls to other libraries like Arviz, rather than specific Matplotlib styling details. Consider removing the mock if it’s causing issues.

(More specific issues and solutions will be added as they are encountered and resolved.)