esl-alimerge(1)

💖 esl-alimerge — the Easel Manual, bestie edition 💖

okay so you found esl-alimerge and you're like "what does this do" and honestly? it's giving alignment matchmaker. it merges multiple alignments into one, using their reference (RF) annotation as the vibe check. part of the Easel crew. let's get into it 🫶

---

✨ NAME ✨

esl-alimerge — merge alignments based on their reference (RF) annotation 💅

---

🦋 SYNOPSIS 🦋

esl-alimerge [options] alifile1 alifile2
  (merge two alignment files)

esl-alimerge --list [options] listfile
  (merge many alignment files listed in a file)

like, either you hand it two alignment files directly, or you hand it a list of them. two moods, both iconic ✨

---

🌸 DESCRIPTION 🌸

esl-alimerge reads more than one input alignment, merges them into a single alignment, and outputs it. that's the whole job. simple, effective, main character energy 👑

the rules of the game (input requirements)

• all input alignments must be in Stockholm format. no exceptions, no cap.
• all alignments must have reference (#=GC RF) annotation. if you don't have it, this whole thing falls apart 😭
• that RF annotation has to be identical in all alignments once you remove the gap characters from it — and those gap characters are '.', '-', and '_'.

why does that matter? because it means alignments with different numbers of total columns can still be merged together, as long as the RF annotation lines up. think alignments made by successive runs of the cmalign program from the INFERNAL package, all using the same CM. that's the classic use case, iykyk.

oh and heads up: columns that have a gap character in the RF annotation are called insert columns. remember that, it comes up again 💀

what happens to your sequences

all sequence data in all input alignments will be included in the output alignment, no matter what output format you pick (see --outformat down below).

however — and this is the part that lowkey surprises people — sequences in the merged alignment will usually have more gaps ('.') than they did in their own original input alignments. why? because esl-alimerge has to add 100% gap columns to each individual input alignment so that insert columns from the other input alignments have somewhere to live in the merged result. it's making room. it's being polite. it's giving host energy 🎀

annotation transfer (Stockholm or Pfam output only)

if your output format is Stockholm or Pfam, annotation gets carried over from the inputs into the merged alignment, like this:

• per-sequence (#=GS) annotation → transferred ✨
• per-residue (#=GR) annotation → transferred ✨
• per-file (#=GF) annotation → transferred if it's present and identical in all alignments
• per-column (#=GC) annotation → transferred if it's present and identical in all alignments once all insert positions have been removed and the #=GC annotation includes zero non-gap characters in insert columns

that last one is a mouthful but it's precise, okay, don't shoot the messenger 🙈

the --list <f> lifestyle

with the --list <f> option, <f> is a file listing alignment files to merge. in that list file:

• blank lines → ignored
• lines that start with # (comments) → ignored
• every data line → one single word: the name of an alignment file to merge

all alignments in each file will be merged. so you can batch it up, no problem 💅

the --small era (memory saving mode)

with --small, esl-alimerge operates in memory saving mode, and the RAM required for the merge becomes minimal — like, should only be a few Mb — and independent of the alignment sizes. obsessed.

but: to use --small, all alignments must be in Pfam format (non-interleaved, 1 line/sequence Stockholm format). you can reformat alignments to Pfam using the esl-reformat Easel miniapp. 🧚

without --small, the required RAM will be roughly equal to the size of the final merged alignment file — which will necessarily be at least the summed size of all the input alignment files you're merging, and sometimes several times larger. yeah. 😭

so if you're merging large alignments, or esl-alimerge is being slow and tragic, try reformatting to Pfam and using --small. genuinely the move.

---

💅 OPTIONS 💅

• -h — print brief help; includes the version number and a summary of all options, including the expert options. cute and useful.
• -o <f> — output the merged alignment to file <f> instead of to stdout.
• -v — be verbose; print info on the size of the alignments being merged, and the annotation transferred to the merged alignment, to stdout. ⚠️ this option can only be used in combination with the -o option (so the printed info doesn't corrupt the output alignment file). respect the constraint bestie.
• --small — operate in memory saving mode. required RAM will be independent of the sizes of the alignments to merge, instead of roughly the size of the eventual merged alignment. when enabled, all alignments must be in Pfam Stockholm (non-interleaved 1 line/seq) format; see esl-reformat(1). the output alignment will be in Pfam format. 🌈
• --rfonly — only include columns that are not gaps in the GC RF annotation in the merged alignment.
• --outformat <s> — write the output alignment in format <s>. common choices for <s> include: stockholm, a2m, afa, psiblast, clustal, phylip. the string <s> is case-insensitive (a2m or A2M both work). default is stockholm. ⭐
• --rna — specify that the input alignments are RNA alignments. by default esl-alimerge will try to autodetect the alphabet, but if the alignment is sufficiently small it may be ambiguous. this option defines the alphabet as RNA.
• --dna — specify that the input alignments are DNA alignments.
• --amino — specify that the input alignments are protein alignments.

---

🔥 SEE ALSO 🔥

http://bioeasel.org/

---

👑 COPYRIGHT 👑

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

---

💜 AUTHOR 💜

http://eddylab.org

---

and that's the whole page, bestie 🫶 this one came from Easel 0.48, dated Nov 2020 — go forth and merge those alignments, you absolute icon 🎀✨