molecular-annotation

Python bindings for molecular annotation tags in SAM/BAM/CRAM files.

This package provides a Python interface to parse and generate MA/AQ/AN tags according to the Molecular Annotation specification.

Installation

pip install molecular-annotation

Usage

from molecular_annotation import MolecularAnnotations

# Parse from MA tag string (positions in the tag are 1-based per spec)
# If annotation type has quality (P, Q, PQ, etc.), must provide aq array
ma_string = "1000;msp+P:100-50,200-60"
aq_array = [40, 35]  # Quality scores for the 2 msp annotations
annotations = MolecularAnnotations.from_tags(ma_string, aq=aq_array)

# Parse without quality scores
ma_string = "1000;nuc+:100-147,250-147"
annotations = MolecularAnnotations.from_tags(ma_string)

# Access properties
print(annotations.read_length)  # 1000
print(annotations.total_annotation_count())  # 2

# Generate tag values
print(annotations.to_ma_string())  # "1000;nuc+:100-147,250-147"
print(annotations.to_aq_array())   # None (no quality for nuc type)
print(annotations.to_an_string())  # None (no names)

Building Annotations

All API coordinates are 0-based half-open [start, end). The MA tag string uses 1-based positions per spec, and conversion is handled automatically.

from molecular_annotation import MolecularAnnotations

# Create empty container
annotations = MolecularAnnotations(1000)  # read length

# Add annotations with a single quality value per annotation
annotations.add_annotations(
    'msp', '+', 'P',            # type_name, strand, quality_spec
    starts=[100, 200, 350],     # 0-based start positions
    lengths=[50, 60, 45],       # annotation lengths
    qualities=[40, 35, 38]      # one quality score per annotation
)

# Add annotations without quality
annotations.add_annotations(
    'nuc', '+', '',             # empty quality_spec = no quality values
    starts=[150, 400],
    lengths=[147, 147]
)

# Add annotations with multiple quality values per annotation
# "PQ" = 2 values per annotation (first phred-scaled, second linear-scaled)
annotations.add_annotations(
    'ctcf', '+', 'PQ',
    starts=[500, 700],
    lengths=[20, 30],
    qualities=[40, 255, 30, 200]  # 2 annotations x 2 values = 4 total
)

print(annotations.to_ma_string())
# "1000;msp+P:101-50,201-60,351-45;nuc+:151-147,401-147;ctcf+PQ:501-20,701-30"

You can also use ends instead of lengths:

annotations.add_annotations(
    'msp', '+', 'P',
    starts=[100, 200],
    ends=[150, 260],            # 0-based exclusive end positions
    qualities=[40, 35]
)

Iterating Over Annotations

# Iterate over all annotations with full coordinate info
for type_name, strand, quality_spec, qs, qe, fs, fe, rs, re, quals, name in annotations.iter_full():
    print(f"{type_name} [{qs}, {qe}) quals={quals}")

# Iterate over a specific type
for qs, qe, fs, fe, rs, re, quals, name in annotations.iter_type("msp"):
    print(f"[{qs}, {qe}) quals={quals}")

Working with pysam

import pysam
from molecular_annotation import MolecularAnnotations, from_record, write_to_record

# Read annotations from a BAM record
with pysam.AlignmentFile("input.bam") as bam:
    for record in bam:
        try:
            annotations = from_record(record)
            print(f"{record.query_name}: {annotations.total_annotation_count()} annotations")
        except KeyError:
            pass  # No MA tag

# Write annotations to a BAM record
annotations = MolecularAnnotations(1000)
annotations.add_annotations('msp', '+', 'P', [100, 200], lengths=[50, 60], qualities=[40, 35])
write_to_record(annotations, record)

Tag Format

See the Molecular Annotation Specification for details on the tag formats and conventions.

Project links

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

2 maintainers

PyPI data
Data sourced directly from PyPI's database.
Avatar for cademirch from gravatar.com cademirch Avatar for mrvollger from gravatar.com mrvollger

Credits

Author: Mitchell Vollger

License

MIT License (MIT)

Requires

Python >=3.8

Provides Extra

dev

Tags

bioinformatics genomics SAM BAM CRAM molecular annotation

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

molecular_annotation-0.1.0.tar.gz (213.2 kB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

molecular_annotation-0.1.0-cp38-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (1.0 MB view details)

Uploaded CPython 3.8+manylinux: glibc 2.17+ x86-64

molecular_annotation-0.1.0-cp38-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (1.0 MB view details)

Uploaded CPython 3.8+manylinux: glibc 2.17+ ARM64

molecular_annotation-0.1.0-cp38-abi3-macosx_11_0_arm64.whl (893.9 kB view details)

Uploaded CPython 3.8+macOS 11.0+ ARM64

molecular_annotation-0.1.0-cp38-abi3-macosx_10_12_x86_64.whl (932.3 kB view details)

Uploaded CPython 3.8+macOS 10.12+ x86-64

File details

Details for the file molecular_annotation-0.1.0.tar.gz.

File metadata

  • Download URL: molecular_annotation-0.1.0.tar.gz
  • Upload date:
  • Size: 213.2 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for molecular_annotation-0.1.0.tar.gz
Algorithm Hash digest
SHA256 ebaf91f43720768fc165473a1f5dd4d3d374872c1bf174521bac071c9388b4ab
MD5 e19ddbe4fbf3323e8d41bbcaf872b78f
BLAKE2b-256 72deb8a4eeda8a684aa21cb7881ad8dd9692029e553af42ca2e0f366d8afae15

See more details on using hashes here.

Provenance

The following attestation bundles were made for molecular_annotation-0.1.0.tar.gz:

Publisher: release-python-ma.yml on fiberseq/fibertools-rs

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file molecular_annotation-0.1.0-cp38-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for molecular_annotation-0.1.0-cp38-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 ca20670d915892bb542dff14451a8b6deaf8af5941a7032e821284e2110ff919
MD5 927d0d5f762661a16bc4f35b603718cb
BLAKE2b-256 2fa7c421d9778fb12b295936cdeb2f4f3384e907aeba6b47c0a4a082d41e1301

See more details on using hashes here.

Provenance

The following attestation bundles were made for molecular_annotation-0.1.0-cp38-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: release-python-ma.yml on fiberseq/fibertools-rs

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file molecular_annotation-0.1.0-cp38-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for molecular_annotation-0.1.0-cp38-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 60f77a2d2e51140ab7d41fbbd883fea6cf8e97820c8140cb2ba5e093457fc0d6
MD5 14a5ab3ebddef6fa0cb351bcdf0b8a9a
BLAKE2b-256 b1a390e53edc2878aa2fee05b7265491451620255a4027dc3f0325798a268b5c

See more details on using hashes here.

Provenance

The following attestation bundles were made for molecular_annotation-0.1.0-cp38-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl:

Publisher: release-python-ma.yml on fiberseq/fibertools-rs

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file molecular_annotation-0.1.0-cp38-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for molecular_annotation-0.1.0-cp38-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 4b4519955a3a6c9ff76027e70a4d32d9d15a0782a5d74f4b04791327c2036ba8
MD5 18d144b10527fa3b5dcd37b3439d2a52
BLAKE2b-256 2290b1169bfd27caab558c2d3501fe7f717805f213a51973354c77ab94f2f315

See more details on using hashes here.

Provenance

The following attestation bundles were made for molecular_annotation-0.1.0-cp38-abi3-macosx_11_0_arm64.whl:

Publisher: release-python-ma.yml on fiberseq/fibertools-rs

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file molecular_annotation-0.1.0-cp38-abi3-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for molecular_annotation-0.1.0-cp38-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 da7ff775e9417003e3541ea1aabf87123346cca123d868331abdb00c24c0a31a
MD5 ac0a1b8f56e6c3835ef741c686ee967a
BLAKE2b-256 e39d780bf55b3bd6ab28483e57b3f5b085e6cff8b08c1b16b245958cfd5f626d

See more details on using hashes here.

Provenance

The following attestation bundles were made for molecular_annotation-0.1.0-cp38-abi3-macosx_10_12_x86_64.whl:

Publisher: release-python-ma.yml on fiberseq/fibertools-rs

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

0.1.0 This release

5 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page