Metadata-Version: 2.4
Name: hector-sc
Version: 0.1.0
Summary: HECTOR single-cell inference and trajectory visualization package.
Author-email: Junya Zhang <polligator@outlook.com>
License-Expression: AGPL-3.0-or-later
Keywords: single-cell,cell type annotation,trajectory analysis,bioinformatics
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: <3.15,>=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: anndata>=0.10
Requires-Dist: gprofiler-official>=1.0
Requires-Dist: h5py>=3.10
Requires-Dist: huggingface-hub>=0.30
Requires-Dist: leidenalg>=0.10
Requires-Dist: matplotlib>=3.7
Requires-Dist: networkx>=3.0
Requires-Dist: numpy>=1.25
Requires-Dist: pandas>=2.0
Requires-Dist: psutil>=5.9
Requires-Dist: pyarrow>=14.0
Requires-Dist: plotly>=5.20
Requires-Dist: pynndescent>=0.5
Requires-Dist: python-igraph>=0.10
Requires-Dist: scanpy>=1.10
Requires-Dist: scikit-image>=0.22
Requires-Dist: scikit-learn>=1.3
Requires-Dist: scipy>=1.10
Requires-Dist: statsmodels>=0.14
Requires-Dist: tqdm>=4.66
Requires-Dist: tensorflow>=2.16; sys_platform != "darwin"
Requires-Dist: tensorflow>=2.16; sys_platform == "darwin" and platform_machine != "arm64"
Requires-Dist: mlx>=0.20; sys_platform == "darwin" and platform_machine == "arm64"
Provides-Extra: cuda12
Requires-Dist: tensorflow[and-cuda]>=2.16; sys_platform == "linux" and extra == "cuda12"
Requires-Dist: cupy-cuda12x>=13.0; sys_platform == "linux" and extra == "cuda12"
Requires-Dist: nvidia-ml-py>=12.0; sys_platform == "linux" and extra == "cuda12"
Requires-Dist: cuml-cu12>=24.10; sys_platform == "linux" and extra == "cuda12"
Requires-Dist: cugraph-cu12>=24.10; sys_platform == "linux" and extra == "cuda12"
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: hypothesis>=6.100; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: twine>=5.1; extra == "dev"
Requires-Dist: jupytext>=1.16; extra == "dev"
Requires-Dist: nbconvert>=7.0; extra == "dev"
Requires-Dist: ipykernel>=6.29; extra == "dev"
Dynamic: license-file

# 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:

```bash
pip install "hector-sc[cuda12]"
```

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

```bash
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:

```python
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:

```python
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.

|                        | requirement                                                                                                |
| ---------------------- | ---------------------------------------------------------------------------------------------------------- |
| GPU VRAM (minimum)     | **10 GB**. Batch size is auto-sized to fit the VRAM actually available; you do not set it.                  |
| GPU VRAM (recommended) | **16 GB** for comfortable headroom                                                                         |
| System RAM             | ~16 GB (model + 100k-cell anchor pool + working set)                                                       |
| CPU-only mode          | Feasible. ~3.6× slower than GPU. ~4 min for 100k cells, ~43 min for 1M cells on a typical workstation CPU. |

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

```yaml
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.
