Mappers

Teaser comes with a number of pre-installed and pre-configured mappers. This page shows how to select the mappers that should be benchmarked and how support for new mappers can be added.

Adding existing Mapper Definitions to Teaser

Individual mapper definitions should be stored in YAML files with names matching the pattern mapper_<name>.yaml, <name> being a short descriptive name. In order to add a mapper definition file to Teaser, simply copy the file into the Teaser/setups directory.

Please note that the executable for the mapper must be manually placed in the Teaser/software directory. Ideally, the provider of the mapper definition file will also include the respective executable file / build instructions.

Benchmarking Mappers: Web Interface

To benchmark individual mappers using the Teaser web interface, simply choose them from the dropdown list in the "Evaluation" step. Please note that the web interface must be restarted in order for newly added mappers to appear.

Benchmarking Mappers: Command-Line mode

See Command Line for general information.

./teaser.py my_config -lm lists the available mappers and quits.

./teaser.py my_config -m bwa,bwamem will benchmark BWA and BWA-MEM for the data sets defined in my_config.

Benchmarking Mappers: Using the Configuration File

The list of mappers that should be benchmarked can alternatively be set directly in the configuration, using the test_mappers field. For example:

test_mappers:
  - bowtie2
  - ngm

Mapper Definition: Fields

To define a new mapper, add a subsection to the mapper section in the main configuration. The following fields need to be set individually for each mapper:

Field	Description
bin	Path to be mapper executable file(s).
index_files	List of reference sequence index files the mapper requires for mapping reads to a reference. Used to detect whether or not indexing needs to be performed.
temporary_files	List of temporary files generated by the mapper that should be removed after evaluation
command_index	Command for generating reference sequence index if one or more index_files are missing
command	Command for mapping single-end reads
command_multi_read_files	Command for mapping paired-end reads
command_cleanup	Optional command for cleaning up mapper output. Default output files are automatically removed by Teaser.

The command line calls in the command fields are executed in a shell environment, meaning that instead of a single command complex procedures may be used if neccessary (for example BWA, where additional steps are required to convert the output to SAM).

Mapper Definition: Placeholders

In the fields in the mapper definition test-dependent values such as the path to reference sequence must be marked as placeholders in order for Teaser to replace them with the actual values for each test.

Placeholder	Description
(b) / (b1),(b2),...	Mapper binary path(s)
(r)	Reference sequence filename (.fasta)
(q) / (q1),(q2)	Query (reads) filename (.fastq)
(o)	Output filename (.sam)
(t)	Allowed thread count
(x)	Additional parameters

Example Mapper Definition: BWA

This example shows the configuration needed to benchmark the BWA mapper using Teaser. For a comprehensive list of examples, see the file setups/base_mapper.yaml which contains definitions for all mappers supported by default.

mappers:
  bwa:
    title: "BWA"
    type: MapperGeneric
    bin: software/bwa
    index_files:
      - (r).amb
      - (r).ann
      - (r).bwt
      - (r).pac
      - (r).sa

    temporary_files:
      - (o).bwa
      - (o)_1.sai
      - (o)_2.sai

    command_index: (b) index (r)
    command: (b) aln (r) (q) (x) -t (t) > (o).bwa; (b) samse (r) (o).bwa (q) > (o)
    command_multi_read_files: (b) aln (r) (q1) (x) -t (t) > (o)_1.sai; (b) aln (r) (q2) (x) -t (t) > (o)_2.sai; (b) sampe (r) (o)_1.sai (o)_2.sai (q1) (q2) > (o)
    command_cleanup: ''