MAF_PARSE(1)

💖 MAF_PARSE 💖

okay bestie, gather round, because we're talking about maf_parse from the User Commands corner of the manual, and honestly? she's that girl. 💅

---

✨ NAME ✨

maf_parse — Reads a MAF file and perform various operations on it.

---

🌸 DESCRIPTION 🌸

So basically, maf_parse reads a MAF file and performs various operations on it. It parses block-by-block whenever it can instead of being dramatic and storing the entire alignment in memory, which is giving main character energy but like, efficiently. 🧚

She can extract a sub-alignment from an alignment — by row or by column, she's flexible like that. She can extract features given a GFF, BED, or genepred file. She can even pull out sub-features like CDS1,2,3 or 4d sites. And she can do all the little functions you'd want, like gap stripping or re-ordering of sequences. Iconic. 👑

She's capable of reading and writing in a few common formats, no cap — but here's the tea: she will not load input or output alignments into memory if the output format is MAF. So that's the tradeoff, and it's a good one.

---

🎀 OPTIONS 🎀

💾 Output format

• --out-format, -o MAF|PHYLIP|FASTA|MPM|SS (Default MAF) — the output file format, periodt. Heads up: SS format is only available un-ordered. Also note that some options — the ones that involve reversing alignments based on strand, or stripping gaps — cannot be output in MAF format and use FASTA by default. And one more thing: when the output format is not MAF, the entire output must be loaded into memory. 😭
• --pretty, -p — pretty-print the alignment (uses '.' when a character matches the corresponding character in the first sequence). Lowkey ignored if --out-format SS is selected. ✨

---

🧬 Obtaining sub-alignments and re-ordering rows

• --start, -s <start_col> — start index of the sub-alignment (indexing starts with 1, bestie, not 0). Coordinates are in terms of the reference sequence unless the --no-refseq option is used, in which case they're in terms of alignment columns. Default is 1.
• --end, -e <end_col> — end index of the sub-alignment. Default is the length of the alignment. Coordinates are defined the same way as the --start option, above. 🫶
• --seqs, -l <seq_list> — comma-separated list of sequences to include (that's the default) or exclude (if you use --exclude). You can indicate them by sequence number or name — and numbering starts with 1 and is evaluated after --order is applied. iykyk.
• --exclude, -x — exclude rather than include the specified sequences. That's it, that's the vibe. 🙈
• --order, -O <name_list> — change the order of the rows in the alignment to match the sequence names specified in name_list. The first name in the alignment becomes the reference sequence. Glow-up for your rows. 💅
• --no-refseq, -n — do not assume the first sequence in the MAF is the refseq. Instead, use coordinates given by absolute position in the alignment (starting from 1). 🔥

---

✂️ Splitting into multiple MAFs by length

• --split, -S length — split the MAF into pieces by length, and put the output in outRootX.maf, where X=1,2,...,numPieces. The outRoot can be modified with --out-root, and the minimum number of digits in X can be modified with --out-root-digits. She splits between blocks, so that each output file does not exceed the specified length. By default, length is counted by the distance spanned in the alignment by the refseq, unless --no-refseq is specified. ✨
• --out-root, -r <name> — filename root for output files produced by --split (default "maf_parse").
• --out-root-digits, -d <numdigits> — (for use with --split). The minimum number of digits used to index each output file produced by split. 🔢

---

🔍 Extracting features from MAF

• --features, -g <fname> — the annotations file. May be GFF, BED, or genepred format. Coordinates are assumed to be in the frame of the first sequence of the alignment (the reference sequence). By default, this outputs the subset of the MAF which are labeled in the annotations file. But it can be used with --by-category, --by-group, and/or --do-cats to split the MAF by annotation type. Or, if used with --mask-features, it's only used to determine regions to mask. Implies --strip-i-lines, --strip-e-lines. 😌
• --by-category, -L — (requires --features). Split by category, as defined by the annotations file and (optionally) the category map (see --catmap).
• --do-cats, -C <cat_list> — (for use with --by-category) output sub-alignments for only the specified categories.
• --catmap, -c <fname>|<string> — (optionally use with --by-category) mapping of feature types to category numbers. You can either give a filename or an "inline" description of a simple category map, e.g.

--catmap "NCATS = 3 ; CDS 1-3"

or

--catmap "NCATS = 1; UTR 1"

• --by-group, -P <tag> — (requires --features). Split by groups in the annotation file, as defined by the specified tag. 🌈

---

🎚️ Masking by quality score

• --mask-bases, -b <qscore> — mask all bases with quality score <= n. Note that n is in the same units as displayed in the MAF (ranging from 0-9), and represents min(9, floor(PHRED_score/5)). Bases without any quality score will not be masked. 💀
• --masked-file, -m <filename> — (for use with --mask-bases). Write a file containing all the regions masked for low quality. The file will be in 0-based coordinates relative to the refseq, with an additional column giving the name of the species masked. Note that low-quality bases masked at alignment columns with a gap in the reference sequence may not be represented in the output file. 😭
• --mask-features -M <spec> — (requires --features). Mask all bases annotated in features in the given species (can be a comma-delimited list of species). Note that coordinates are always in terms of refseq, even if a different species is being masked. 🌸

---

🍓 Other

• --strip-i-lines, -I — remove lines in the MAF starting with i.
• --strip-e-lines, -E — remove lines in the MAF starting with e.
• --help, -h — print this help message. She's always there for you, bestie. 🫶

---

vibe check passed: every flag, every default, every coordinate rule, and every little caveat is still in there. Nothing got dropped, nothing got invented. 💖

---

and that's a wrap on maf_parse, written by the maf_parse 1.4 girlies back in May 2016 — yes she's been slaying since 2016 and she's still iconic. go parse something, bestie, you've got this 💅✨🦋