HERA

[lerdmann1601]

HERA v1.2.1

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.1? (Minor Update)

This patch release improves the transparency and extensibility of the HERA ecosystem by including the complete deployment infrastructure within the toolbox. It also includes an important robustness improvement for ranking calculations.

Note: Since v1.2.1 is a fast-follow update, the features from v1.2.0 are included below to provide a complete overview of the recent upgrades.

📦 Enhanced Packaging

• Deployment Scripts Included: The MATLAB toolbox now includes all deploy/ scripts (e.g., build_HERA_matlab.m, build_HERA_python.m), allowing users to inspect the build process or recreate the standalone runtime, Python package and MATLAB toolbox locally.

🔧 Bug Fixes & Improvements

• Ranking Robustness: Added epsilon-based floating-point comparisons in calculate_ranking.m to prevent potential ranking instabilities caused by numerical precision errors when effect sizes are near zero.

---

Recent Features (from v1.2.0)

(For a full list of features, see the v1.2.0 Release Notes)

📈 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.

🐍 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.

Full Changelog: v1.2.0...v1.2.1

---

This discussion was created from the release HERA.