🔥 HMC-Torch

A Modular Platform for Hierarchical Multi-Label Classification with R-Matrix Constraints

HMC-Torch is a modular, extensible platform for Hierarchical Multi-Label Classification (HMC) that integrates the R-matrix constraint — originally proposed by Giunchiglia & Lukasiewicz (2018, NeurIPS) — as a reusable, first-class architectural component.

📄 Paper: HMC-Torch: A Modular Platform for Hierarchical Multi-Label Classification with R-Matrix Constraints (Bruno Sette, UFSCar, 2026)

✨ Key Features

• 🔌 Modular pipeline: DatasetAdapter → FeatureEncoder → HierarchicalHead → Calibrator → Reconciler
• 🧱 R-Matrix as infrastructure: reusable ancestor-closure constraint for training + inference
• 🌳 Explicit hierarchy modeling: Tree (FunCat) and DAG (Gene Ontology) with type-specific reconciliation
• 📊 25+ datasets across 5 domains: scientific text, genomics, email, microscopy, medical imaging
• 🧬 Multi-modal: tabular, text (transformers), protein sequences, images
• ⚡ GPU-accelerated: 14× training speedup
• 📦 Plugin system: register your own datasets without modifying the package
• 🔁 Reproducible: experiment manifests with git SHA, seeds, and dependency versions

📦 Installation

pip install hmc-torch

For optional features:

pip install "hmc-torch[vision]"      # Image models (timm)
pip install "hmc-torch[protein]"     # Protein models (fair-esm)
pip install "hmc-torch[expression]"  # Expression autoencoders

From source

git clone https://github.com/Sette/hmc-torch.git
cd hmc-torch
uv sync --all-groups
export PYTHONPATH=src

🚀 Quick Start

Python API

import hmc

# Train a global classifier with R-matrix constraint
results = hmc.train("wos", method="globalE2E", device="cuda", epochs=5)

# Train a tabular baseline
results = hmc.train("cellcycle_FUN", method="tabular_mlp", device="cuda", epochs=100)

CLI

# Frozen embeddings baseline
python -m hmc.main --dataset_name wos --method global --device cuda \
  --dataset_path ./data --output_path ./output

# Fine-tuned transformer (SOTA)
python -m hmc.main --dataset_name arxiv --method globalE2E --device cuda \
  --dataset_path ./data --epochs 50 --batch_size 32 --output_path ./output

# Tabular baseline
python -m hmc.main --dataset_name cellcycle_FUN --method tabular_mlp --device cuda \
  --dataset_path ./data --output_path ./output

🗂️ Supported Datasets

Built-in datasets (25+)

Register your own dataset

from hmc.data import DatasetRegistry, Split, DatasetBundle, Hierarchy

# Option 1: Programmatic registration
class MyDataset:
    def get_datasets(self):
        train = Split(features=X_train, labels=Y_train)
        test = Split(features=X_test, labels=Y_test)
        return train, None, test

    @property
    def hierarchy(self):
        return TreeHierarchy.from_edges([("root", "child1"), ...])

DatasetRegistry.register("my_data", lambda **kw: MyDataset(**kw))

# Option 2: Entry points (for packages)
# In your setup.cfg or pyproject.toml:
# [project.entry-points."hmc_torch.datasets"]
# my_data = "my_package:create_manager"

🧠 Methods

📊 Results

Text Benchmarks (Micro-F1)

🏆 New SOTA on ArXiv (+13.5 pts over HiAGM) and WOS (+0.2 pts over HTC-infoMAX)

FunCat Genomic Benchmarks (AUPRC)

🏆 Beats HMCN-F on seq_FUN (0.307 vs 0.291)

Gene Ontology (Block-Diagonal R-Matrix)

AUPRC improves on all 9 GO datasets (avg +0.0055) with zero hierarchy violations, using $O(N)$ memory instead of $O(N^2)$ (>1,400× reduction).

GPU Speedup

🧬 Architecture

DatasetAdapter  →  FeatureEncoder  →  HierarchicalHead  →  Calibrator  →  Reconciler
    ↓                    ↓                    ↓                ↓              ↓
DatasetBundle     fit/transform       GlobalSigmoidHead   Platt Scaling   Bottom-up
  + Hierarchy     (tabular, text,     LocalLevelHead      Temperature     max-prop
  + Splits         protein, vision)   TreePathHead

R-Matrix Constraint

The ancestor closure matrix $R_{ij} = 1$ iff class $i$ is an ancestor of $j$. Applied at:

1. Training: $\mathcal{L}_{\text{hier}} = \max(0, p_j - p_i + \gamma)$ for all ancestor pairs
2. Inference: $p_i^{\text{rec}} = \max(p_i, \max_{j: \text{child}(i,j)} p_j^{\text{rec}})$

Block-Diagonal R-Matrix (Sparse)

For large DAGs (4,000+ classes), the dense $R$ matrix requires $>65$ MB. Our sparse approximation uses graph traversal ($O(N+E)$ memory) with zero hierarchy violations.

📁 Project Structure

src/hmc/
├── data/              # Data contracts (DatasetBundle, Split, Hierarchy)
├── datasets/          # Built-in dataset implementations
│   ├── arxiv/         # ArXiv (JSONL + SPECTER2)
│   ├── wos/           # WOS (Web of Science)
│   ├── gofun/         # FunCat + GO (ARFF tabular)
│   ├── aapd/          # Arxiv Academic Paper Dataset
│   ├── rcv1/          # Reuters Corpus Volume 1
│   └── eurlex/        # EUR-Lex documents
├── features/          # Feature encoders (text, tabular, vision, protein)
├── models/            # HMC model components
│   ├── global_classifier/  # Global heads + R-matrix
│   ├── local_classifier/   # Per-level local heads
│   ├── hierarchical/       # Sparse R-matrix, label GCN
│   └── tabular/            # GBDT + MLP baselines
├── pipeline/          # Training pipelines
└── utils/             # Metrics, manifests, caching

🤝 Contributing

Contributions welcome! Areas we'd love help with:

• New dataset adapters
• Additional feature encoders (genomics, graphs)
• New hierarchical heads and reconciliation strategies
• Documentation and tutorials

git clone https://github.com/Sette/hmc-torch.git
cd hmc-torch
uv sync --all-groups
make test
make lint

📚 Citation

@article{sette2026hmctorch,
  title   = {HMC-Torch: A Modular Platform for Hierarchical Multi-Label
             Classification with R-Matrix Constraints},
  author  = {Bruno Sette},
  journal = {arXiv preprint},
  year    = {2026},
}

📄 License

MIT © Bruno Sette