Rust-covpyo3 0.3.0

Fast Rust-backed per-base coverage computation over genomic regions from BAM files.

# Rust_covpyo3
 
A fast, Rust-backed Python library for computing per-base coverage over genomic regions from BAM files.
 
---



## Instalation

### dependencies:
python dependencies
```
 pip install maturin
 pip install numpy
 ```

 rust 
 to install rust go to : https://www.rust-lang.org/tools/install
and follow the instruction usually it just required to copy paste a link in the terminal.

### install pip
can be installed by pip! 
```bash
pip install Rust_covpyo3
```

### local build
If no prebuilt wheel is available for your platform, or you want to build from source, you'll need to compile the Rust backend yourself.
 
**1. Install Python dependencies**
 
```bash
pip install maturin numpy
```
 
**2. Install a recent Rust toolchain**
 
Follow the official instructions at https://www.rust-lang.org/tools/install — usually a single command pasted into your terminal.
 
**3. Build and install the wheel**
 
From the repository root:
 
```bash
cd Rust_covpyo3
maturin build --release
python -m pip install -U target/wheels/*.whl
```

The build can take 30 seconds to a few minutes depending on your internet connection.
 
> 💡 If you build multiple times, clear `target/wheels/` first so `pip` only sees one wheel to install.
 
> 💡 If you're working in a virtual environment and want hot-reloading during development, use `maturin develop` instead of `maturin build`. See the [maturin documentation](https://github.com/PyO3/maturin) for details.


## Usage

### `get_coverage_algo2`

Computes per-base coverage over a genomic region using an interval-based algorithm. Rather than piling up base-by-base, it parses each read's CIGAR string to determine the reference positions it covers, then increments a coverage array for those positions. This makes it efficient for sparse regions and gives you fine-grained control over which reads to include.

```python
from Rust_covpyo3 import get_coverage_algo2

coverage = get_coverage_algo2(
    start=10000,
    end=20000,
    chrom="chr1",
    strand="Plus",
    bam_path="sample.bam",
    lib="frFirstStrand",
    mapq_thr=10,
    flag_in=0,
    flag_exclude=256,
)
# coverage is a list of ints, one per position from start to end
```

### Parameters

| Parameter | Type | Description |
|---|---|---|
| `start` | `int` | Start of the region (0-based, inclusive) |
| `end` | `int` | End of the region (0-based, exclusive) |
| `chrom` | `str` | Chromosome / sequence name |
| `strand` | `str` | `"Plus"`, `"Minus"`, or `"NA"` (unstranded) |
| `bam_path` | `str` | Path to an indexed BAM file |
| `lib` | `str` | Library type — accepted values: `frFirstStrand` (TruSeq stranded), `frSecondStrand`, `fFirstStrand`, `fSecondStrand`, `ffFirstStrand`, `ffSecondStrand`, `rfFirstStrand`, `rfSecondStrand`, `rFirstStrand`, `rSecondStrand`. See [BAMstrandSpecifier](https://github.com/rLannes/BAMstrandSpecifier) |
| `mapq_thr` | `int` | Minimum mapping quality. Set to `0` to disable filtering |
| `flag_in` | `int` | SAM flags that **must** be set (bitwise). Use `0` for no requirement |
| `flag_exclude` | `int` | SAM flags that **must not** be set (bitwise). e.g. `256` to exclude secondary alignments |

### Returns

A `list[int]` of length `end - start`, where each element is the read depth at that position.

### How it works

1. All reads overlapping the `[start, end)` region are fetched from the BAM index.
2. Each read is filtered by `flag_in` / `flag_exclude` and mapping quality.
3. For strand-specific libraries, the read's strand is inferred from its flags and the library type. Only reads matching the requested `strand` are kept. For unstranded libraries, all passing reads are counted.
4. The read's CIGAR string is parsed to extract the intervals on the reference that the read actually covers (skipping deletions and spliced regions).
5. Those intervals are intersected with `[start, end)` and the corresponding positions in the output array are incremented.