straln: Stretcher Alignment Toolkit

straln is a bioinformatics tool designed to parse .aln files in markx0 format generated by the EMBOSS stretcher alignment tool. It transforms pairwise alignments into standardized genomic formats (BEDPE/BED) and provides tools to overlap these results with VCF data and snap visual evidence in IGV.

Features

• Format Conversion: Transform .aln files into standardized BED and BEDPE formats.
• Automatic Merging: Automatically join consecutive alignment blocks to clarify long insertions or deletions.
• Genomic Integration: Intersects alignment discrepancies with VCF records to identify alternative genomic positions for variants that may have been misaligned or misplaced by standard callers in repetitive or paralogous regions.
• Evidence Capture: Automate IGV snapshots for quicker manual validation of detected variants.

Installation

Install the latest stable version via pip:

pip install git+https://github.com/nikolienka24/straln

# print help
straln --help

Usage Guide

straln is built around three primary modules: parse, overlap, and snap, and one complementary: swap.

1. Parse alignment (parse)

Convert EMBOSS markx0 files into to standardized BEDPE and BED formats.

Arguments

Parameter	Short	Description	Default
alignment_file	Path to the input.aln file.	Required
--output	-o	Directory to save the parsed files.	./straln_parse_results
--seq1_name	-s1	Label for seq1.	seq1
--seq2_name	-s2	Label for seq2.	seq2
--offset1	-off1	Manual 0-based offset for seq1.	Extracted from the input alignment file header.
--offset2	-off2	Manual 0-based offset for seq2.	Extracted from the input alignment file header.

Command

straln parse my_alignment.aln -o ./results

Output files

File	Format	Description
parsed.bedpe	BEDPE	Raw Alignment Blocks. Captures every discrepancy.
parsed.joined.bedpe	BEDPE	Merged Blocks. Collapses fragmented segments for easier visualization of long indels (example below).
seq1.bed / seq2.bed	BED	Independent Tracks. Standard BED files representing discrepancies in each individual sequence from the alignment.
stats.txt	Text	Metrics. Summary of alignment length, identity percentage, mismatches, and gaps.

Note: Coordinates in BEDPE/BED files are 0-based and half-open like in the standard formats.

Example: Automatic Merging (.joined files)

The straln toolkit automatically identifies fragmented alignment blocks collapses them into unified genomic intervals. This occurs when two consecutive rows in the parsed.bedpe file represent a continuous biological sequence.

Raw Fragments (parsed.bedpe)

chrom1	start1	end1	chrom2	start2	end2	nucleotide1	nucleotide2
seq1	8	9	seq2	10	11	A	T
seq1	23	24	seq2	26	28	T	TT
seq1	23	24	seq2	28	29	T	C
seq1	23	24	seq2	29	30	T	C

Merged Result (parsed.joined.bedpe)

straln recognizes these belong to a single continuous alignment event:

seq1	start1	end1	chrom2	start2	end2	sequence1	sequence2
seq1	8	9	seq2	10	11	A	T
seq1	23	24	seq2	26	30	T	TTCC

Note: This merging is essential for the overlap module, as it defines the true boundaries of structural variants.

---

2. Swap alignment columns (swap)

The swap module flips the roles of the two sequences in a BEDPE file. It exchanges all coordinates and sequences for seq1 (columns 1-3, 7) with those of seq2 (columns 4-6, 8). This is particularly useful when you need to change the reference orientation of your alignment results, e.g. using straln overlap.

Arguments

Parameter	Short	Description	Default
input_file		Path to the input.bedpe file to be swapped.	Required
--output	-o	Path to the output swapped BEDPE file.	swapped.bedpe

Command

straln swap -o parsed.swapped.bedpe parsed.bedpe

Example Transformation

Before Swap (parsed.bedpe)

chrom1	start1	end1	chrom2	start2	end2	seq1	seq2
seq1	3	4	seq2	1	2	AA	A
seq1	31	41	seq2	11	12	AA	A

After Swap (parsed.swapped.bedpe)

chrom1	start1	end1	chrom2	start2	end2	seq1	seq2
seq2	1	2	seq1	2	4	A	AA
seq2	11	12	seq1	31	41	A	AA

---

3. Find alternative mutations (overlap)

• overlap: Compares mutations from your alignment/parsed alignment in BEDPE against a VCF file within a user-defined distance to report all variant matches.

Parameters

Parameter	Short	Description	Required
--vcf	-v	Path to the input VCF file.	Yes
--bedpe	-b	Path to the input parsed BEDPE file.	Yes or --aln
--aln	-a	Path to the input alignment file.	Yes or --bedpe
--chrom	-c	Target chromosome identifier. This is implemented as Regex search, so for diploid genomes, include specific suffixes (e.g., 17_maternal or chr1_pat).	Yes
--distance	-d	Search distance (bp) around alignment gaps.	No, default: 100
--precentual_identity	-p	Percentual identity of compared (alternative) mutations to the vcf mutation (float).	No, default: 99.0
--output_folder	-o	Search distance (bp) around alignment gaps.	No, default: ./straln_overlap_result

Command

# parsed alignment
straln overlap --bedpe parsed.bedpe -v variations.vcf -c 17 -d 150

# raw alignment
straln overlap --aln input.aln -v variations.vcf -c 17 -d 150

Output files

File	Format	Description
alternative_mutations.csv	CSV	Alternative Variant Matches. A list of variants from your VCF file found near alignment discrepancies.

---

4. Visual verification (snap)

The snap module creates an IGV batch script based on a JSON configuration file. This allows you to generate high-resolution screenshots of all provided discrepancies automatically.

Arguments

Parameter	Short	Description	Default
config		Path to the setup.json configuration file.	Required

Template for setup.json

{
  "paths": {
    "genome_fasta": "./HG002.fasta",
    "regions_file": "./regions.bed",
    "tracks": [
      "HG002.corrected.bam",
      "problematic.HG002.bed"
    ],
    "output_dir": "./outputs",
    "script_file": "./script.txt"
  },
  "igv_settings": {
    "window_padding": 50,
    "max_panel_height": 2000
  }
}

Command

straln snap setup.json

Output

File Type	Path
Batch Script	./script.txt

How to run the IGV batch script

Once you have generated the script file using the straln snap command, you can execute it to generate your snapshots using one of the two methods below.

Method 1: Using the IGV Desktop App (Graphical Interface)

1. Open the IGV Desktop application on your computer.
2. Load the Script: In the top menu bar, navigate to Tools > Run Batch Script...
3. Select Script File: Browse to your generated .txt file and click Open.
4. Execution: IGV will automatically begin loading tracks, navigating to the coordinates, and saving snapshots to your specified output directory.

Method 2: Using the Command Line (Non-Graphical Interface)

This method is ideal for automation or if you prefer working within the terminal.

On Linux or macOS: Open your terminal and run the igv.sh script provided in the IGV installation folder:

# General syntax
./igv.sh -b <path_to_your_script.txt>

# Example
./igv.sh -b ./scripts/igv_screenshot_script_PAN011.txt