esl-alimap(1)

💖 esl-alimap — the Easel manual, bestie edition 💖

okay so first of all, hi, welcome to esl-alimap(1) from the Easel Manual. yes it's a real manpage, yes it's about mapping two alignments to each other, and yes I'm gonna make it make sense. grab a snack. 🍓

---

✨ NAME ✨

esl-alimap — map two alignments to each other. that's it. that's the whole vibe. 💅

---

🌸 SYNOPSIS 🌸

esl-alimap [options] msafile1 msafile2

two files, one dream. 🦋

---

👑 DESCRIPTION 👑

okay so esl-alimap is a highly specialized application — like, it does one thing and it does it iconically — and that thing is determining the optimal alignment mapping of columns between two alignments of the same sequences.

so what even is an alignment mapping? it defines, for every column in alignment 1, a matching column in alignment 2. and the number of residues in the aligned sequences that are in common between those two matched columns? those are considered 'shared' by those two columns. periodt.

for example — and stay with me here — if the nth residue of sequence i occurs in alignment 1 column x and alignment 2 column y, then the only mapping of alignment 1 and 2 that would correctly map and share that residue is one that includes column x mapping to column y. it's giving soulmates. 💖

the optimal mapping of the two alignments is the mapping which maximizes the sum of shared residues between all pairs of matching columns. and the fraction of total residues that are shared? that gets reported as the coverage in the esl-alimap output. slay.

not me needing to say this but: only the first alignments in msafile1 and msafile2 will be mapped to each other. if the files contain more than one alignment, all alignments after the first will be ignored. the rest are getting ghosted. 💀

the two alignments (one from each file) must contain exactly the same sequences (if they were unaligned, they'd be identical) in precisely the same order. also they must be in Stockholm format. no substitutions, bestie. 🙈

the output of esl-alimap differs depending on whether one or both of the alignments contain reference (#=GC RF) annotation. if so, the coverage for residues from nongap RF positions will be reported separately from the total coverage. two numbers, both valid, we love a split report. ✨

esl-alimap uses a dynamic programming algorithm to compute the optimal mapping. the algorithm is similar to the Needleman-Wunsch-Sellers algorithm — but plot twist — the scores used at each step of the recursion are not residue-residue comparison scores, they're the number of residues shared between two columns. iconic behavior honestly. 🔥

now, the --mask-a2a <f>, --mask-a2rf <f>, --mask-rf2a <f>, and --mask-rf2rf <f> options create 'mask' files that pertain to the optimal mapping in slightly different ways. a mask file consists of a single line, of only '0' and '1' characters. these denote which positions of the alignment from msafile1 map to positions of the alignment from msafile2 as described below for each of the four respective masking options. these masks can be used to extract only those columns of the msafile1 alignment that optimally map to columns of the msafile2 alignment using the esl-alimask miniapp.

and here's the lil catch bestie 🫶 — to extract the corresponding set of columns from msafile2 (that optimally map to columns of the alignment from msafile1), it is necessary to rerun the program with the order of the two msafiles reversed, save new masks, and use esl-alimask again. yes, you gotta do it twice. it's a two-pass situation. the way that symmetry works. 💜

---

💅 OPTIONS 💅

• -h — print brief help; includes version number and summary of all options. your lil emergency exit when you forget everything. 🙈
• -q — be quiet; don't print information the optimal mapping of each column, only report coverage and potentially save masks to optional output files. lowkey the introvert flag. 🤫
• --mask-a2a <f> — save a mask of '0's and '1's to file <f>. a '1' at position x means that position x of the alignment from msafile1 maps to an alignment position in the alignment from msafile2 in the optimal map. alignment-to-alignment, the classic. ✨
• --mask-a2rf <f> — save a mask of '0's and '1's to file <f>. a '1' at position x means that position x of the alignment from msafile1 maps to a nongap RF position in the alignment from msafile2 in the optimal map. alignment-to-RF, fancy. 🎀
• --mask-rf2a <f> — save a mask of '0's and '1's to file <f>. a '1' at position x means that nongap RF position x of the alignment from msafile1 maps to an alignment position in the alignment from msafile2 in the optimal map. RF-to-alignment, the reverse queen. 👑
• --mask-rf2rf <f> — save a mask of '0's and '1's to file <f>. a '1' at position x means that nongap RF position x of the alignment from msafile1 maps to a nongap RF position in the alignment from msafile2 in the optimal map. RF-to-RF, the most exclusive club. 🌈
• --submap <f> — specify that all of the columns from the alignment from msafile1 exist identically (contain the same residues from all sequences) in the alignment from msafile2. this makes the task of mapping trivial. however, not all columns of msafile1 must exist in msafile2. save the mask to file <f>. a '1' at position x of the mask means that position x of the alignment from msafile1 is the same as position y of msafile2, where y is the number of '1's that occur at positions <= x in the mask. easy mode unlocked. ⭐
• --amino — assert that msafile1 and msafile2 contain protein sequences. 🧬
• --dna — assert that msafile1 and msafile2 contain DNA sequences. 🧬
• --rna — assert that the msafile1 and msafile2 contain RNA sequences. 🧬

---

🦋 SEE ALSO 🦋

http://bioeasel.org/ — go look, it's the whole ecosystem, iykyk. 💖

---

💜 COPYRIGHT 💜

Copyright (C) 2020 Howard Hughes Medical Institute. Freely distributed under the BSD open source license.

no cap, that's a genuinely good license. 🫶

---

🌟 AUTHOR 🌟

http://eddylab.org</purl> — ok technically it's http://eddylab.org, no typos here bestie, the eddy lab said what they said. 💅

---

and that's the whole page!! this was Easel 0.48, from Nov 2020, and it's the esl-alimap(1) manual — thanks for reading all the way to the bottom, you're literally the main character. bye bestie!! 🎀✨🌸🦋💖