NAME

       rabema_evaluate - RABEMA Evaluation

       SYNOPSIS

              rabema_evaluate  [OPTIONS]  --reference REF.fa --in-gsi IN.gsi --in-sam MAPPING.sam
              rabema_evaluate [OPTIONS] --reference REF.fa --in-gsi IN.gsi --in-bam MAPPING.bam

       DESCRIPTION

              Compare the SAM/bam output MAPPING.sam/MAPPING.bam of any read mapper  against  the
              RABEMA gold standard previously built with rabema_build_gold_standard. The input is
              a reference FASTA file, a gold standard interval (GSI) file and the  SAM/BAM  input
              to evaluate.

              The input SAM/BAM file must be sorted by queryname. The program will create a FASTA
              index file REF.fa.fai for fast random access to the reference.

       -h, --help

              Displays this help message.

       --version

              Display version information

       -v, --verbose

              Enable verbose output.

       -vv, --very-verbose

              Enable even more verbose output.

              Input / Output:

       -r, --reference FASTA

              Path to load reference FASTA from. Valid filetypes are: fa and fasta.

       -g, --in-gsi GSI

              Path to load gold standard intervals from. If compressed using gzip, the file  will
              be decompressed on the fly. Valid filetypes are: gsi and gsi.gz.

       -s, --in-sam SAM

              Path to load the read mapper SAM output from. Valid filetype is: sam.

       -b, --in-bam BAM

              Path to load the read mapper BAM output from. Valid filetype is: bam.

       --out-tsv TSV

              Path to write the statistics to as TSV. Valid filetype is: tsv.

              Benchmark Parameters:

       --oracle-mode

              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.

       --only-unique-reads

              Consider only reads that a single alignment in the mapping result file. Usefull for
              precision computation.

       --match-N

              When set, N matches all characters without penalty.

       --distance-metric METRIC

              Set distance metric. Valid values: hamming, edit. Default: edit. One of hamming and
              edit. Default: edit.

       -e, --max-error RATE

              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: 0.

       -c, --benchmark-category CAT

              Set benchmark category. One of {all, all-best, any-best. Default: all One  of  all,
              all-best, and any-best. Default: all.

       --trust-NM

              When  set, we trust the alignment and distance from SAM/BAM file and no realignment
              is performed. Off by default.

       --ignore-paired-flags

              When set, we ignore all SAM/BAM flags related to pairing. This  is  necessary  when
              analyzing SAM from SOAP's soap2sam.pl script.

       --DONT-PANIC

              Do  not  stop  program execution if an additional hit was found that indicates that
              the gold standard is incorrect.

              Logging:

       --show-missed-intervals

              Show details for each missed interval from the GSI.

       --show-invalid-hits

              Show details for invalid hits (with too high error rate).

       --show-additional-hits

              Show details for additional hits (low enough error rate but not in gold standard.

       --show-hits

              Show details for hit intervals.

       --show-try-hit

              Show details for each alignment in SAM/BAM input.

              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.

       RETURN VALUES

              A return value of 0 indicates success, any other value indicates an error.

       MEMORY REQUIREMENTS

              From  version 1.1, great care has been taken to keep the memory requirements as low
              as possible.

              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.

       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.

              http://www.seqan.de/rabema

              RABEMA Homepage

              http://www.seqan.de/mason

              Mason Homepage

       VERSION

              rabema_evaluate version: 1.2.0 Last update March 14, 2013