HECTOR

Hierarchical Embedding for Ontology-guided Trajectory Recognition and Analysis of single-cell sequencing data

HECTOR packages the current HECTOR inference and trajectory analysis code as a research-preview Python distribution. The package source is under hector/.

Installation

On Linux or WSL2 with an NVIDIA graphics card:

pip install "hector-sc[cuda12]"

On everything else — Mac, Windows, or Linux without an NVIDIA card:

pip install hector-sc

Either command installs the complete feature set; there are no other optional extras to choose from. HECTOR selects its inference backend automatically: TensorFlow on Linux, Windows, and Intel Macs, or MLX on Apple Silicon Macs.

The cuda12 extra adds TensorFlow's pip-managed NVIDIA CUDA runtime libraries, the prebuilt cupy-cuda12x wheel used for live VRAM measurement and CUDA memory-pool management, and the RAPIDS libraries cuml-cu12 and cugraph-cu12, which accelerate reduce_dimensions() and evaluate_cells(). Every package in the extra is gated to Linux, so on Mac and Windows the bracketed form installs nothing extra and is equivalent to the plain command.

Model Checkpoints

The packaged registry exposes two model entries hosted in Hugging Face repo polligator/HECTOR. Access to the hosted checkpoints is managed separately; authorized users can authenticate with Hugging Face before using a registry key.

• human -> file human.h5 (Homo sapiens)
• mouse -> file mouse.h5 (Mus musculus)

Basic usage:

import anndata
import hector

adata = anndata.read_h5ad("example_data.h5ad")
predictor = hector.HECTOR("human")
predictions = predictor.predict(adata)
predictor.write_predictions(adata, predictions)

Local checkpoint paths still work — pass a file path instead of a registry key:

import hector

predictor = hector.HECTOR("/path/to/your/checkpoint.h5")

Hardware Requirements

Inference runs on GPU by default (auto-batched to fit available VRAM) and falls back to CPU when no GPU is visible. Per-cell embeddings are deterministic: the same input on the same hardware and settings reproduces bit-identical results. Across different batch sizes, row orderings, or hardware, embeddings agree to within float32 rounding.

Numbers measured on the human checkpoint (57 M parameters; 100 000-cell × 5 000-gene anchor pool). Smaller anchor pools or fewer genes will reduce the footprint proportionally.

Package Layout

• hector/predictor.py: public predictor API and high-level inference workflows
• hector/predictor_support.py: internal model definitions, preprocessing, GRIT, and data utilities
• hector/trajectory.py: public trajectory configuration, analyzer orchestration, and shared layout/color helpers
• hector/trajectory_support.py: internal trajectory placement, ambiguity, clustering, and overlap helpers
• hector/trajectory_render.py: Plotly and matplotlib trajectory renderers
• hector/__init__.py: package exports plus model registry, cache, and download helpers

Citation

title: "Hierarchical Embedding for Ontology-guided Trajectory Recognition and Analysis"
authors: Junya Zhang
version: "0.1.0"
date-released: "2026-05-10"
license: "AGPL-3.0-only"
repository-code: "https://github.com/Polligator/HECTOR"

License

The source code is released under the GNU Affero General Public License v3.0. See LICENSE for details.

The project name, logo, icons, and related branding are not licensed under the AGPLv3. Modified versions should not use the project name or branding in a way that suggests they are official, endorsed by, or affiliated with the original project.

Contributions

External code contributions are not currently accepted.

Bug reports, reproducibility reports, installation issues, and feature suggestions are welcome through GitHub Issues.

This policy helps keep copyright ownership clear while the project is under active research and development.