Metadata-Version: 2.5
Name: hashrope-bio
Version: 0.3.4
Summary: Computational biology applications of hash rope data structures
Author-email: Muntaser Syed <muntaser@ieee.org>
License-Expression: MIT
License-File: LICENSE
Keywords: bioinformatics,drug-discovery,genomics,hash-rope,sequence-comparison
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.10
Requires-Dist: hashrope<0.4,>=0.3.4
Provides-Extra: bench
Requires-Dist: biopython>=1.83; extra == 'bench'
Requires-Dist: matplotlib>=3.8; extra == 'bench'
Requires-Dist: mdanalysis>=2.7; extra == 'bench'
Requires-Dist: numpy>=1.26; extra == 'bench'
Requires-Dist: pandas>=2.0; extra == 'bench'
Requires-Dist: pysam>=0.22; extra == 'bench'
Requires-Dist: rdkit; extra == 'bench'
Provides-Extra: cheminformatics
Requires-Dist: rdkit; extra == 'cheminformatics'
Provides-Extra: dev
Requires-Dist: pytest-benchmark>=4.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Provides-Extra: genomics
Requires-Dist: biopython>=1.83; extra == 'genomics'
Requires-Dist: pysam>=0.22; extra == 'genomics'
Provides-Extra: proteomics
Requires-Dist: mdanalysis>=2.7; extra == 'proteomics'
Requires-Dist: numpy>=1.26; extra == 'proteomics'
Description-Content-Type: text/markdown

# hashrope-bio

Computational biology applications of [hashrope](https://github.com/jemsbhai/hashrope) —
Exact byte comparison for gene-level change detection, genomic region comparison,
mutation localization, drug resistance screening, and tandem repeat compression.

## Synchronized 0.3.4 release

This version synchronizes the Python and Rust biology packages with core
Hashrope 0.3.4. Biology's exact consumer algorithms are unchanged from 0.3.3.
Version parity preserves correctness contracts and fingerprints; it does not
imply equal performance across languages or workloads. See the
[release scope and performance caveats](https://github.com/jemsbhai/hashrope/blob/master/releases/0.3.4/README.md).

## Exact comparison

This release requires Hashrope 0.3.4 or later in the 0.3 series. Fingerprint
values/defaults are unchanged; equality, mutation and conservation decisions now
verify actual bytes. Report hash fields are metadata, and gene/exon reports carry
separate verified change flags. Manually constructing these reports requires
those flags rather than deriving them from hashes.

Exact verification can scan an entire independent region and uses a per-call
comparison cache where needed. Shared ranges and periodic structure can be skipped after
proof. Historical speedups and datasets below describe the earlier fingerprint
experiments; they do not establish current exact-comparison performance or
universal collision resistance. Historical result files have been preserved.

The [exact-path optimization report](../../../benchmarks/exact_optimization/README.md)
reruns the full stored HIV comparison workload against archived preoptimization
and optimized cores. It includes verification costs and construction exclusions;
it does not revalidate the older chromosome-scale fingerprint speedups below.

## Install

```bash
pip install "hashrope-bio==0.3.4"
```

For optional backends:
```bash
pip install -e ".[genomics]"   # pysam + biopython for FASTA I/O
```

## Features

### Gene-level change detection (`genomics.gene_diff`)

Compare gene bodies and exons exactly, with shortcuts for shared and repeated
structure. Independent equal regions may require reading every byte.

```python
from hashrope_bio.genomics import load_fasta_to_rope, load_gene_regions, diff_genes

ref_rope, h, _ = load_fasta_to_rope("reference.fa")
sample_rope, _, _ = load_fasta_to_rope("patient.fa", h=h)
genes = load_gene_regions("chr22_genes.tsv")
report = diff_genes(ref_rope, sample_rope, genes, h)
print(report.summary())
# Gene diff: 12/643 genes changed, 47/5127 exons changed
#   LARGE1 (650,315 bp): body changed, 3/14 exons differ
#   ...
```

Validated on GRCh38 chr22 with 643 real genes (UCSC refGene): **5,770/5,770 queries correct**.
Speedups: **25× for typical genes (10–50 Kbp), 411× for large genes (>500 Kbp)**.

### Drug resistance screening (`cheminformatics.resistance`)

Check N known resistance mutation sites by comparing actual codon bytes.

```python
from hashrope_bio.cheminformatics.resistance import check_resistance_panel, HIV_RT_NNRTI_PANEL

results = check_resistance_panel(ref_rope, sample_rope, HIV_RT_NNRTI_PANEL, h)
for r in results:
    if r.is_mutant:
        print(f"  {r.site.annotation}")
```

Validated on 100 real clinical HIV-1 sequences against Stanford HIVDB:
**103/103 drug resistance mutations detected (100% sensitivity)**.

### Region identity queries (`genomics.region_query`)

Exact byte comparison for arbitrary genomic regions; fingerprint queries remain available separately.

```python
from hashrope_bio.genomics import region_hash, regions_identical

identical = regions_identical(ref_rope, sample_rope, start=10000, length=50000, h=h)
```

### Mutation localization (`genomics.mutation`)

Exact prefix comparison localizes the first divergent byte. Matching fingerprints do not prune mutations.

Validated on 3,422 ClinVar pathogenic SNVs on chr22: **3,422/3,422 correct (100%)**.

### Tandem repeat compression (`genomics.repeats`)

RepeatNode gives O(log q) hash computation for q-repeat motifs vs O(q·d) naive.
**610× speedup at q=10,000** for clinical trinucleotide repeats (HTT, FMR1).

## Project structure

```
src/hashrope_bio/
├── genomics/          # FASTA loading, region queries, mutation search, gene diff, repeats
├── proteomics/        # MD trajectory frame comparison (stub)
└── cheminformatics/   # Resistance panels, compound lookup with retained verification bytes
benchmarks/            # Experiment scripts
scripts/               # Dataset download helpers
data/                  # Downloaded datasets (gitignored)
tests/                 # Unit tests (28 passing)
```

## Depends on

- [hashrope](https://pypi.org/project/hashrope/) — core rope data structure
- pysam / biopython (optional) — FASTA I/O

## Citation

If you use hashrope-bio in published research, please cite:
- Repository: https://github.com/jemsbhai/hashrope-bio
- Core data structure: https://github.com/jemsbhai/hashrope

## License

MIT

## Compound lookup compatibility

`build_compound_index` retains every candidate and its canonical encoding bytes.
`lookup_compound` checks those bytes inside the matching hash bucket; collisions
and duplicate input rows are retained. Legacy plain dictionaries containing only
hashes/row IDs are rejected because they cannot verify identity; rebuild them
from the source file. Canonicalization remains the caller's responsibility.

Run consumer tests from this directory with local Hashrope installed (or add
`../../../packages/python` and `src` to `PYTHONPATH`): `python -m pytest tests`.
