Skip to content

Python Integration

A compiled interface allows HERA to be integrated directly into your Python data science pipelines. It wraps the underlying MATLAB functions and provides them as native objects.

Note

No MATLAB License Required: The Python interface operates entirely on the freely downloadable MATLAB Runtime provided by MathWorks. You do not need a MATLAB license, account, or commercial MATLAB software to use HERA in Python.

1. Installation (For End Users)

The easiest way to install the package is via pip from PyPI.

Step 1: Install Package

pip3 install hera-matlab

Step 2: Install MATLAB Runtime (Free Download)

HERA utilizes the free MATLAB Runtime R2025b (v25.2). No commercial license or MATLAB purchase is required. After installing the Python package, run the automated setup helper to check your system or obtain the official download link:

python3 -m hera_matlab.install_runtime

Follow the on-screen instructions provided by this helper to complete the free runtime setup if it is not already installed on your system.

Step 3: macOS Specifics (Critical)

On macOS, you cannot use the standard python interpreter to import the package, as it will likely fail with a library loading error. Instead, you must use the mwpython wrapper provided by the MATLAB Runtime.

Location of mwpython: Typically found at: /Applications/MATLAB/MATLAB_Runtime/R2025b/bin/mwpython

Usage: Instead of running python3 script.py, run:

/Applications/MATLAB/MATLAB_Runtime/R2025b/bin/mwpython script.py

You may want to add this to your PATH variable for easier access.

Warning

Python Version Compatibility: HERA (via MATLAB Runtime) currently supports Python 3.9, 3.10, 3.11, and 3.12. Python 3.13 is NOT supported.

If you have Python 3.13 installed, mwpython will fail to load your packages. Solution: Create and activate a Virtual Environment with Python 3.12 before running mwpython.

# Example using brew to install python 3.12
brew install python@3.12
/opt/homebrew/bin/python3.12 -m venv .venv_hera
source .venv_hera/bin/activate
pip3 install hera-matlab
# Now mwpython will automatically use this environment
mwpython script.py

2. Usage Modes

A. File- & Config-Based Analysis (Single Run or Automated Pipeline)

In this mode, HERA executes a complete analysis based on a JSON configuration file—whether for a single standalone analysis, automated batch processing, or server pipelines. It automatically generates all PDF reports, figures, and CSV/JSON output tables on disk without requiring interactive user prompts.

Note

The interactive command-line interface (CLI) prompt is not supported in the Python package. To run an analysis, either provide a JSON configuration file via hera.start_ranking('configFile', '...') or pass data directly as NumPy/Pandas structures via hera.run_ranking(config) (Mode B below).

import hera_matlab

# Initialize Runtime
hera = hera_matlab.initialize()

# Run with JSON configuration
# Outputs (PDFs, Images) will be saved to the 'output_dir' defined in the config
hera.start_ranking('configFile', 'analysis_config.json', nargout=0)

hera.terminate()

See Configuration & Parameters for a complete list of available options.

B. Direct Data Integration (NumPy/Pandas)

This mode allows you to use HERA as a computational engine within your Python scripts (e.g., Jupyter Notebooks). You can pass data directly from NumPy/Pandas and receive the ranking results as a Python dictionary, enabling seamless integration into larger data science pipelines.

Automatic Data Conversion (v1.2.0+)

Starting with version 1.2.0, the package includes a wrapper that performs bidirectional conversion:

  1. Input: Automatically converts NumPy arrays and Pandas DataFrames to the required MATLAB types.
  2. Output: Automatically converts returned MATLAB data (e.g., matlab.double) back into NumPy arrays for easy processing in Python.

This eliminates the need for manual conversion in both directions.

Important

Performance (v1.4.0+): Input conversion utilizes modern MATLAB direct buffer access (R2022a+). This avoids unnecessary Python list overhead.

import hera_matlab
import numpy as np

# Initialize
hera = hera_matlab.initialize()

# Option 1: Using NumPy Arrays
data_m1 = np.array([[0.1, 0.5], [0.2, 0.4]])
data_m2 = np.array([[1.0, 3.0], [1.2, 2.9]])

# (Option 2: Pandas DataFrames are also supported)

config = {
    'custom_data': [data_m1, data_m2],
    'metric_names': ['Runtime', 'Accuracy'],
    'dataset_names': ['Method A', 'Method B'],
    'ranking_mode': 'M1_M2',
    'output_dir': 'hera_numpy_results'
}

# The wrapper automatically converts the data before calling MATLAB
results = hera.run_ranking(config, nargout=1)

print(f"Final Ranks: {results['final_rank']}")

Note

Explicit termination (hera.terminate()) is optional in scripts, as the package handles cleanup automatically. However, it is recommended for interactive sessions (e.g., Jupyter) to free up resources immediately.

See Results Structure Reference for a complete list of available fields

3. Running the Test Suite

You can execute the internal HERA verification and test suite (Scientific, System, and Unit tests) directly from Python to ensure the installation is valid and mathematically correct. For more details on the test suite, see the Testing section in the main documentation.

import hera_matlab

# Initialize
hera = hera_matlab.initialize()

# Launch Test Mode
# Arguments: 'runtest', 'true'
# This will execute all tests and print the results to standard output/log files.
hera.start_ranking('runtest', 'true', nargout=0)

hera.terminate()

This is useful for verifying deployments on new machines (e.g., CI/CD).

4. Running Convergence Analysis

You can also trigger the robust convergence analysis directly from Python. This is identical to the MATLAB HERA.start_ranking('convergence', 'true') command. For more details on the analysis and its parameters, see Convergence Analysis.

import hera_matlab

# Initialize
hera = hera_matlab.initialize()

# Run Convergence Analysis
# Arguments: 'convergence', 'true'
# Optional: 'sims', 50 (for higher precision)
# Optional: 'logPath', '/path/to/log' (or 'interactive')
hera.start_ranking('convergence', 'true', nargout=0)

# Run with custom JSON configuration (Advanced)
# HERA will automatically load all parameters from the file
hera.start_ranking('convergence', 'analysis_config.json', nargout=0)

hera.terminate()

5. Build & Release Instructions (For Maintainers)

Important

This section is strictly for developers and maintainers who build and publish the Python package. End users do not need to build anything; they can install directly via pip install hera-matlab.

Prerequisites

  • MATLAB with the MATLAB Compiler SDK (which provides compiler.build.pythonPackage).
  • Python 3.9–3.12 with pip and the venv module installed locally.
  • A clean Git working directory with the appropriate release tag checked out (e.g., v1.4.7).

Step 1: Build Distribution Artifacts

The repository includes an automated build helper script that compiles the MATLAB code, injects metadata, and packages the Python distribution:

./deploy/build_and_prep_pypi.sh

Note

If the matlab command is not in your terminal PATH, open MATLAB, navigate to deploy/, and run build_hera_python(). Then execute ./deploy/build_and_prep_pypi.sh from your terminal).

What this script performs:

  1. Compilation: Calls build_hera_python.m to generate the raw Python package files in deploy/output/python.
  2. Metadata Injection: Executes .github/scripts/prepare_pypi.py to synchronize version numbers, insert license information, and inject the runtime setup helper (hera_matlab.install_runtime).
  3. Packaging: Creates an isolated virtual environment (.venv_build) and executes python3 -m build to produce clean distribution artifacts (.whl and .tar.gz) in deploy/dist/.

Step 2: Upload to GitHub Release

  1. On GitHub, navigate to Releases -> Draft a new release.
  2. Select or create the release tag corresponding to your build (e.g., v1.4.7).
  3. Upload the .whl and .tar.gz files from deploy/dist/ as release assets.
  4. Publish the release.

Step 3: Publish to PyPI via GitHub Actions

Since GitHub Actions runners cannot build MATLAB packages without a cloud license, PyPI publication uses PyPI Trusted Publishing to deploy the pre-built release assets:

  1. Go to the Actions tab in GitHub.
  2. Select the Publish to PyPI workflow in the sidebar.
  3. Click Run workflow, enter your Release Tag (e.g., v1.4.7), and submit.
  4. The workflow downloads the pre-built assets from your GitHub Release and securely uploads them directly to PyPI.

For further details on CI/CD architecture, see Automated Build (GitHub Actions).

Important

Release Scope & Policy

  • Full Suite Releases: Releases are not just for Python. A release MUST always include all artifacts: the MATLAB Toolbox (.mltbx), standalone executables, and the Python distribution.
  • Mandatory Review: All changes must be reviewed and approved by the repository owner before a release is prepared.
  • Compliance: Contributors must strictly follow the rules outlined in CODE_OF_CONDUCT.md and CONTRIBUTING.md.