Metadata-Version: 2.4
Name: aksha
Version: 0.2.1
Summary: Scalable HMM-based sequence search and retrieval
Author: Jacob West-Roberts
License-Expression: MIT
Project-URL: Repository, https://github.com/jwestrob/aksha
Project-URL: Issues, https://github.com/jwestrob/aksha/issues
Keywords: hmm,hmmer,pyhmmer,bioinformatics,sequence-search,genomics,metagenomics
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: <3.13,>=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aksha-runtime==0.1.1
Requires-Dist: pandas>=2.0.0
Requires-Dist: tqdm>=4.65.0
Requires-Dist: requests>=2.28.0
Requires-Dist: platformdirs>=3.0.0
Provides-Extra: gpu
Requires-Dist: aksha-cuda12==0.1.1; extra == "gpu"
Dynamic: license-file

# Aksha

**Fast HMM-based annotation for genomes and metagenomes.**

Aksha accelerates HMM-based sequence searches so you can spend more time on
biology and less time waiting for annotations. Built on [HMMER](http://hmmer.org/)
and [PyHMMER](https://pyhmmer.readthedocs.io/), it combines fast CPU searches,
optional NVIDIA GPU acceleration, database management and sequence retrieval
in one command-line tool.

Aksha outperformed MetaCerberus 1.4 in our Pfam benchmarks on both CPU and GPU.

<details>
<summary>Benchmark results and comparison conditions</summary>

The recorded PLM2_5 workload contained 300,186 proteins and 27,481 Pfam models.

| Tool / configuration | Physical CPU cores | Pfam runtime | Speedup over MetaCerberus |
| --- | ---: | ---: | ---: |
| MetaCerberus 1.4, CPU | 64 | 11m 34s | — |
| Aksha, CPU | 64 | 4m 46s | 2.43× |
| Aksha, 1 H200 GPU + CPU | 64 host cores | 3m 39s | 3.17× |

Aksha's CPU and GPU outputs matched exactly in these runs. Both CPU-only
runs used 64 physical cores on the same Xeon 6787P machine. The GPU run used
one H200 plus 64 physical Xeon Platinum 8480+ host cores on a separate node.
Core counts are allocated physical cores, not CPU sockets or SMT threads.
MetaCerberus timing covers its HMM search/filter/parse pipeline, not
additional reporting; its thresholds and output rules differ, so this is a
workflow comparison, not identical-work benchmarking. Measurements predate
wheel packaging. [CPU evidence](https://github.com/jwestrob/aksha/blob/main/docs/development/CPU_PRODUCTION_INTEGRATION.md)
and [GPU evidence](https://github.com/jwestrob/aksha/blob/main/docs/development/GPU_PRODUCTION_INTEGRATION.md).

</details>

## More than a fast search

- Search proteins or nucleotide sequences using supported databases or your own HMMs.
- Download and manage databases such as Pfam and KOfam from the same tool.
- Use a database's recommended cutoffs, or choose your own score and E-value thresholds.
- Export tabular results and optionally retrieve matching sequences for downstream analysis.

## Installation

The PyPI release is being prepared. Once published:

```bash
python -m pip install aksha
# With optional GPU support:
python -m pip install 'aksha[gpu]'
```

Currently supported: Linux x86-64 with Python 3.12. GPU use requires a
compatible NVIDIA GPU and driver. ARM, macOS and Windows are not yet supported.
See the [installation guide](https://github.com/jwestrob/aksha/blob/main/release/INSTALL.md)
for hardware requirements, local-wheel installation and GPU setup.

## Quick start

Download the Pfam protein-family database, then search your protein sequences:

```bash
aksha initialize --hmms PFAM
aksha search --prot_in proteins.faa --installed_hmms PFAM --cut_ga --outdir results
```

Results are written to `results/`. The example uses Pfam's built-in score
thresholds. You can also supply your own models with `--hmm_in` instead of
`--installed_hmms`. Run `aksha --help` or `aksha search --help` for more options.

The [database setup guide](https://github.com/jwestrob/aksha/blob/main/docs/database-setup.md)
explains available databases, storage locations and reusing existing files.
For source builds, see the [maintainer guide](https://github.com/jwestrob/aksha/blob/main/release/BUILD.md).

## License

Aksha's original code is MIT-licensed; third-party components retain their own
licenses. See the [application license](https://github.com/jwestrob/aksha/blob/main/LICENSE),
[native-code license](https://github.com/jwestrob/aksha/blob/main/native/README.md)
and [third-party notices](https://github.com/jwestrob/aksha/blob/main/release/THIRD_PARTY_NOTICES.md).
