This Python library provides robust tools for handling CIGAR strings and related alignment formats in bioinformatics. CIGAR ("Compact Idiosyncratic Gapped Alignment Report") strings succinctly represent alignment data between sequences - such as genomic sequences - highlighting matches, mismatches, insertions, deletions, and more within aligned sequences. The functionality within this library abstracts and simplifies interactions with CIGAR strings, making it easier to manipulate, interpret, and convert these alignment specifications for analytical and visualization purposes.
- Easy CIGAR String Parsing and Construction: Easily parse CIGAR strings from text or create them programmatically with detailed annotations for operations like matching, inserting, or deleting.
- Alignment Manipulation: Slice, trim, and concatenate sequence alignments for advanced genomic analyses.
- Coordinate Mapping: Provides bi-directional mapping between reference and query sequences, enabling you to track and modify coordinates with precision.
- Gap Identification: Detect gaps, insertions, and deletions within alignments to facilitate adjustments and further analysis.
- Multiple Sequence Alignment (MSA): Convert CIGAR strings into multiple sequence alignment (MSA) representations for visualization or further processing.
- CIGAR String Normalization: Merge consecutive identical operations and support merging non-overlapping alignments to normalize complex CIGAR strings.
You can easily parse a CIGAR string and perform various operations using the Cigar class:
from aligntools import Cigar
# Parse a CIGAR string
cigar = Cigar.coerce("10M1I5D5M")
# Enumerate operations
for operation in cigar.iterate_operations():
print(operation)
# Output:
# M M M M M M M M M M I D D D D D M M M M M
# Calculate the lengths of the reference and query sequences
print(f"Reference Length: {cigar.ref_length}")
print(f"Query Length: {cigar.query_length}")
# Output:
# Reference Length: 20
# Query Length: 16CIGAR strings can be split at specific reference positions, allowing for more fine-grained control over the alignment:
from aligntools import Cigar, CigarHit
# Parse a CIGAR string and create a CigarHit
cigar = Cigar.coerce("10M5I10M")
hit = CigarHit(cigar, r_st=0, r_ei=19, q_st=0, q_ei=24)
# Cut the alignment at reference position 10.5 (at midpoint between positions 10 and 11).
left, right = hit.cut_reference(10.5)
print("Left slice:", left)
print("Right slice:", right)
# Output:
# Left slice: 10M5I1M@[0,15]->[0,10]
# Right slice: 9M@[16,24]->[11,19]You can trim unmatched regions from either the query or reference sequence:
from aligntools import Cigar
# Parse a CIGAR string with unmatched regions
cigar = Cigar.coerce("5S10M5S")
# Trim unmatched regions from the query sequence
trimmed_cigar = cigar.rstrip_query()
print(f"Trimmed CIGAR: {trimmed_cigar}")
# Output:
# Trimmed CIGAR: 5S10MConvert a CIGAR string to a multiple sequence alignment (MSA) representation for better visualization of how sequences align:
from aligntools import Cigar
# Parse a CIGAR string
cigar = Cigar.coerce("5M2I5M")
# Define reference and query sequences
ref_seq = "ACGTACGTAC"
query_seq = "ACGTTACGTATG"
# Convert to MSA
ref_msa, query_msa = cigar.to_msa(ref_seq, query_seq)
print(f"Reference MSA: {ref_msa}")
print(f"Query MSA: {query_msa}")
# Output:
# Reference MSA: ACGTA--CGTAC
# Query MSA: ACGTTACGTATGaligntools can merge two consecutive CIGAR strings into a single normalized CIGAR string:
from aligntools import Cigar
# Parse two CIGAR strings
cigar1 = Cigar.coerce("5M5D")
cigar2 = Cigar.coerce("10M")
# Merge the two alignments
merged_cigar = cigar1 + cigar2
print(f"Merged CIGAR: {merged_cigar}")
# Output: Merged CIGAR: 5M5D10MYou can manage coordinate translations between the reference and query using CoordinateMapping:
from aligntools import Cigar
# Create a CIGAR and its coordinate mapping
cigar = Cigar.coerce("5M2I3M")
mapping = cigar.coordinate_mapping
# Translate reference and query coordinates
ref_coordinate = 3
query_coordinate = mapping.ref_to_query[ref_coordinate]
print(f"Query coordinate: {query_coordinate}")
# Output:
# Query coordinate: 3
ref_coordinate = 6
query_coordinate = mapping.ref_to_query[ref_coordinate]
print(f"Query coordinate: {query_coordinate}")
# Output:
# Query coordinate: 8The CigarHit class is a higher-level abstraction that allows you to perform complex operations on a sequence alignment:
from aligntools import Cigar, CigarHit
# Define a complex CIGAR string and create a CigarHit
cigar = Cigar.coerce("5M2D5M")
hit = CigarHit(cigar, r_st=0, r_ei=11, q_st=0, q_ei=9)
# Cut and trim the alignment
left, right = hit.cut_reference(4.5)
trimmed_hit = right.rstrip_reference()
print("Left Hit: ", left)
print("Right (trimmed) Hit:", trimmed_hit)
# Output:
# Left Hit: 5M@[0,4]->[0,4]
# Right (trimmed) Hit: 2D5M@[5,9]->[5,11]To use aligntools for your projects, simply run pip install aligntools.
We welcome contributions to the aligntools project! Whether you want to fix a bug, add new features, or improve documentation, feel free to fork the repository, make your changes, and submit a pull request. We also welcome issues and suggestions.
To make changes to aligntools:
- Fork the repository. This is done through GitHub UI, initiated by the "Fork" button.
- Cloning the repository, like so:
# Get the repository sources.
git clone https://github.com/${YOUR_USERNAME}/aligntools
cd aligntools
pip install .[dev,test] # Install all development, and test dependencies.
git checkout -b $YOUR_CHANGE_NAME- Editing some files & commiting the results.
- Running the validation, like this:
pytest && ruff check && bandit- Pushing the changes back to GitHub servers:
git push origin HEAD
- Creating a pull request through GitHub UI. Go to aligntools repository, and select "Create pull request option".
This project is licensed under the AGPLv3.0 License. See the COPYING file for details.