Metadata-Version: 2.4
Name: hector-sc
Version: 1.0.2
Summary: HECTOR single-cell inference and trajectory visualization package.
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/Polligator/HECTOR
Project-URL: Repository, https://github.com/Polligator/HECTOR
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 and Contrastive Training for Ontology-guided Recognition and Trajectory Analysis of single-cell sequencing data

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

**Prefer a graphical interface?** [HECTOR Desktop](https://github.com/Polligator/HECTOR-Desktop) lets you load data, run predictions, and explore results without using the command line. Download the macOS or Windows application from its [Releases page](https://github.com/Polligator/HECTOR-Desktop/releases).

## 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 on Hugging Face.

- `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") # model will automatically download
predictions = predictor.predict(adata)
predictor.write_predictions(adata, predictions)
```


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


## Citation

```yaml
title: "A shared ontology representation of cell identity and development"
version: "1.0"
license: "Apache-2.0"
repository-code: "https://github.com/Polligator/HECTOR"
```

## License

The source code is released under the Apache License, Version 2.0. See
[`LICENSE`](LICENSE) for details.

The project name, logo, icons, and related branding are not licensed under
Apache-2.0. 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.
