.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "PERM" "1" "April 2014" "Yangho Chen" "PerM"
.
.SH "NAME"
\fBperm\fR \- Efficient mapping of short reads with periodic spaced seeds
.
.P
If you have any usage questions, please email "yanghoch at usc dot edu"\.
.
.SH "SYNOPSIS"
To use the command line, type \fIperm\fR with the args in the order\.
.
.SH "EXAMPLES"
\fBFor single\-end reads:\fR
.
.P
\fBperm\fR \fIRef\fR \fIReads\fR [\fIoptions\fR]
.
.P
Examples:
.
.P
\fBperm\fR Ref\.fasta Reads\.fasta \-v 5 \-o out\.mapping \-u ummappedReads\.fa
.
.P
\fBperm\fR RefFilesList\.txt ReadsSetFilesList\.txt \-v 5 \-u unmappedReads\.fa \-E
.
.P
\fBperm\fR Ref\.fasta Reads\.csfasta \-v 5 \-m \-s my\.index \-\-delimiter \',\' \-\-seed F3
.
.P
\fBperm\fR my\.index SingleEndReads\.csfasta \-v 5 \-o out\.sam \-k 10 \-a ambiguous10\.csfasta
.
.P
\fBFor paired\-end reads:\fR
.
.P
\fBperm\fR \fIRef\fR \fB\-1\fR \fIF3_Reads\fR \fB\-2\fR \fIR3_Reads\fR [\fIoptions\fR]
.
.P
Examples:
.
.P
\fBperm\fR ref\.fa \-1 F3\.fa \-2 R3\.fa \-U 3000 \-L 100 \-v 5 \-A \-m \-s \-o out\.sam
.
.P
\fBperm\fR ref\.txt \-1 F3\.fq \-2 R3\.fq \-v 5 \-m \-s my\.index \-o out\.mapping \-\-seed F3
.
.P
\fBperm\fR my\.index \-1 F3\.fq \-2 R3\.fq \-U 3000 \-L 100 \-v 5 \-A \-o out\.sam
.
.P
\fBTo build an index only:\fR
.
.P
\fBperm\fR \fIRef\fR \fIRead_Length\fR \fB\-\-readFormat\fR <\.csfasta|\.fasta> \fB\-m\fR \fB\-s\fR \fIindex path\fR \fB\-\-seed\fR F3
.
.P
Example:
.
.P
\fBperm\fR hg18\.txt 50 \fB\-\-readFormat\fR \.csfasta \fB\-m\fR \fB\-s\fR hg18_50_SOLiD\.index
.
.SH "OPTIONS"
\fBRequired Arguments\fR
.
.IP "\(bu" 4
The reference file should be in FASTA format with the either the \fI\.fasta\fR, \fI\.fna\fR, or \fI\.fa\fR file extension\. For a transcriptome with multiple genes or isoforms as reference, concatenate all FASTA sequences in a single FASTA file\. Alternatively, if there are many files, for example one per chromosome, ex: chr1\.fa to chrY\.fa, list the FASTA filenames one per line in a file which has the \fI\.txt\fR extension\. The \fI\.txt\fR is important because PerM examines the file extension to know if the input file is a list of filenames\. The filenames need to include the file path (relative or absolute) unless the FASTA files are all in the same directory that PerM is run from\.
.
.IP "\(bu" 4
The read file(s) should be in the \.fasta, \.fastq, \.csfasta or \.csfastq format\. PerM parses a file according to its extension, or the format explicitly specified by the \fI\fB\-\-readFormat <format>\fR\fR flag\. If there are multiple read files, list each filename, one per line, in a \.txt file\. PerM takes it as the input and can map multiple read sets in parallel by [http://en\.wikipedia\.org/wiki/OpenMP OpenMP]\.
.
.IP "" 0
.
.P
\fBShort Options (grouped by related functionality)\fR
.
.TP
\fB\-A\fR
Output \fIall\fR alignments within the mismatch threshold (see \fI\-v\fR option), end\-to\-end\.
.
.TP
\fB\-B\fR
Output \fIbest\fR alignments in terms of mismatches in the threshold (see \fI\-v\fR 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 will be output\. \fI\-B\fR is the default mode if neither \fI\-A\fR or \fI\-B\fR is specified\.
.
.TP
\fB\-E\fR
Output only uniquely mapped reads \fIremaining after the \fIbest\fR down selection has been applied if applicable\fR\. When combined with the \fI\-A\fR option, only reads with a single alignment within the mismatch threshold (see \fI\-v\fR option) will be output\.
.
.TP
\fB\-v\fR
Maximum number of mismatches allowed (or allowed in each end for pair\-end reads)\. The default value is the number of mismatches that the seed used is fully sensitive to\.
.
.TP
\fB\-k\fR
Specifies maximum number of alignments to output\. The default value is 200 if the \-k flag is not given\. Alignments for reads mapping to more than the maximum number positions will not be output\. Use the \-a option to collect reads which exceeded the maximum\.
.
.TP
\fB\-t\fR
Number of bases at the 5\' end of each read to ignore\. For example, if the first 5 bases are used as a barcode or to index multiple samples together, use \-t 5\. If not specified, no initial bases will be ignored\.
.
.TP
\fB\-T\fR
Number of bases in each read to use, starting after any bases ignored by \-t option\. Later bases at the 3\' of the read are ignored\. For example, \-T 30 means use only first 30 bases (signals) after the any bases ignored due to the \-t option\.
.
.TP
\fB\-m\fR
Create the reference index without reusing the saved index even if available\.
.
.TP
\fB\-s\fR \fIpath\fR
Save the reference index to accelerate the mapping in the future\. If \fIpath\fR is not specified, the index will be created in the current working directory (i\.e\. where PerM is run from) using the default index name\. If \fIpath\fR is a directory, the index will be created in the specified directory using the default index name (directory must exist; it will not automatically be created)\. If \fIpath\fR is a file path, the index will be created with the specified name\.
.
.TP
\fB\-o\fR \fIfilepath\fR
Name of mapping output file when mapping a single read set\. The output file format will be either the \.mapping tab delimited text format or the SAM format as determined by the extension of the output filename\. For example {{{\-o out\.sam}}} will output in SAM format; {{{\-o /path/to/out\.mapping}}} will output in \.mapping format\. Use \fI\-\-outputFormat\fR to override this behavior\. The \fI\-o\fR option does not apply when multiple reads sets are being mapped at once to take advantage of multiple CPUs (cores); see the \fI\-d\fR option for that case\.
.
.TP
\fB\-d\fR \fIdirpath\fR
Output directory for mapping output files when mapping multiple read sets (output files will be named automatically)\. If the directory specified does not exist, the output directory will be created provided the parent directory exists\. If the \fI\-d\fR switch is not specified, files will be written to the directory PerM is run from\. Note: if \-d \fIfilepath\fR is specified when mapping a single read set, \fIdirpath\fR will be prepended to \fIfilepath\fR; however, this usage is not recommended\.
.
.TP
\fB\-a\fR \fIfilepath\fR
Create a FASTA (FASTQ) file for reads mapped to more positions than the threshold specified by \-k or the default of 200\.
.
.TP
\fB\-b\fR \fIfilepath\fR
Create a FASTA (FASTQ) file for reads that is shorter than expected length or with strange characters\.
.
.TP
\fB\-u\fR \fIfilepath\fR
Create a FASTA (FASTAQ) file of unmapped reads\. When a single read set is mapped, \fIfilename\fR specifies the name of the output file\. When multiple read sets are mapped, \fIfilename\fR is irrelevant and should be omitted; the files of unmapped sequences will automatically be named and created in the directory PerM is run from\.
.
.P
\fBLong Options\fR
.
.TP
\fB\-\-ambiguosReadOnly\fR
Output only ambiguous mapping to find repeats (similar regions within substitution threshold)\. When this option is specified, reads that mapped to over mapping number threshold that specified by \-k will still be printed\.
.
.TP
\fB\-\-ambiguosReadInOneLine\fR
utput reads mapped to more than k places in one line\. When this option is specified, reads that mapped to over mapping number threshold specified by \-k will still be printed but printed in one line\.
.
.TP
\fB\-\-noSamHeader\fR
Do not include a SAM header\. This makes it easier to concatenate multiple SAM output files\.
.
.TP
\fB\-\-includeReadsWN\fR
Map reads with equal or fewer N or \'\.\' bases than the specified threshold by encoding N or \'\.\' as A or 3\. Reads with more \'N\' will be discarded\. The default setting discards read with any \'N\'\.
.
.TP
\fB\-\-statsOnly\fR
Output the mapping statistics to stdout only, without saving alignments to files\.
.
.TP
\fB\-\-ignoreQS\fR
Ignore the quality scores in FASTQ or QUAL files\.
.
.TP
\fB\-\-printNM\fR
When quality scores are available, use this flag to print number of mismatches, instead of mismatch scores in mapping format\.
.
.TP
\fB\-\-seed\fR {F,,0,, | F,,1,, | F,,2,, | F,,3,, | F,,4,, | S,,11,, | S,,20,, | S,,12,,}
Specify the seed pattern\. The F,,0,,, F,,1,,, F,,2,,, F,,3,,, and F,,4,, seeds are fully sensitive to 0\-4 mismatches respectively\. The S,,11,, S,,20,, S,,12,, seeds are designed for the SOLiD sequencer\. An S,,kj,, seed is full sensitive to k adjacent mismatch pairs (SNP signature is color space) and j isolated mismatches\. See [http://code\.google\.com/p/perm/wiki/Algorithms the algorithm page] for more information about the seed patterns\.
.
.TP
\fB\-\-refFormat\fR \fI{fasta | list | index }\fR
Assume references sequence(s) are in the specified format, instead of guessing according to file\'s extension\.
.
.TP
\fB\-\-readFormat\fR |\fI{fasta | fastq | csfasta | csfastq}\fR
Assume reads are in the specified format, instead of guessing according to the file(s)\' extension\.
.
.TP
\fB\-\-outputFormat\fR \fI{ sam | mapping }\fR
Override the default output mapping format option or specify it explicitly when the output file extension is not \.sam or \.mapping\.
.
.TP
\fB\-\-delimiter\fR \fIchar\fR
\fIchar\fR is a character used as the delimiter to separate the the read id, and the additional info in the line with > when reading a FASTA or CSFASTA file\.
.
.TP
\fB\-\-log\fR \fIfilepath\fR
\fIfilepath\fR specifies the name of the log file which contains the mapping statistics that will also be printed on the screen\.
.
.TP
\fB\-\-forwardOnly\fR
Map reads to the forward strand only: (This is for SOLiD Strand specific sequencing)\.
.
.TP
\fB\-\-reverseOnly\fR
Map reads to the reverse strand only: (This is for SOLiD Strand specific sequencing)
.
.P
\fBOptions for Paired\-end Reads\fR
.
.P
PerM deals with mate\-paired reads by mapping each end separately\. All combinations of mated pairs mapping to the same reference sequence will be output if their separation are in the allowed ranged as specified by the \fI\-L\fR and \fI\-U\fR flags\.
.
.TP
\fB\-e\fR
Exclude ambiguous paired\.
.
.TP
\fB\-L\fR / \fB\-\-lowerBound\fR \fIInt\fR
lower bound for mate\-paired separation distance
.
.TP
\fB\-U\fR / \fB\-\-upperBound\fR \fIInt\fR
upper bound for mate\-paired separation distance
.
.P
The upper bound and lower bound can be negative, which may catch the re\-arrangement variations\. Use the \fB\-A\fR argument to avoid missing the correct pairs\. However, this may greatly increase the running time if both ends are in repetitive regions\.
.
.TP
\fB\-\-fr\fR
Map paired\-end reads to different strand only
.
.TP
\fB\-\-ff\fR
Map paired\-end reads to the same strand only
.
.TP
\fB\-\-printRefSeq\fR
Print the mapped reference paired sequence as the two last columns in \.mapping format\. | The default option output mapping in both the same or different strand\.
.
.SH "DEFAULT SETTINGS"
The following are the default settings when the corresponding command line option is not specified\. Please specify the option to change the default settings\.
.
.IP "\(bu" 4
Allow only two mismatches only in each end and use seed F,,2,, S,,11,, or F,,3,, ,selected according to the read lengths and types\.
.
.IP "\(bu" 4
Print the best alignments for each read in terms of the number of mismatches\.
.
.IP "\(bu" 4
Output files in \fB*\fR\.mapping format\.
.
.IP "\(bu" 4
Searches for a saved index with the default file name before building the new index\.
.
.IP "\(bu" 4
Won\'t save the index in file, unless {{{\-s}}} is specified\.
.
.IP "\(bu" 4
For paired end reads, the default allowed separation distance is 0\-3000 bp\. Change with the \fB\-L\fR and \fB\-U\fR options\.
.
.IP "" 0
.
.P
\fBParallel Mapping\fR
.
.P
PerM simultaneously maps multiple reads sets in a list by querying the same index\. It will detect how many CPUs (cores) are available and assign each of them a read set\. If a read set is done, the next read set in the list will be processed automatically\. Each read set will have its own mapping output file\. To better utilize all CPUs on a node, large reads set should be split into many small read sets and put in a list\. When multiple nodes are used in the same file system, the index should be pre\-built first by one node; the other nodes will read the pre\-built index without building index again\. Without pre\-built index, each machine will try to build its own index, wasting CPU time and storage space\.
.
.SH "Exit codes"
PerM sets the exit code to 0 upon successful completion, the normal Unix behavior\. If the program is terminated via Ctrl\-C (SIGINT), the exit code will be 2, the number for SIGINT (see \fBman kill\fR)\. If you invoke PerM from another language, you can check the return code and do something intelligent\. Here is a Perl pseudo\-code example:
.
.IP "" 4
.
.nf

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\.\en\en";
# Maybe do some cleanup such as deleting the small files the read file was
# split into for parallel processing\.
exit($ec);
  }
}
.
.fi
.
.IP "" 0
.
.SH "Use PerM on Galaxy"
Thanks to Prof Anton Nekrutenko and Kelly Vincent at PSU, you can now use PerM on [http://test\.g2\.bx\.psu\.edu/ Galaxy\'s \fItest\fR server]\. Follow the hyperlink to Galaxy\'s page, and click NGS:Mapping in the tool menu\. Please choose \fIMap with PerM for SOLiD and Illumina\fR\. You can upload your own reference or use the pre\-built hg19 index in the system\. Please email me if you encounter any difficulties\. Once the system proves its stability, it will be moved to Galaxy\'s main server with more pre\-built reference index\.
.
.SH "Unit Test"
When PerM was developed, a unit cppUnit test module was also prepared\. If you are interested in the test code for PerM, please email me\.