[Paper Review] HiClass: a Python library for local hierarchical classification compatible with scikit-learn

Fábio Malcher Miranda, Niklas Köhnecke+1 more|arXiv (Cornell University)|Dec 13, 2021

Machine Learning in Bioinformatics21 citations

TL;DR

HiClass is a scikit-learn-compatible Python library for local hierarchical classification, implementing node-level, parent-level, and level-level classifiers with support for hierarchical metrics. It enables training and prediction on tree- or DAG-structured data using flexible training policies, improving performance on hierarchical classification tasks compared to flat approaches.

ABSTRACT

HiClass is an open-source Python library for local hierarchical classification entirely compatible with scikit-learn. It contains implementations of the most common design patterns for hierarchical machine learning models found in the literature, that is, the local classifiers per node, per parent node and per level. Additionally, the package contains implementations of hierarchical metrics, which are more appropriate for evaluating classification performance on hierarchical data. The documentation includes installation and usage instructions, examples within tutorials and interactive notebooks, and a complete description of the API. HiClass is released under the simplified BSD license, encouraging its use in both academic and commercial environments. Source code and documentation are available at https://github.com/scikit-learn-contrib/hiclass.

Motivation & Objective

• To provide a unified, scikit-learn-compatible framework for local hierarchical classification in Python.
• To support multiple design patterns: local classifier per node, per parent node, and per level.
• To enable evaluation using hierarchical precision, recall, and F-score, which are more appropriate for hierarchical data.
• To support training with partial hierarchy and missing labels, enhancing real-world applicability.
• To offer extensibility via custom estimators and parallel training using Ray or Joblib.

Proposed method

• Uses scikit-learn’s BaseEstimator API for full compatibility with existing ML workflows and pipelines.
• Represents hierarchical labels as structured NumPy arrays of shape n_samples × n_levels, with empty strings for missing labels.
• Employs NetworkX to model hierarchical structures as directed acyclic graphs (DAGs), supporting both trees and complex hierarchies.
• Implements six training policies (e.g., Exclusive, Inclusive, Siblings) to define positive and negative examples for binary classifiers.
• Supports parallel training of local classifiers via Ray or Joblib, while prediction proceeds top-down to maintain consistency.
• Introduces hierarchical metrics: hP (precision), hR (recall), and hF (F-score), defined as extensions of standard metrics using ancestor-descendant set intersections.

Experimental results

Research questions

• RQ1 How can hierarchical classification be efficiently implemented in Python with full compatibility to the scikit-learn ecosystem?
• RQ2 What are the most effective training policies for local hierarchical classifiers, and how do they impact performance?
• RQ3 Can hierarchical evaluation metrics provide more meaningful performance insights than standard flat metrics on hierarchical data?
• RQ4 How does the library handle incomplete or partially known hierarchies during training and prediction?
• RQ5 To what extent can HiClass support diverse hierarchical structures, including DAGs, beyond simple trees?

Key findings

• HiClass enables training and prediction on hierarchical data using local classifiers per node, per parent, or per level, with consistent top-down prediction to preserve hierarchy.
• The library supports six distinct training policies for defining positive and negative examples, allowing flexibility in model design.
• Hierarchical metrics (hP, hR, hF) are shown to be more appropriate than flat metrics for evaluating hierarchical classification performance.
• Training can be accelerated via parallel execution using Ray or Joblib, with support for both binary and multi-class local classifiers.
• The library supports partial hierarchies and missing labels in outer levels, enhancing robustness in real-world scenarios with incomplete data.
• HiClass is released under the simplified BSD license, enabling broad use in academic and commercial applications.