PERM(1)

🦋 PERM(1) · PerM 🦋

✨ NAME ✨

okay bestie, perm is the tool, and its whole thing is efficient mapping of short reads with periodic spaced seeds 🧚

If you have any usage questions, please email "yanghoch at usc dot edu". 💌

🎀 SYNOPSIS 🎀

To use the command line, type perm with the args in the order. 💖

💅 EXAMPLES 💅

For single-end reads:

perm Ref Reads [options]

Examples:

perm Ref.fasta Reads.fasta -v 5 -o out.mapping -u ummappedReads.fa
perm RefFilesList.txt ReadsSetFilesList.txt -v 5 -u unmappedReads.fa -E
perm Ref.fasta Reads.csfasta -v 5 -m -s my.index --delimiter ´,´ --seed F3
perm my.index SingleEndReads.csfasta -v 5 -o out.sam -k 10 -a ambiguous10.csfasta

For paired-end reads:

perm Ref -1 F3_Reads -2 R3_Reads [options]

Examples:

perm ref.fa -1 F3.fa -2 R3.fa -U 3000 -L 100 -v 5 -A -m -s -o out.sam
perm ref.txt -1 F3.fq -2 R3.fq -v 5 -m -s my.index -o out.mapping --seed F3
perm my.index -1 F3.fq -2 R3.fq -U 3000 -L 100 -v 5 -A -o out.sam

To build an index only:

perm Ref Read_Length --readFormat <.csfasta|.fasta> -m -s index path --seed F3

Example:

perm hg18.txt 50 --readFormat .csfasta -m -s hg18_50_SOLiD.index

🌸 OPTIONS 🌸

💖 Required Arguments

• Reference file: this should be FASTA with the .fasta, .fna, or .fa extension. For a transcriptome with multiple genes or isoforms as the reference, concatenate all the FASTA sequences into one single FASTA file. If you've got lots of files (like one per chromosome, ex: chr1.fa to chrY.fa), list the FASTA filenames one per line in a file with the .txt extension. The .txt part is super important because PerM checks the file extension to figure out whether the input is a list of filenames. Filenames need to include the file path (relative or absolute) unless all the FASTA files live in the same directory PerM is run from.
• Read files: these should be .fasta, .fastq, .csfasta or .csfastq. PerM parses a file based on its extension, or on the format you explicitly set with --readFormat <format>. If you've got multiple read files, list each filename one per line in a .txt file. PerM takes that list as the input and can map multiple read sets in parallel using OpenMP (http://en.wikipedia.org/wiki/OpenMP).

🧚 Short Options (grouped by related functionality)

• -A — output all alignments within the mismatch threshold (see -v option), end-to-end. ✨
• -B — output the best alignments in terms of mismatches within the threshold (see -v option). For example, if a read has no perfect match alignments, two single base mismatch alignments, and additional alignments with more mismatches, only the two single base mismatch alignments get output. -B is the default mode if you don't specify -A or -B. 👑
• -E — output only the uniquely mapped reads left over after the best down selection has been applied (if applicable). When you combine it with -A, only reads with a single alignment within the mismatch threshold (see -v option) get output. 🦋
• -v — the maximum number of mismatches allowed (or allowed in each end for paired-end reads). The default is the number of mismatches that the seed you're using is fully sensitive to. 💜
• -k — the max number of alignments to output. If you don't give -k, the default is 200. Alignments for reads mapping to more than that max number of positions won't be output. Use the -a option to collect the reads that went over the max. 🙈
• -t — the number of bases at the 5´ end of each read to ignore. For example, if the first 5 bases are a barcode or you're using them to index multiple samples together, use -t 5. If you don't specify it, no initial bases get ignored. 🌈
• -T — the number of bases in each read to use, starting after any bases ignored by the -t option. Later bases at the 3´ end of the read get ignored. For example, -T 30 means use only the first 30 bases (signals) after any bases ignored due to the -t option. 🍓
• -m — create the reference index without reusing a saved index, even if one is available. 🔥
• -s path — save the reference index so mapping is faster next time. If you don't specify a path, the index gets created in your current working directory (aka wherever you ran PerM from) using the default index name. If the path is a directory, the index gets created in that directory with the default index name (the directory has to already exist, it won't be made for you). If the path is a file path, the index gets created with that exact name. 💅
• -o filepath — the name of the mapping output file when you're mapping a single read set. The format is either the .mapping tab-delimited text format or SAM, depending on the extension of the output filename. For example, -o out.sam outputs SAM, and -o /path/to/out.mapping outputs .mapping format. Use --outputFormat to override this behavior. The -o option doesn't apply when you map multiple read sets at once to take advantage of multiple CPUs (cores), so check the -d option for that case. 🎀
• -d dirpath — the output directory for mapping output files when you're mapping multiple read sets (the output files get named automatically). If the directory doesn't exist, it'll be created as long as the parent directory exists. If you don't specify -d, files get written to the directory PerM is run from. Heads up: if you use -d filepath while mapping a single read set, dirpath gets prepended to filepath.

⚠️ That -d usage is not recommended, so maybe just avoid it. 🙈

• -a filepath — create a FASTA (FASTQ) file for reads mapped to more positions than the threshold set by -k (or the default of 200). 🧁
• -b filepath — create a FASTA (FASTQ) file for reads that are shorter than the expected length or have strange characters. 🫶
• -u filepath — create a FASTA/FASTQ file of unmapped reads. When you map a single read set, the filename you give is the name of the output file. When you map multiple read sets, the filename is irrelevant and should be left off. The unmapped sequence files get named and created automatically in the directory PerM is run from. 🌸

⏭️ part 2 picks up with the long options, so stay tuned 🫶

✨ DEFAULT SETTINGS ✨

okay so these are the defaults PerM uses when you don't pass the matching command line option 💅 if you want something different, you gotta specify the option yourself bestie 🫶

• Mismatch rules 🎀 — PerM allows only two mismatches, and only in each end, using seed F,,2,,, S,,11,,, or F,,3,,. Which one it picks depends on your read lengths and types.
• Output ranking 🦋 — it prints the best alignments for each read, ranked by the number of mismatches.
• File format 📄 — output files come out in *.mapping format.
• Saved index check 🔍 — it looks for a saved index under the default file name before it builds a new one.
• Index saving 🙅‍♀️ — it won't save the index to a file unless you specify -s.
• Paired end distance 📏 — for paired end reads, the default allowed separation distance is 0-3000 bp. Change it with the -L and -U options ✨

🍓 Parallel Mapping

this one is lowkey iconic 👑 PerM can map multiple read sets from a list at the same time by querying the same index. It detects how many CPUs (cores) are available and gives each one a read set. When a read set finishes, the next one in the list gets processed automatically 🔥 each read set gets its own mapping output file.

To make the most of all your CPUs on a node, split large read sets into lots of small ones and put those in a list 🧚 if you're using multiple nodes on the same file system, have one node pre-build the index first. The other nodes will read that pre-built index instead of building their own. Without a pre-built index, every machine tries to build its own, which wastes CPU time and storage space 💀

🌸 Exit codes

PerM exits with 0 on successful completion, which is the normal Unix behavior ✅ if you terminate it with Ctrl-C (SIGINT), the exit code is 2, the number for SIGINT (see man kill) 🙈 if you call PerM from another language, you can check the return code and do something smart with it. Here's a Perl pseudo-code example, bestie 💜

    while (... some sort of loop ...) {
      my $cmd = "PerM ... arguments and switches";
      my $ec = system($cmd);
      if ($ec == 2) {
    print STDERR "PerM terminated via Ctrl-C. Stopping run.\n\n";
    # Maybe do some cleanup such as deleting the small files the read file was
    # split into for parallel processing.
    exit($ec);
      }
    }

🧚 Use PerM on Galaxy

huge shoutout to Prof Anton Nekrutenko and Kelly Vincent at PSU 🫶 you can now use PerM on Galaxy's test server at http://test.g2.bx.psu.edu/. Follow the link to Galaxy's page and click NGS:Mapping in the tool menu. Choose Map with PerM for SOLiD and Illumina. You can upload your own reference or use the pre-built hg19 index already in the system 🌈 if you run into any difficulties, email me. Once the system proves it's stable, it'll move to Galaxy's main server with more pre-built reference indexes ⭐

💜 Unit Test

when PerM was being developed, a unit cppUnit test module was prepared too 🎀 if you're curious about the test code for PerM, email me and I'll share it 🦋

---

and that's a wrap on PerM(1)! 🌸 written by Yangho Chen back in April 2014, so the whole vibe is a little vintage but the info is still chef's kiss 💅✨