Metadata-Version: 2.3
Name: aligntools
Version: 1.0.4
Summary: A Python library for manipulation of CIGAR, MSA, and other alignment formats.
Author-email: British Columbia Centre for Excellence in HIV/AIDS <vmysak@bccfe.ca>
License-Expression: GPL-3.0
License-File: COPYING
Provides-Extra: dev
Requires-Dist: bandit; extra == 'dev'
Requires-Dist: flake8; extra == 'dev'
Requires-Dist: mypy==1.9.0; extra == 'dev'
Provides-Extra: test
Requires-Dist: pytest-cov; extra == 'test'
Requires-Dist: pytest>=6.0; extra == 'test'
Description-Content-Type: text/markdown


[![codecov](https://codecov.io/gh/cfe-lab/aligntools/branch/master/graph/badge.svg)](https://codecov.io/gh/cfe-lab/aligntools)
[![types - Mypy](https://img.shields.io/badge/types-Mypy-blue.svg)](https://github.com/python/mypy)
[![flake8 checked](https://img.shields.io/badge/flake8-checked-blueviolet.svg)](https://github.com/PyCQA/flake8)
[![License - GPL3](https://img.shields.io/badge/license-GPLv3-blue)](https://spdx.org/licenses/)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/cfe-lab/aligntools/pulls)

# Alignment tools

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.

## Features

- **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.

## Examples

### Parsing and Manipulating a CIGAR String

You can easily parse a CIGAR string and perform various operations using the `Cigar` class:

```python
from aligntools import Cigar

# Parse a CIGAR string
cigar = Cigar.coerce("10M1I5D5M")

# Enumerate operations
for operation in cigar.iterate_operations():
    print(operation)

# Output:
# CigarActions.MATCH
# CigarActions.MATCH
# ... (continues)
# CigarActions.MATCH
# CigarActions.INSERT
# CigarActions.DELETE
# ... (continues)
# CigarActions.MATCH
# CigarActions.MATCH

# 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: 16
```

### Cutting a CIGAR String by Reference Position

CIGAR strings can be split at specific reference positions, allowing for more fine-grained control over the alignment:

```python
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]
```

### Trimming Query and Reference Sequences

You can trim unmatched regions from either the query or reference sequence:

```python
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: 5S10M
```

### Converting CIGAR Strings to Multiple Sequence Alignments (MSA)

Convert a CIGAR string to a multiple sequence alignment (MSA) representation for better visualization of how sequences align:

```python
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:     ACGTTACGTATG
```

### Merging Consecutive Alignments

`aligntools` can merge two consecutive CIGAR strings into a single normalized CIGAR string:

```python
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: 5M5D10M
```

### Advanced Usage: Coordinate Mapping Between Reference and Query Sequences

You can manage coordinate translations between the reference and query using `CoordinateMapping`:

```python
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: 8
```

### Using `CigarHit` for Complex Alignment Manipulations

The `CigarHit` class is a higher-level abstraction that allows you to perform complex operations on a sequence alignment:

```python
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]
```

## Installation

To use `aligntools` for your projects, simply run `pip install aligntools`.

## Contributing

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:

```shell
# 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:

```shell
pytest && flake8 && bandit
```

- Pushing the changes back to GitHub servers:

```
git push origin HEAD
```

- Creating a pull request through GitHub UI. Go to [aligntools repository](https://github.com/cfe-lab/aligntools), and select "Create pull request option".

## License

This project is licensed under the GPLv3.0 License. See the COPYING file for details.
