Guide: Running the Model

This guide explains the standard procedure for executing an Abacus MMM run using the provided driver script.

Primary Method: Using the Driver Script

The recommended way to run the model is via a driver script, such as the example provided in the demo/ directory (demo/runme.py). This script typically handles loading the configuration, preparing the data, initialising the model, fitting, and saving the results.

  1. Activate Environment: Ensure your Python virtual environment (venv_abacus) is activated:

    source venv_abacus/bin/activate

    (Use venv_abacus\Scripts\activate on Windows)

  2. Navigate: Make sure your terminal’s current working directory is the project root (/home/user/Desktop/ABACUS).

  3. Configure: Ensure your configuration YAML file (e.g., config.yaml) and input data CSV are correctly set up as described in the Configuration Guide and Data Preparation Guide. The driver script (e.g., demo/runme.py) will typically load these based on paths specified within the script or its associated configuration.

  4. Execute: Run the driver script as a Python module:

    # Example using the demo script
python -m demo.runme

    (Note: The specific driver script might take arguments, such as the path to the config file, but the demo script likely has these paths predefined within it. Check the script’s implementation if needed.)

  5. Monitor Output: Observe the console output. You should see:

    • Messages indicating data loading and preprocessing steps.

    • Progress bars from PyMC during the MCMC sampling (tune and draws phases).

    • Potential warnings from PyMC regarding sampling (e.g., divergences, low ESS, high R-hat) which should be investigated.

    • Messages indicating the generation and saving of results.

    • A completion message.

  6. Check Results: Once finished, find the output files (plots, CSVs, model.nc) in the specified results directory (often results/). Refer to the Interpreting Results Guide.

Other Methods (Advanced)

Directly instantiating and using the abacus.driver.driver.Driver class (or lower-level components like the model classes in abacus.core) in a custom Python script or notebook is possible for advanced users requiring more control. This approach bypasses the standard driver script logic. Refer to the source code and API documentation (if available) for details on the required class initialisation and method calls.