# Rust_covpyo3
A fast, Rust-backed Python library for computing per-base coverage over genomic regions from BAM files.
v4.0.1 optimisation of mem alloc and using diff array
---
## Installation
### From PyPI
```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**
```bash
git clone https://github.com/rLannes/Rust_covpyo3
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
All coverage functions require an **indexed** BAM file (a `.bai` next to the `.bam`).
### `get_coverage_algo2`
Computes per-base coverage over a single 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="+",
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). Must be strictly greater than `start` |
| `chrom` | `str` | Chromosome / sequence name, as it appears in the BAM header |
| `strand` | `str` | `"+"`, `"-"`, or `"."` (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.
#### Errors
Raises `RuntimeError` if:
- the BAM file or its index cannot be opened
- `start` is not strictly lower than `end`
- the region cannot be fetched (e.g. `chrom` is not in the BAM header)
- a record or its CIGAR string cannot be read
### `get_coverage_batch`
Same computation and filtering as `get_coverage_algo2`, applied to many regions of the same BAM file at once. Use it instead of calling `get_coverage_algo2` in a loop: the BAM file is opened only once, which is much faster when you have many regions.
```python
from Rust_covpyo3 import get_coverage_batch
regions = [
(10000, 20000, "chr1", "+"),
(50000, 55000, "chr1", "-"),
(3000, 4000, "chr2", "."),
]
coverage = get_coverage_batch(
regions,
bam_path="sample.bam",
lib="frFirstStrand",
mapq_thr=10,
flag_in=0,
flag_exclude=256,
)
coverage[(10000, 20000, "chr1", "+")] # list of 10000 ints
```
#### Parameters
| Parameter | Type | Description |
|---|---|---|
| `batch` | `list[tuple[int, int, str, str]]` | Regions as `(start, end, chrom, strand)` tuples, with the same meaning as in `get_coverage_algo2`. Regions can be given in any order |
| `bam_path`, `lib`, `mapq_thr`, `flag_in`, `flag_exclude` | | Same as `get_coverage_algo2`, applied to every region |
#### Returns
A `dict` mapping each `(start, end, chrom, strand)` tuple to its coverage `list[int]`. A region listed more than once appears once in the output.
#### Errors
Raises `RuntimeError` under the same conditions as `get_coverage_algo2`. If any region fails, the whole batch fails and no result is returned.
### How the coverage is computed
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.
### Other functions
#### `get_header(bam_path)`
Returns the list of sequence (chromosome) names defined in the BAM header.
```python
from Rust_covpyo3 import get_header
get_header("sample.bam") # ["chr1", "chr2", ...]
```
#### `get_mapped_reads(bam_path)`
Returns a list of `(chrom, n_mapped_reads)` tuples read from the BAM index, plus one extra entry for unmapped reads. Requires an indexed BAM file.
```python
from Rust_covpyo3 import get_mapped_reads
get_mapped_reads("sample.bam") # [("chr1", 123456), ("chr2", 98765), ...]
```
Metadata
Release files for Rust_covpyo3 0.4.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| rust_covpyo3-0.4.3.tar.gz | 21.2 kB | Without provenance | Details for rust_covpyo3-0.4.3.tar.gz |
Built distributions (wheels)
| File | Actions Reset | |||
|---|---|---|---|---|
| rust_covpyo3-0.4.3-cp39-abi3-manylinux_2_28_x86_64.whl | CPython 3.9 | abi3 | Linux glibc 2.28+ x86-64 | Details for rust_covpyo3-0.4.3-cp39-abi3-manylinux_2_28_x86_64.whl |
| rust_covpyo3-0.4.3-cp39-abi3-manylinux_2_28_aarch64.whl | CPython 3.9 | abi3 | Linux glibc 2.28+ ARM64 | Details for rust_covpyo3-0.4.3-cp39-abi3-manylinux_2_28_aarch64.whl |
| rust_covpyo3-0.4.3-cp39-abi3-macosx_11_0_arm64.whl | CPython 3.9 | abi3 | macOS 11.0+ ARM64 | Details for rust_covpyo3-0.4.3-cp39-abi3-macosx_11_0_arm64.whl |
| rust_covpyo3-0.4.3-cp39-abi3-macosx_10_12_x86_64.whl | CPython 3.9 | abi3 | macOS 10.12+ x86-64 | Details for rust_covpyo3-0.4.3-cp39-abi3-macosx_10_12_x86_64.whl |
Total release size: 15.8 MB
Release files / rust_covpyo3-0.4.3.tar.gz
| Download URL | rust_covpyo3-0.4.3.tar.gz |
|---|---|
| Size | 21.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
0c941b928016f5f352c28fca552966a2825437219981b497b46866b7024df564
|
|
BLAKE2b-256 checksum How to use checksums |
221d4ccc7d79c6f9e67d4dad230468b9bc13c8b282da0c3bf057dee269d58f45
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.6 {"installer":{"name":"uv","version":"0.13.6","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / rust_covpyo3-0.4.3-cp39-abi3-manylinux_2_28_x86_64.whl
| Download URL | rust_covpyo3-0.4.3-cp39-abi3-manylinux_2_28_x86_64.whl |
|---|---|
| Size | 4.1 MB |
| Tags | CPython 3.9 Linux glibc 2.28+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
ae9cbb59a549d8db763e8b9fa9291bde3f1116cce87853781900668fded8a7d0
|
|
BLAKE2b-256 checksum How to use checksums |
aba7a2c5ba1e7ddb210c5da151213aa7cb36cb4d1aa2ce8d6d855781ee66d5b9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.6 {"installer":{"name":"uv","version":"0.13.6","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / rust_covpyo3-0.4.3-cp39-abi3-manylinux_2_28_aarch64.whl
| Download URL | rust_covpyo3-0.4.3-cp39-abi3-manylinux_2_28_aarch64.whl |
|---|---|
| Size | 4.5 MB |
| Tags | CPython 3.9 Linux glibc 2.28+ ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
853d8a6d463b0fa0ee793290dde7922bc5f09f2d87314c50c5082e7f692a12f1
|
|
BLAKE2b-256 checksum How to use checksums |
85928025daf4c3f3131478017f38b809bc95601e48df53c20662fd2eca522e61
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.6 {"installer":{"name":"uv","version":"0.13.6","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / rust_covpyo3-0.4.3-cp39-abi3-macosx_11_0_arm64.whl
| Download URL | rust_covpyo3-0.4.3-cp39-abi3-macosx_11_0_arm64.whl |
|---|---|
| Size | 3.7 MB |
| Tags | CPython 3.9 abi3 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
7d51ba8348b17b885b6060810ab336928ef08d434be4974ad28c1ae4ea6269cd
|
|
BLAKE2b-256 checksum How to use checksums |
6e0f098e99ca47c3e427d05929df2243ef0920a3e28877de0e502bee56b4f1dc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.6 {"installer":{"name":"uv","version":"0.13.6","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / rust_covpyo3-0.4.3-cp39-abi3-macosx_10_12_x86_64.whl
| Download URL | rust_covpyo3-0.4.3-cp39-abi3-macosx_10_12_x86_64.whl |
|---|---|
| Size | 3.5 MB |
| Tags | CPython 3.9 abi3 macOS 10.12+ x86-64 |
|
SHA-256 checksum How to use checksums |
5587c8074d9701c6667380e625ccedac12c1658dc8512cd1d1ce7ee13562649d
|
|
BLAKE2b-256 checksum How to use checksums |
e0bca8901eb7b96bf0d213b99b0b97406343696953d2c92a284a0c31e50db73a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.6 {"installer":{"name":"uv","version":"0.13.6","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for Rust_covpyo3 0.4.3
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.