HERA

[lerdmann1601]

HERA v1.2.0

HERA is a robust MATLAB toolbox designed for the scientific benchmarking of clustered data. It offers hierarchical-compensatory ranking logic, advanced effect-size statistics, and automated reporting capabilities.

🖥️ Platform Support

• MATLAB Toolbox & Python Package: Windows, macOS (Intel & Apple Silicon), Linux
• Standalone Application: macOS (Apple Silicon ONLY)

📦 Compatibility

• MATLAB: Compatible with R2024b and newer.
• Python: Requires Python 3.9 through 3.12. and Matlab Runtime R2025b (25.2).

📥 Installation

Option 1: MATLAB Toolbox

The easiest way to use HERA within MATLAB.

1. Download the HERA Toolbox (.mltbx) file.
2. Double-click the file or drag it into the MATLAB Command Window to install.
3. Access HERA functions directly (e.g., HERA.start_ranking).

Option 2: Python Package

Integrate HERA into your Python data science pipelines.

1. Install the MATLAB Runtime R2025b (25.2) from the MathWorks Website.
2. Run pip3 install hera-matlab.
3. Import via import hera_matlab.

Option 3: Standalone Application

Supported Platform: macOS (Apple Silicon)
No MATLAB license required.

1. Download and extract the standalone installer ZIP.
2. Run the Installer (HERA_Runtime_Installer_...) to set up the application and automatically download the MATLAB Runtime.
3. Start the application using the HERA_Launcher.

Important Note for macOS Users:
Due to macOS security protocols for software distributed outside the App Store, you may need to manually authorize the
application twice: once for the Installer and once for the Launcher.

Option 1
If macOS prevents the file from opening ("App is damaged" or "Unidentified Developer"):

1. Right-click the file (Installer or Launcher) and select Open.
2. Attempt to open it. If it still fails:
3. Go to System Settings -> Privacy & Security.
4. Scroll down to the Security section.
5. Click Open Anyway (or "Allow") for the blocked application.
6. Confirm by clicking Open.
   Repeat these steps for both the Installer and the Launcher if prompted (might be every time you want to use it).

Option 2: Permanent Fix
This removes all security warnings for HERA permanently by clearing the quarantine attributes.

1. Open the Terminal app (Press Cmd + Space, type "Terminal", and press Enter).
2. Type sudo xattr -cr (make sure there is a space at the end).
3. Drag and drop the entire extracted HERA_Runtime_... folder from Finder into the Terminal window or copy and paste the folder path.
4. Press Enter.
5. Type your login password if prompted (typing will be invisible) and press Enter.
6. Open the Terminal app (Press Cmd + Space, type "Terminal", and press Enter).
7. Type sudo xattr -cr (make sure there is a space at the end).
8. Drag and drop the entire extracted HERA_Runtime_... folder from Finder into the Terminal window or copy and paste the folder path.
9. Press Enter.
10. Type your login password if prompted (typing will be invisible) and press Enter.
11. Now you can double-click the Installer and Launcher without issues.

Disclaimer: This software and the associated instructions are provided "as is", without warranty of any kind. The author expressly disclaim all liability for any damages, errors, or security risks arising from the use of this software or the execution of system commands. Modifying file attributes skips Apple's security checks; proceed at your own risk.

🚀 Key Features

• Hierarchical-Compensatory Logic: A multi-tier ranking system where primary metrics set the baseline, while secondary metrics can actively correct or swap ranks if a lower-ranked method significantly outperforms a higher-ranked one.
• Effect-Size Driven Decisions: Moves beyond simple p-values by enforcing practical significance thresholds (Cliff's Delta, Relative Difference) dynamically calculated via Percentile Bootstrapping and BCa Confidence Intervals to ensure results are robust against outliers and small sample sizes.
• Robust Rank Stability: Ensures reliable benchmarking results through rigorous Cluster Bootstrapping preventing rankings driven by outliers or noise.
• Python Integration: Seamlessly call HERA from Python using NumPy/Pandas data structures.
• Automated Reporting: PDF reports, Sankey diagrams, and Win-Loss matrices.

What's New in v1.2.0? (Feature & Stability Release)

This release introduces significant new modules for scientific validation ("Convergence Analysis") and massively improves the Python experience with smart type conversion.

📈 Scientific Validation: Convergence Analysis

• New Module: Added a dedicated Convergence Analysis mode (HERA.start_ranking('convergence', 'true')) to validate the stability of default robust convergence parameters.
• Simulation: Implements simulation loops to analyze how ranking, threshold and BCa confidence interval stability changes with different sample sizes and data distribution scenarios.
• Reporting: Automatically generates detailed CSV logs and plots visualization of convergence behavior.

🐍 Python Integration 2.0

• Smart Type Conversion: The Python wrapper now automatically detects and converts NumPy arrays and Pandas DataFrames/Series into MATLAB-compatible types. You can now pass your data directly to HERA without manual formatting!
• Type Stubs (.pyi): Added type hinting files to provide better autocompletion and static analysis support in basic Python IDEs.
• Return Values: Improved handling of return values, ensuring that MATLAB results are converted back to Python-friendly formats where possible.

📚 Documentation & Usability

• GitHub Pages: Converted all documentation links to point directly to the GitHub Pages site for a better reading experience.
• Contents.m: Added a standard MATLAB Contents.m file for better help integration within the MATLAB environment.
• Documentation Overhaul: Updated README, Example_Analysis, and other guides to match the new version and folder structure.

🛠 Build & Workflow

• Cleaner Builds: Improved build scripts (build_HERA_...) to automatically remove temporary files (__pycache__, .DS_Store) for smaller, cleaner distribution packages.
• Zenodo DOI: Updated documentation and citation files to use the persistent Zenodo DOI, ensuring stable referencing across all versions.

Full Changelog: v1.1.2...v1.2.0

---

This discussion was created from the release HERA.