Metadata-Version: 2.4
Name: hector-sc
Version: 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

HECTOR automatically selects an available inference backend and adjusts batch
sizes to the available memory. CPU inference is used where supported when no
accelerator is available. Results are expected to be numerically stable for
fixed inputs and settings, although small differences can occur across
hardware, backends, batch sizes, or row orderings.

| Resource | Guidance |
| --- | --- |
| GPU VRAM | **10 GB or more is recommended** for GPU inference with the published human checkpoint; adaptive batching may permit smaller workloads on devices with less memory. |
| GPU VRAM (comfortable) | **16 GB** provides additional headroom for larger workloads. |
| System RAM | Workload-dependent. Approximately **16 GB** is a useful starting point for the published human checkpoint with a 100,000-cell anchor pool. |
| CPU-only mode | Supported where the selected backend provides CPU execution, but generally slower than accelerated inference. |

These estimates use the published human checkpoint (approximately 57 million
parameters) with a 100,000-cell by 5,000-gene anchor pool. Smaller anchor pools
or fewer genes generally reduce memory requirements, but memory use also
includes fixed model and runtime overhead.

## 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"
license: "AGPL-3.0-or-later"
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
