.TH RABEMA_EVALUATE 1 "" "rabema_evaluate 1.2.9 [tarball]" ""
.SH NAME
rabema_evaluate \- RABEMA Evaluation
.SH SYNOPSIS
\fBrabema_evaluate\fP [\fIOPTIONS\fP] \fB--reference\fP \fIREF.fa\fP \fB--in-gsi\fP \fIIN.gsi\fP \fB--in-bam\fP \fIMAPPING.{sam,bam}\fP
.SH DESCRIPTION
Compare the SAM/bam output \fIMAPPING.sam\fP/\fIMAPPING.bam\fP of any read mapper against the RABEMA gold standard previously built with \fBrabema_build_gold_standard\fP.  The input is a reference FASTA file, a gold standard interval (GSI) file and the SAM/BAM input to evaluate.
.sp
The input SAM/BAM file must be \fIsorted by queryname\fP.  The program will create a FASTA index file \fIREF.fa.fai\fP for fast random access to the reference.
.SH OPTIONS
.TP
\fB-h\fP, \fB--help\fP
Display the help message.
.TP
\fB--version\fP
Display version information.
.TP
\fB-v\fP, \fB--verbose\fP
Enable verbose output.
.TP
\fB-vv\fP, \fB--very-verbose\fP
Enable even more verbose output.
.SS Input / Output:
.TP
\fB-r\fP, \fB--reference\fP \fIINPUT_FILE\fP
Path to load reference FASTA from. Valid filetypes are: \fI.sam[.*]\fP, \fI.raw[.*]\fP, \fI.gbk[.*]\fP, \fI.frn[.*]\fP, \fI.fq[.*]\fP, \fI.fna[.*]\fP, \fI.ffn[.*]\fP, \fI.fastq[.*]\fP, \fI.fasta[.*]\fP, \fI.faa[.*]\fP, \fI.fa[.*]\fP, \fI.embl[.*]\fP, and \fI.bam\fP, where * is any of the following extensions: \fIgz\fP, \fIbz2\fP, and \fIbgzf\fP for transparent (de)compression.
.TP
\fB-g\fP, \fB--in-gsi\fP \fIINPUT_FILE\fP
Path to load gold standard intervals from. If compressed using gzip, the file will be decompressed on the fly. Valid filetype is: \fI.gsi[.*]\fP, where * is any of the following extensions: \fIgz\fP for transparent (de)compression.
.TP
\fB-b\fP, \fB--in-bam\fP \fIINPUT_FILE\fP
Path to load the read mapper SAM or BAM output from. Valid filetypes are: \fI.sam[.*]\fP and \fI.bam\fP, where * is any of the following extensions: \fIgz\fP, \fIbz2\fP, and \fIbgzf\fP for transparent (de)compression.
.TP
\fB--out-tsv\fP \fIOUTPUT_FILE\fP
Path to write the statistics to as TSV. Valid filetype is: \fI.rabema_report_tsv\fP.
.TP
\fB--dont-check-sorting\fP
Do not check sortedness (by name) of input SAM/BAM files.  This is required if the reads are not sorted by name in the original FASTQ files.  Files from the SRA and ENA generally are sorted.
.SS Benchmark Parameters:
.TP
\fB--oracle-mode\fP
Enable oracle mode.  This is used for simulated data when the input GSI file gives exactly one position that is considered as the true sample position.  For simulated data.
.TP
\fB--only-unique-reads\fP
Consider only reads that a single alignment in the mapping result file. Useful for precision computation.
.TP
\fB--match-N\fP
When set, N matches all characters without penalty.
.TP
\fB--distance-metric\fP \fISTRING\fP
Set distance metric.  Valid values: hamming, edit.  Default: edit. One of \fIhamming\fP and \fIedit\fP. Default: \fIedit\fP.
.TP
\fB-e\fP, \fB--max-error\fP \fIINTEGER\fP
Maximal error rate to build gold standard for in percent.  This parameter is an integer and relative to the read length.  The error rate is ignored in oracle mode, here the distance of the read at the sample position is taken, individually for each read.  Default: 0 Default: \fI0\fP.
.TP
\fB-c\fP, \fB--benchmark-category\fP \fISTRING\fP
Set benchmark category.  One of {all, all-best, any-best.  Default: all One of \fIall\fP, \fIall-best\fP, and \fIany-best\fP. Default: \fIall\fP.
.TP
\fB--trust-NM\fP
When set, we trust the alignment and distance from SAM/BAM file and no realignment is performed.  Off by default.
.TP
\fB--extra-pos-tag\fP \fISTRING\fP
If the CIGAR string is absent, the missing alignment end position can be provided by this BAM tag.
.TP
\fB--ignore-paired-flags\fP
When set, we ignore all SAM/BAM flags related to pairing.  This is necessary when analyzing SAM from SOAP's soap2sam.pl script.
.TP
\fB--DONT-PANIC\fP
Do not stop program execution if an additional hit was found that indicates that the gold standard is incorrect.
.SS Logging:
.TP
\fB--show-missed-intervals\fP
Show details for each missed interval from the GSI.
.TP
\fB--show-invalid-hits\fP
Show details for invalid hits (with too high error rate).
.TP
\fB--show-additional-hits\fP
Show details for additional hits (low enough error rate but not in gold standard.
.TP
\fB--show-hits\fP
Show details for hit intervals.
.TP
\fB--show-try-hit\fP
Show details for each alignment in SAM/BAM input.
.sp

.sp
The occurrence of "invalid" hits in the read mapper's output is not an error.  If there are additional hits, however, this shows an error in the gold standard.
.SH RETURN VALUES
A return value of 0 indicates success, any other value indicates an error.
.SH MEMORY REQUIREMENTS
From version 1.1, great care has been taken to keep the memory requirements as low as possible.
.sp
The evaluation step needs to store the whole reference sequence in memory but little more memory.  So, for the human genome, the memory requirements are below 4 GB, regardless of the size of the GSI or SAM/BAM file.
.SH REFERENCES
M. Holtgrewe, A.-K. Emde, D. Weese and K. Reinert.  A Novel And Well-Defined Benchmarking Method For Second Generation Read Mapping, BMC Bioinformatics 2011, 12:210.
.TP
\fIhttp://www.seqan.de/rabema\fP
RABEMA Homepage
.TP
\fIhttp://www.seqan.de/mason\fP
Mason Homepage