Bastien
Chevreux
bach@chevreux.org

> Solomon Short

> The manual only makes sense after you learn the program.

# MIRA3 reference

aka: The extended man page of MIRA, a genome and EST/RNASeq sequence assembly system for Sanger, 454, IonTorrent, PacBio and Illumina/Solexa sequencing data

## Synopsis

mira -chrv manifest-file manifest-file ...

## Important notes

For an easy introduction on how to use MIRA, a number of tutorials with step-by-step instructions are available:

1. `mira_usage` for basic Sanger assembly

2. `mira_454` for basic 454 assembly

3. `mira_iontor` for basic Ion Torrent assembly

4. `mira_pacbio` for basic assembly of sequences from Pacific Bioscience

5. `mira_solexadev` for basic mapping assembly of Solexa data

6. `mira_est` for some advice concerning assembly of EST sequence (and miraSearchESTSNPs)

7. `mira_hard` some notes on how to assemble 'hard' data sets: EST data sets or genome projects for eukaryotes, but some prokaryotes also qualify for this

8. `mira_faq` with some frequently asked question

## Requirements

To use MIRA itself, one doesn't need very much:

- Sequence data in EXP, CAF, PHD, FASTA or FASTQ format

- Optionally: ancillary information in NCBI traceinfo XML format; ancillary information about strains in tab delimited format, vector screen information generated with `ssaha2` or `smalt`.

- Some memory and disk space. Actually lots of both if you are venturing into 454 or Solexa.

## Working modes

MIRA has three basic working modes: genome, EST or EST-reconstruction-and-SNP-detection. From version 2.4 on, there is only executable which supports all modes. The name with which this executable is called defines the working mode:

1. `mira` for assembly of genomic data as well as assembly of EST data from one or multiple strains / organisms

   and

2. `miraSearchESTSNPs` for assembly of EST data from different strains (or organisms) and SNP detection within this assembly. This is the former `miraEST` program which was renamed as many people got confused regarding whether to use MIRA in est mode or miraEST.

Note that `miraSearchESTSNPs` is usually realised as a link to the `mira` executable, the executable decides by the name it was called with which module to start.

## Configuring an assembly: files and parameters

All the configuration needed for an assembly is done in one (or several) configuration file(s): the manifest files. This encompasses things like what kind of assembly you want to perform (genome or EST / RNASeq, mapping or de-novo etc.pp) or which data files contain the sequences you want to assemble (and in which format these are).

### The manifest file: introduction

A manifest file can be seen as a two part configuration file for an assembly: the first part contains some general information while the second part contains information about the sequencing data to be loaded. Examples being always easier to follow than long texts, here's an example for a de-novo assembly with 454 data:

    # Example for a manifest describing a simple 454 de-novo assembly

    # A manifest file can contain comment lines, these start with the #-character

    # First part: defining some basic things
    # In this example, we just give a name to the assembly
    #  and tell MIRA it should assemble a genome de-novo in accurate mode
    # As special parameter, we want to use 4 threads in parallel (where possible)

    project = MyFirstAssembly
    job = genome,denovo,accurate
    parameters = -GE:not=4

    # The second part defines the sequencing data MIRA should load and assemble
    # The data is logically divided into "readgroups": this reflects the
    #  ... that read sequences ...

    readgroup = SomeUnpaired454ReadsIGotFromTheLab
    data = TCMFS456ZH345.fastq TQF92GT7H34.fastq
    technology = 454

To make things a bit more interesting, here's an example for a typical standard setup nowadays: unpaired 454 plus a paired-end Illumina + a mate-pair Illumina. To make things even more interesting, the data for Illumina sequences is not given for every single file, but with wildcards:

    # Example for a manifest describing a de-novo assembly with
    # unpaired 454, paired-end Illumina and mate-pair Illumina

    # First part: defining some basic things
    # In this example, we just give a name to the assembly
    #  and tell MIRA it should assemble a genome de-novo in accurate mode
    # As special parameter, we want to use 4 threads in parallel (where possible)

    project = MyFirstAssembly
    job = genome,denovo,accurate
    parameters = -GE:not=4

    # The second part defines the sequencing data MIRA should load and assemble
    # The data is logically divided into "readgroups": this reflects the
    #  ... that read sequences ...

    readgroup = SomeUnpaired454ReadsIGotFromTheLab
    data = TCMFS456ZH345.fastq TQF92GT7H34.fastq
    technology = 454

    readgroup = SomePairedEndIlluminaReadsIGotFromTheLab
    data = datape*.fastq
    technology = solexa
    templatesize = 100 300
    segmentplacement = ---> <---
    segmentnaming = solexa

    readgroup = SomeMatePairIlluminaReadsIGotFromTheLab
    data = datamp*.fastq
    technology = solexa
    templatesize = 2800 3200
    segmentplacement = <--- --->
    segmentnaming = solexa

### The manifest file: basics

The first part of an assembly manifest contains the very basic information the assembler needs to have to know what you want it to do. This part consists of exactly three entries:

1. project = tells the assembler the name you wish to give to the whole assembly project. MIRA will use that name throughout the whole assembly for naming directories, files and a couple of other things.

   You can name the assembly anyway you want, you should however restrain yourself and use only alphanumeric characters and perhaps the characters plus, minus and underscore. Using slashes or backslashes here is a recipe for catastrophe.

2. job = tells the assembler what kind of data it should expect and how it should assemble it.

   You need to make your choice mainly in three steps and in the end concatenate your choices to the job= entry of the manifest:

   1. are you building an assembly from scratch (choose: denovo) or are you mapping reads to an existing backbone sequence (choose: mapping)? Pick one. Leaving this out automatically chooses denovo as default.

   2. are the data you are assembling forming a larger contiguous sequence (choose: genome) or are you assembling small fragments like in EST or mRNA libraries (choose: est)? Pick one. Leaving this out automatically chooses genome as default.

   3. do you want a quick and dirty assembly for first insights (choose: draft) or an assembly that should be able to tackle even most nasty cases (choose: accurate)? Pick one. Leaving this out automatically chooses accurate as default.

   Once you're done with your choices, concatenate everything with commas and you're done. E.g.: '`--job=mapping,genome,draft`' will give you a mapping assembly of a genome in draft quality.

   For de-novo assembly of genomes, these switches are optimised for 'decent' coverages that are commonly seen to get you something useful, i.e., ≥ 7x for Sanger, >=18x for 454 FLX or Titanium, ≥ 25x for 454 GS20 and ≥ 30x for Solexa. Should you venture into lower coverage or extremely high coverage (say, >=60x for 454), you will need to adapt a few parameters via extensive switches.

3. parameters = is used in case you want to change one of the 150+ extended parameters MIRA has to offer to control almost every aspect of an assembly. This is described in more detail in a separate section below.

### The manifest file: defining the data to load

The second part of an assembly manifest tells MIRA which files it needs to load, which sequencing technology generated the data, whether there are DNA template constraints it can use during the assembly process and a couple of other things.

1. readgroup = group name is the keyword which tells MIRA that you are going to define a new read group. You can optionally name that group.

   #### Understanding readgroups and DNA templates

   When you send away your DNA for sequencing, it is going to be prepared for sequencing according to your wishes. Sequencing providers call this "constructing a library" and regardless whether you sequence with Sanger, 454, Illumina, Ion Torrent, Pacific Biosciences or other technologies, the "library prep" is always there.

   With most library preps, your DNA is first amplified and then cut into small pieces. These pieces are called templates and their length can be anywhere between a few dozen bases, a few hundred bases or even a couple of dozen or even hundred kilobases. The important thing is that these templates can be much bigger in size than the actual read length. While this is a wet lab step, protocols and providers have gotten pretty good at constructing libraries where the DNA templates are all in a given range of bases like, e.g., having a library with template size 500bp (+/- 100bp) and another library with template size around 7kb (+/- 500bp).

   Depending on the technology and sequencing strategy used, the DNA templates are used to create either one single read or - and that's important - two or more reads.

   Libraries with "single reads" are often called "single read libraries" or "shotgun libraries". They can be found for every sequencing technology and are most of the time easy to construct (therefore cheap) and are often used to provide a decent amount of bases as basic coverage for your project.

   Libraries with two reads per DNA template are often called "mate-pair" or "paired-end" libraries. They are harder to construct and sometime have less yield, therefore they are often more expensive. But the sequencing approach using several reads per DNA template allows assembly and scaffolding algorithms to resolve repetitive regions of a genome which are longer than the average read length. Note that Pacific Biosciences has a sequencing mode called "strobed sequencing" which is different from "paired-end/mate-pair" but also creates multiple reads per DNA template.

   Long story short: an assembler must know afterwards what kind of reads it has to expect: the sequencing technology, library preparation strategy etc. For this, the notion of read groups has emerged: reads coming from the same technology and same library preparation are pooled together in a read group to tell the assembler: in the assembly, if you see two reads coming from a same DNA template, you should expect them to be at a certain distance from each other and they should be oriented in a certain way.

   The above was a very simplified view on the whole area of DNA templates, readgroups, shotgun and paired end sequencing. Enough to hopefully understand the concepts, but you might want to read more about it.

2. data = filepath filepath ... defines the file paths from which sequences should be loaded. A file path can contain just the name of one (or several) files or it can contain the path, i.e., the directory (absolute or relative) including the file name.

   MIRA automatically recognises what type the sequence data is by looking at the postfix of files. Currently allowed file types are:

   - `.fasta` for sequences formatted in FASTA format where there exists an additional `.fasta.qual` file which contains quality data. If the file with quality data is missing, this is interpreted as error and MIRA will abort.

   - `.fna`, also for sequences formatted in FASTA format. The difference to `.fasta` lies in the way MIRA treats a missing quality file (called `.fna.qual`): it does not see that as critical error and continues.

   - `.fastq` for files in FASTQ format

   - `.fofnexp` for a file of EXP filenames which point to file in the Staden EXP format.

   - `.gff3` or `.gff` for files in GFF3 format. Note that MIRA will load all sequences and annotations contained in this file.

   - `.gbk`, `.gbf`, `.gbff` or `.gb` for files formatted in GenBank format. Note that the MIRA GenBank loader does not understand intron/exon or other multiple-locus structures in this format, use GFF3 instead!

   - `.caf` for files in the CAF format (from Sanger Centre)

   - `.maf` for files in the MIRA MAF format

   - `.xml`, `.ssaha2` and `.smalt` for ancillary data in NCBI TRACEINFO, SSAHA2 or SMALT format respectively.

   Multiple 'data' lines and multiple entries per line (even different formats) are allowed, as in, e.g.,

       data = file1.fastq file2.fastq file3.fasta file4.gbk
       data = myscreenings.smalt

   You can also use wildcards and/or directory names. E.g., loading all file types MIRA understand from a given directory `mydir`:

       data = mydir

   or loading all files starting with `mydata` and ending with `fastq`:

       data = mydata*fastq

   or loading all files in directory `mydir` starting with `mydata` and ending with `fastq`:

       data = mydir/mydata*fastq

   or loading all FASTQ files in all directories starting with `mydir`:

       data = mydir*/*fastq

   or ... well, you get the gist.

   Giving a directory like in `mydir` is equivalent to `mydir/*` (saying: give me all files in the firectory `mydir`), however the first version should be preferred when the directory contains thousands of files.

   GenBank and GFF3 files may or may not contain embedded sequences. If annotations are present in these files for which no sequence is present in the same file, MIRA will look for reads of the same name which it already loaded in this or previously defined read groups and add the annotations there.

   As security measure, annotations in GenBank and GFF3 files for which absolutely no sequence or read has been defined are treated as error.

3. default_qual= quality_value is meant to be used as default fallback quality value for sequences where the data files given above do not contain quality values. E.g., GFF3 or GenBank formats, eventually also FASTA files where quality data files is missing.

4. technology= technology which names the technology with which the sequences were produced. Allowed technologies are: sanger, 454, solexa, iontor, pcbiolq, pcbiohq, text.

   The text technology is not a technology per se, but should be used for sequences which are not comming from sequencing machines like, e.g., database entries, consensus sequences, artificial reads (which do not comply to normal behaviour of 'normal' sequencing data), etc.pp

5. as_reference This keyword indicates to MIRA that the sequences in this readgroup should not be assembled, but should be used as reference backbone for a mapping assembly. That is, sequencing reads are then placed/mapped onto these reference reads.

6. templatesize = min_size max_size [infoonly|exclusion_criterion]. Defines the minimum and maximum size of "good" DNA templates in the library prep for this read group.

   If the term infoonly is present, then MIRA will pass the information on template sizes in result files, but will not use it for any decision making during de-novo assembly or mapping assembly. The term exclusion_criterion makes MIRA use the information for decision making.

   If infoonly or exclusion_criterion are missing, then MIRA assumes exclusion_criterion for de-novo assemblies and infoonly for mapping assemblies.

   The templatesize line in the manifest file replaces the parameters -GE:uti:tismin:tismax of earlier versions of MIRA (3.4.x and below).

   For mapping assemblies with MIRA, you usually will want to use infoonly as else - in case of genome re-arrangements, larger deleteions or insertions - MIRA would probably reject one read of every read pair (as it would not be at the expected distance and/or orientation) and you would not be able to simply find the re-arrangement in downstream analysis.

   For de-novo assemblies however you should not use infoonly except in very rare cases where you know what you do.

   #### Understanding the size of DNA templates

   When using a paired-end or mate-pair sequencing strategy, two sequences are generated for the ends of each DNA template (see sidebar above: "understanding readgroups and DNA templates"). That is, if one has a library with 6kb fragments, one knows that the outer ends of the two reads will be approximately 6kb apart, ike so:

       DNA template    ##############################################################
       read 1          .......
       read 2                                                                  ......
                       <------------------------- ~6 kb ---------------------------->

   Sequencing labs will try their best to get these two sequences from DNA templates which comply to a given length specification. But as this is chemistry and wet lab, things must be seen with a certain uncertainty and therefore the DNA templates generated are not exactly of the specified size (e.g. 6kb), but the size distribution will vary in a given range, e.g., 5.5kb to 6.5 kb.

7. segmentplacement = placementcode [infoonly|exclusion_criterion]. Allowed placement codes are:

   - ? which is a place-holder for "unknown" or "don't care." Segments of a template can be reads in any direction and in any relationship to each other. Shotgun reads usually have this, but also useful for for, e.g., primer walking with Sanger.

   - ---> <--- or FR or INNIES. The forward / reverse scheme as used in traditional Sanger sequencing as well as Illumina paired-end sequencing,

     This is the usual placement code for Sanger paired-end protocols as well as Illumina paired-end. Less frequently used in IonTorrent paired-end sequencing.

   - <--- ---> or RF od OUTTIES. The reverse / forward scheme as used in Illumina mate-pair sequencing.

     This is the usual placement code for Illumina mate-pair protocols.

   - 1---> 2---> or samedir forward or SF or LEFTIES. The forward / forward scheme. Segments of a template are all placed in the same direction, the segment order in the contig follows segment ordering of the reads.

   - 2---> 1---> samedir backward or SB or RIGHTIES. Segments of a template are all placed in the same direction, the segment order in the contig is reversed compared to segment ordering of the reads.

     This is the usual placement code for 454 "paired-end" and IonTorrent long-mate protocols.

   - samedir Segments of a template are all placed in the same direction, the spatial relationship however is not cared of.

   - >>> (reserved for sequencing of several equidistant fragments per template like in PacBio strobe sequencing, not implemented yet)

   If the term infoonly is present, then MIRA will pass the information on segment placement in result files, but will not use it for any decision making during de-novo assembly or mapping assembly. The term exclusion_criterion makes MIRA use the information for decision making.

   If infoonly or exclusion_criterion are missing, then MIRA assumes exclusion_criterion for de-novo assemblies and infoonly for mapping assemblies.

   For mapping assemblies with MIRA, you usually will want to use infoonly as else - in case of genome re-arrangements, larger deleteions or insertions - MIRA would probably reject one read of every read pair (as it would not be at the expected distance and/or orientation) and you would not be able to simply find the re-arrangement in downstream analysis.

   For de-novo assemblies however you should not use infoonly except in very rare cases where you know what you do.

   #### Understanding read segment placement on DNA templates

   bla

8. segmentnaming = naming_scheme. Defines the naming scheme reads are following to indicate the DNA template they belong to. Allowed naming schemes are: sanger, stlouis, tigr, FR, solexa.

   If not defined, the defaults are sanger for Sanger sequencing data, while solexa for Solexa, 454 and Ion Torrent.

   This has changed with MIRA 3.9.1 and `sff_extract` 0.3.0. Before that, 454 and Ion Torrent were given fr as naming scheme.

   #### Understanding read naming schemes

   Read naming is a long story with lots of historical gotchas: it needs to be clear and simple, but still people sometimes wanted to convey additional meta-information with it. Unsurprisingly, several "standards" emerged over time. In short: it's a mess.

   How to choose: please read the documentation available at the different centres or ask your sequence provider. In a nutshell (and probably over-simplified):

   Sanger scheme

     "somename.[pqsfrw][12][bckdeflmnpt][a|b|c|..." (e.g. U13a08f10.p1ca), but the length of the postfix must be at least 4 characters, i.e., ".p" alone will not be recognised.

     Usually, ".p" + 3 characters or "f" + 3 characters are used for forwards reads, while reverse complement reads take either ".q" or ".r" (+ 3 characters in both cases).

   TIGR scheme

     "somenameTF*|TR*|TA*" (e.g. GCPBN02TF or GCPDL68TABRPT103A58B),

     Forward reads take "TF*", reverse reads "TR*".

   St. Louis scheme

     "somename.[sfrxzyingtpedca]*"

   Forward/Reverse scheme

     "somename.[fr]*" (e.g. E0K6C4E01DIGEW.f or E0K6C4E01BNDXN.r2nd),

     ".f*" for forward, ".r*" for reverse.

   Solexa scheme

     Even simpler than the forward/reverse scheme, it allows only for one two reads per template: "somename/[12]"

   Any wildcard in the forward/reverse suffix must be consistent for a read pair, and is treated as part of the template name. This is to allow multiple sequencing of a fragment, particularly common with Sanger capillary data (e.g. given somename.f and somename.r, resequenced as somename.f2 and somename.r2, this would be treated as two pairs, with template names somename and somename_2 respectively).

9. strainname = string. Defines the strain / organism-code the reads of this read group are from. If not set, MIRA will assign "StrainX" to reads and "ReferenceStrain" to reference sequences.

   #### Understanding how MIRA uses strain information

   bla

10. datadir_scf = directory

    For SANGER data only: tells MIRA in which directory it can find SCF data belonging to reads of this read group.

### The manifest file: extended parameters

The parameters= line in the manifest file opens up the full panoply of possibilities the MIRA assembler offers. This ranges from fine-tuning assemblies to setting parameters in a way so that MIRA is suited also for very special assembly cases.

#### Parameter groups

Some parameters one can set in MIRA somehow belong together. Example given: when specifying an overlap in an alignment of two sequences, one could tell the assembler it should look at overlaps only if they have a certain similarity and a certain length. On the other hand, specifying how many processors / threads the assembler should use or whether the results of an assembly should be written out as SAM format does not seem to relate to alignments.

MIRA uses parameter groups to keep parameters together which somehow belong together. Example given:

    parameters =  -GENERAL:number_of_threads=4 \
                  -ALIGN:min_relative_score=70:minimum_read_length=150 \
                  -OUTPUT:output_result_caf=no

The parameters of the different parameter groups are described in detail a bit later in this manual.

#### Technology sections

With the introduction of new sequencing technologies, MIRA also had to be able to set values that allow technology specific behaviour of algorithms. One simple example for this could be the minimum length a read must have to be used in the assembly. For Sanger sequences, having this value to be 150 (meaning a read should have at least 150 unclipped bases) would be a very valid, albeit conservative choice. For 454 reads and especially Solexa and ABI SOLiD reads however, this value would be ridiculously high.

To allow very fine grained behaviour, especially in hybrid assemblies, and to prevent the explosion of parameter names, MIRA uses categorises the paremeters in two categories:

1. technology independent parameters which control general behaviour of MIRA like, e.g., the number of assembly passes or file names etc.

2. technology dependent parameters which control behaviour of algorithms where the sequencing technology plays a role. Example for this would be the minimum length of a read (like 200 for Sanger reads and 120 for 454 FLX reads).

More on this a bit further down in this documentation.

As example, a manifest using technology dependent and independent parameters could look like this:

    parameters = COMMON_SETTINGS -GENERAL:number_of_threads=4 \
                  SANGER_SETTINGS -ALIGN:min_relative_score=70:minimum_read_length=150 \
                  454_SETTINGS -ALIGN:min_relative_score=75:minimum_read_length=100 \
                  SANGER_SETTINGS -ALIGN:min_relative_score=90:minimum_read_length=75

Now, assume the following read group descriptions in a manifest:

    ...

    readgroup
    technology=454
    ...

    readgroup
    technology=solexa
    ...

For MIRA, this means a number of parameters should apply to the assembly as whole, while others apply to the sequencing data itself ... and some parameters might need to be different depending on the technology they apply to. MIRA dumps the parameters it is running with at the beginning of an assembly and it makes it clear there which parameters are "global" and which parameters apply to single technologies.

Here is exemplary a part of the output of used parameters that MIRA will show:

    ...

    Assembly options (-AS):
        Number of passes (nop)                      : 1
        Skim each pass (sep)                        : yes
        Maximum number of RMB break loops (rbl)     : 1
        Spoiler detection (sd)                      : no
        Last pass only (sdlpo)                      : yes

        Minimum read length (mrl)                   :  [san]  80
                                                       [454]  40
        						   [sxa]  20
        Base default quality (bdq)                  :  [san]  10
                                                       [454]  10
        						   [sxa]  10
    ...

You can see the two different kind of settings that MIRA uses: common settings (like -AS:nop) and technology dependent settings (like -AS:mrl), where for each sequencing technology used in the project, the setting can be different.

How would one set a minimum read length of 80 and a base default quality of 10 for 454 reads, but for Solexa reads a minimum read length of 30 with a base default quality of 15? The answer:

    job=denovo,genome,draft
    parameters= 454_SETTINGS -AS:mrl=80:bdq=10 SOLEXA_SETTINGS -AS:mrl=30:bdq=15

Notice the ..._SETTINGS section in the command line (or parameter file): these tell MIRA that all the following parameters until the advent of another switch are to be set specifically for the said technology.

For improved readability, you can distribute parameters across several lines either by pre-fixing every line with `parameter=`, like so:

    job=denovo,genome,draft
    parameters= 454_SETTINGS -AS:mrl=80:bdq=10
    parameters= SOLEXA_SETTINGS -AS:mrl=30:bdq=15

Alternatively you can use a backslash at the end of a parameter line to indicate that the next line is a continuing line, like so:

    job=denovo,genome,draft
    parameters= 454_SETTINGS -AS:mrl=80:bdq=10 \
                SOLEXA_SETTINGS -AS:mrl=30:bdq=15

Beside COMMON_SETTINGS there are currently 6 technology settings available:

1. SANGER_SETTINGS

2. 454_SETTINGS

3. IONTOR_SETTINGS

4. PCBIOLQ_SETTINGS (currently not supported)

5. PCBIOHQ_SETTINGS

6. SOLEXA_SETTINGS

7. TEXT_SETTINGS

Some settings of MIRA are influencing global behaviour and are not related to a specific sequencing technology, these must be set in the COMMON_SETTINGS environment. For example, it would not make sense to try and set different number of assembly passes for each technology like in

    parameters= 454_SETTINGS -AS:nop=4 SOLEXA_SETTINGS -AS:nop=3

Beside being contradictory, this makes not really sense. MIRA will complain about cases like these. Simply set those common settings in an area prefixed with the COMMON_SETTINGS switch like in

    parameters= COMMON_SETTINGS -AS:nop=4 454_SETTINGS ... SOLEXA_SETTINGS ...

Since MIRA 3rc3, the parameter parser will help you by checking whether parameters are correctly defined as COMMON_SETTINGS or technology dependent setting.

#### Parameter short names

Writing the verbose form of parameters can be quite a long task. Here a short example:

    parameters = COMMON_SETTINGS -GENERAL:number_of_threads=4 \
                  SANGER_SETTINGS -ALIGN:min_relative_score=70:minimum_read_length=150 \
                  454_SETTINGS -ALIGN:min_relative_score=75:minimum_read_length=100 \
                  SOLEXA_SETTINGS -ALIGN:min_relative_score=90:minimum_read_length=75

However, every parameter has a shortened form. The above could be written like this:

    parameters = COMMON_SETTINGS -GE:not=4 \
                  SANGER_SETTINGS -AL:mrs=70:mrl=150 \
                  454_SETTINGS -AL:mrs=75:mrl=100 \
                  SOLEXA_SETTINGS -AL:mrs=90:mrl=75

Please note that it is also perfectly legal to decompose the switches so that they can be used more easily in scripted environments (notice the multiple -AL in some sections of the following example):

    parameters = COMMON_SETTINGS -GE:not=4 \
                  SANGER_SETTINGS \
                    -AL:mrs=70 \
    		-AL:mrl=150 \
                  454_SETTINGS -AL:mrs=75:mrl=100 \
                  SOLEXA_SETTINGS \
    	        -AL:mrs=90 \
                    -AL:mrl=75

#### Order dependent quick switches

For some parameters, the order of appearance in the parameter lines of the manifest is important. This is because the quick parameters are realised internally as a collection of extended parameters that will overwrite any previously manually set extended parameters. It is generally a good idea to place quick parameters in the order as described in this documentation, that is: first the order dependent quick parameters, then other quick parameters, then all the other extended parameters.

-highlyrepetitive

  A modifier switch for genome data that is deemed to be highly repetitive. The assemblies will run slower due to more iterative cycles that give MIRA a chance to resolve nasty repeats.

--noclipping=...

  Switches off clipping options for given sequencing technologies. Technologies can be sanger, 454, iontor, solexa or solid. Multiple entries separated by comma.

  Note that -CL:pec and the chimera clipping -CL:ascdc are not switched off by this parameter and should be switched off separately.

  Examples:

  1. Switch off 454 and Solexa (but keep eventually keep Sanger clipping): `--noclipping=454,solexa`

  2. Switch off all: `--noclipping` or `--noclipping=all`

#### Parameter group: -GENERAL (-GE)

General options control the type of assembly to be performed and other switches not belonging anywhere else.

number_of_threads(not)=0 ≤ integer ≤ 256

  Default is 0. Master switch to set the number of threads used in different parts of MIRA.

  A value of 0 tells MIRA to set this to the number of available physical cores on the machine it runs on. That is, hyperthreaded "cores" are not counted in as using these would cause a tremendous slowdown in the heavy duty computation parts. E.g., a machine with 2 processors having 4 cores each will have this value set to 8.

  In case MIRA cannot find out the number of cores, the fallback value is 2.

  Note: when running the SKIM algorithm in parallel threads, MIRA can give different results when started with the same data and same arguments. While the effect could be averted for SKIM, the memory cost for doing so would be an additional 50% for one of the large tables, so this has not been implemented at the moment. Besides, at the latest when the Smith-Watermans run in parallel, this could not be easily avoided at all.

automatic_memory_management(amm)=on|y[es]|t[rue], off|n[o]|f[alse]

  Default is Yes. Whether MIRA tries to optimise run time of certain algorithms in a space/time trade-off memory usage, increasing or reducing some internal tables as memory permits.

  Note 1: This functionality currently relies on the `/proc` file system giving information on the system memory ("MemTotal" in /proc/meminfo) and the memory usage of the current process ("VmSize" in `/proc/self/status`). If this is not available, the functionality is switched off.

  Note 2: The automatic memory management can only work if there actually is unused system memory. It's not a wonder switch which reduces memory consumption. In tight memory situations, memory management has no effect and the algorithms fall back to minimum table sizes. This means that the effective size in memory can grow larger than given in the memory management parameters, but then MIRA will try to keep the additional memory requirements to a minimum.

max_process_size(mps)=0 ≤ integer

  Default is 0. If automatic memory management is used (see above), this number is the size in gigabytes that the MIRA process will use as maximum target size when looking for space/time trade-offs. A value of 0 means that MIRA does not try keep a fixed upper limit.

  Note: when in competition to -GE:kpmf (see below), the smaller of both sizes is taken as target. Example: if your machine has 64 GiB but you limit the use to 32 GiB, then the MIRA process will try to stay within these 32 GiB.

keep_percent_memory_free(kpmf)=0 ≤ integer

  Default is 10. If automatic memory management is used (see above), this number works a bit like -GE:mps but the other way round: it tries to keep x percent of the memory free.

  Note: when in competition to -GE:mps (see above), the argument leaving the most memory free is taken as target. Example: if your machine has 64 GiB and you limit the use to 42 GiB via -GE:mps but have a -GE:kpmf of 50, then the MIRA process will try to stay within 64-(64*50%)=32 GiB.

est_snp_pipeline_step(esps)=1 ≤ integer ≤ 4

  Default is 1. Controls the starting step of the SNP search in EST pipeline and is therefore only useful in miraSearchESTSNPs.

  EST assembly is a three step process, each with different settings to the assembly engine, with the result of each step being saved to disk. If results of previous steps are present in a directory, one can easily "play around" with different setting for subsequent steps by reusing the results of the previous steps and directly starting with step two or three.

print_date(pd)=on|y[es]|t[rue], off|n[o]|f[alse]

  Default is yes. Controls whether date and time are printed out during the assembly. Suppressing it is not useful in normal operation, only when debugging or benchmarking.

#### Parameter group: -ASSEMBLY (-AS)

General options for controlling the assembly.

num_of_passes(nop)=integer

  Default is dependent of the sequencing technology and assembly quality level. Defines how many iterations of the whole assembly process are done.

  As a special use case, a value of 0 will let MIRA just run the following tasks: loading and clipping of reads as well as calculating hash frequencies and read repeat information. The resulting reads can then be found as MAF file in the checkpoint directory; the read repeat information in the info directory.

  Early termination: if the number of passes was chosen too high, one can simply create a file `projectname_assembly/projectname_d_chkpt/terminate`. At the beginning of a new pass, MIRA checks for the existence of that file and, if it finds it, acknowledges by renaming it to `terminate_acknowledged` and then run 2 more passes (with special "last pass routines") before finishing the assembly.

  As a rule of thumb, de-novo assemblies should always have at least two passes, while mapping assemblies should work with only one pass. Not doing this will lead to results unexpected by users. The reason is that MIRA the learning routines either have no chance to learn enough about the assembly (for de-novo with one pass) or learn "too much" (mapping with more than one pass).

skim_each_pass(sep)=on|y[es]|t[rue], off|n[o]|f[alse]

  Default is dependent of the sequencing technology and assembly quality level. Defines whether the skim algorithm (and with it also the recalculation of Smith-Waterman alignments) is called in-between each main pass. If set to no, skimming is done only when needed by the workflow: either when read extensions are searched for (-DP:ure) or when possible vector leftovers are to be clipped (-CL:pvc).

  Setting this option to yes is highly recommended, setting it to no only for quick and dirty assemblies.

rmb_break_loops(rbl)=integer > 0

  Default is dependent of the sequencing technology and assembly quality level. Defines the maximum number of times a contig can be rebuilt during a main assembly passes (-AS:nop) if misassemblies due to possible repeats are found.

max_contigs_per_pass(mcpp)=integer

  Default is 0. Defines how many contigs are maximally built in each pass. A value of 0 stands for 'unlimited'. Values >0 can be used for special use cases like test assemblies etc.

  If in doubt, do not touch this parameter.

automatic_repeat_detection(ard)=on|y[es]|t[rue], off|n[o]|f[alse]

  Default is is currently yes. Tells MIRA to use coverage information accumulated over time to more accurately pinpoint reads that are in repetitive regions.

coverage_threshold(ardct)=float > 1.0

  Default is 2.0 for all sequencing technologies in most assembly cases. This option says this: if MIRA a read has ever been aligned at positions where the total coverage of all reads of the same sequencing technology attained the average coverage times -AS:ardct (over a length of -AS:ardml, see below), then this read is considered to be repetitive.

min_length(ardml)=integer > 1

  Default is dependent of the sequencing technology, currently 400 for Sanger and 200 for 454 and Ion Torrent.

  A coverage must be at least this number of bases higher than -AS:ardct before being really treated as repeat.

grace_length(ardgl)=integer > 1

  Default is dependent of the sequencing technology.

uniform_read_distribution(urd)=on|y[es]|t[rue], off|n[o]|f[alse]

  Default is currently yes for genome assemblies and no for EST assemblies or assemblies with Solexa data.

  Takes effect only if uniform read distribution (-AS:urd) is on.

  When set to yes, MIRA will analyse coverage of contigs built at a certain stage of the assembly and estimate an average expected coverage of reads for contigs. This value will be used in subsequent passes of the assembly to ensure that no part of the contig gets significantly more read coverage of reads that were previously identified as repetitive than the estimated average coverage allows for.

  This switch is useful to disentangle repeats that are otherwise 100% identical and generally allows to build larger contigs. It is expected to be useful for Sanger and 454 sequences. Usage of this switch with Solexa and Ion Torrent data is currently not recommended.

  It is a real improvement to disentangle repeats, but has the side-effect of creating some "contig debris" (small and low coverage contigs, things you normally can safely throw away as they are representing sequence that already has enough coverage).

  This switch must be set to no for EST assembly, assembly of transcripts etc. It is recommended to also switch this off for mapping assemblies.

urd_startinpass(urdsip)=integer > 0

  Default is dependent of the sequencing technology and assembly quality level. Recommended values are: 3 for an assembly with 3 to 4 passes (-AS:nop). Assemblies with 5 passes or more should set the value to the number of passes minus 2.

  Takes effect only if uniform read distribution (-AS:urd) is on.

urd_clipoffmultiplier(urdcm)=float > 1.0

  Default is 1.5 for all sequencing technologies in most assembly cases. The --highlyrepetitive quick-switch sets this to 1.2.

  This option says this: if MIRA determined that the average coverage is x, then in subsequent passes it will allow coverage for reads determined to be repetitive to be built into the contig only up to a total coverage of x*urdcm. Reads that bring the coverage above the threshold will be rejected from that specific place in the contig (and either be built into another copy of the repeat somewhere else or end up as contig debris).

  Please note that the lower -AS:urdcm is, the more contig debris you will end up with (contigs with an average coverage less than half of the expected coverage, mostly short contigs with just a couple of reads).

  Takes effect only if uniform read distribution (-AS:urd) is on.

keep_long_repeats_separate(klrs)=on|y[es]|t[rue], off|n[o]|f[alse]

  Default is is dependent on --job quality: currently no for draft and yes for accurate. Switched of for EST assembly.

  Tells MIRA to use keep repeats longer that the length of reads in separate contigs.

spoiler_detection(sd)=on|y[es]|t[rue], off|n[o]|f[alse]

  Default is dependent of the sequencing technology and assembly quality level. A spoiler can be either a chimeric read or it is a read with long parts of unclipped vector sequence still included (that was too long for the -CL:pvc vector leftover clipping routines). A spoiler typically prevents contigs to be joined, MIRA will cut them back so that they represent no more harm to the assembly.

  Recommended for assemblies of mid- to high-coverage genomic assemblies, not recommended for assemblies of ESTs as one might loose splice variants with that.

  A minimum number of two assembly passes (-AS:nop) must be run for this option to take effect.

sd_last_pass_only(sdlpo)=on|y[es]|t[rue], off|n[o]|f[alse]

  Default is yes. Defines whether the spoiler detection algorithms are run only for the last pass or for all passes (-AS:nop).

  Takes effect only if spoiler detection (-AS:sd) is on. If in doubt, leave it to 'yes'.

minimum_read_length(mrl)=integer ≥ 20

  Default is dependent of the sequencing technology. Defines the minimum length that reads must have to be considered for the assembly. Shorter sequences will be filtered out at the beginning of the process and won't be present in the final project.

minimum_reads_per_contig(mrpc)=integer ≥ 1

  Default is dependent of the sequencing technology and the --job parameter. For genome assemblies it's usually around 2 for Sanger, 5 for 454, 5 for Ion Torrent, 5 for PacBio and 10 for Solexa. In EST assemblies, it's currently 2 for all sequencing technologies.

  Defines the minimum number of reads a contig must have before it is built or saved by MIRA. Overlap clusters with less reads than defined will not be assembled into contigs but reads in these clusters will be immediately transferred to debris.

  This parameter is useful to considerably reduce assembly time in large projects with millions of reads (like in Solexa projects) where a lot of small "junk" contigs with contamination sequence or otherwise uninteresting data may be created otherwise.

  Important: a value larger 1 of this parameter interferes with the functioning of -OUT:sssip and -OUT:stsip.

base_default_quality(bdq)=integer ≥ 0

  Default is currently 10 for all sequencing technologies. Defines the default base quality of reads that have no quality read from file.

enforce_presence_of_qualities(epoq)=on|y[es]|t[rue], off|n[o]|f[alse]

  Default is yes. When set to yes, MIRA will stop the assembly if any read has no quality values loaded.

use_genomic_pathfinder(ugpf)=on|y[es]|t[rue], off|n[o]|f[alse]

  Default is yes. MIRA has two different pathfinder algorithms it chooses from to find its way through the (more or less) complete set of possible sequence overlaps: a genomic and an EST pathfinder. The genomic looks a bit into the future of the assembly and tries to stay on safe grounds using a maximum of information already present in the contig that is being built. The EST version on the contrary will directly jump at the complex cases posed by very similar repetitive sequences and try to solve those first and is willing to fall back to first-come-first-served when really bad cases (like, e.g., coverage with thousands of sequences) are encountered.

  Generally, the genomic pathfinder will also work quite well with EST sequences (but might get slowed down a lot in pathological cases), while the EST algorithm does not work so well on genomes. If in doubt, leave on yes for genome projects and set to no for EST projects.

use_emergency_search_stop(uess)=on|y[es]|t[rue], off|n[o]|f[alse]

  Default is yes. Another important switch if you plan to assemble non-normalised EST libraries, where some ESTs may reach coverages of several hundreds or thousands of reads. This switch lets MIRA save a lot of computational time when aligning those extremely high coverage areas (but only there), at the expense of some accuracy.

ess_partnerdepth(esspd)=integer > 0

  Default is 500. Defines the number of potential partners a read must have for MIRA switching into emergency search stop mode for that read.

use_max_contig_buildtime(umcbt)=on|y[es]|t[rue],off|n[o]|f[alse]

  Default is no. Defines whether there is an upper limit of time to be used to build one contig. Set this to yes in EST assemblies where you think that extremely high coverages occur. Less useful for assembly of genomic sequences.

buildtime_in_seconds(bts)=integer > 0

  Default is 3600 for genome assemblies, 720 for EST assemblies with Sanger or 454 and 360 for EST assemblies with Solexa or Ion Torrent. Depending on -AS:umcbt above, this number defines the time in seconds allocated to building one contig.

#### Parameter group: -STRAIN/BACKBONE (-SB)

General options for controlling backbone options for mapping assemblies as well as general strain information.

startbackboneusage_inpass(sbuip)=0 < integer

  Default is dependent on assembly quality level chosen: 0 for 'draft' and -AS:nop divided by 2 for 'accurate'.

  When assembling against backbones, this parameter defines the pass iteration (see -AS:nop) from which on the backbones will be really used. In the passes preceding this number, the non-backbone reads will be assembled together as if no backbones existed. This allows MIRA to correctly spot repetitive stretches that differ by single bases and tag them accordingly. Note that full assemblies are considerably slower than mapping assemblies, so be careful with this when assembling millions of reads.

  Rule of thumb: if backbones belong to same strain as reads to assemble, set to 1. If backbones are a different strain, then set -SB:sbuib to 1 lower than -AS:nop (example: nop=4 and sbuip=3).

backbone_strainname_forceforall(bsnffa)=on|y[es]|t[rue], off|n[o]|f[alse]

  Default is no. Useful when using CAF as input for backbone: forces all reads of the backbone contigs to get assigned the new backbone strain, even if they previously had other strains assigned.

  Main usage is in multi-step hybrid assemblies.

backbone_raillength(brl)=0 ≤ integer ≤ 10000

  Default is 0. Parameter for the internal sectioning size of the backbone to compute optimal alignments. Should be set to two times length of longest read in input data + 15%. When set to 0, MIRA will compute optimal values from the data loaded.

backbone_railoverlap(bro)=0 ≤ integer ≤ 2000

  Default is 0. Parameter for the internal sectioning size of the backbone to compute optimal alignments. Should be set to length of the longest read. When set to 0, MIRA will compute optimal values from the data loaded.

also_build_new_contigs(abnc)=on|y[es]|t[rue], off|n[o]|f[alse]

  Default is no. Standard mapping assembly mode of the assembler is to map available reads to a backbone and discard reads that do not fit. If set to 'yes', MIRA will use reads that did not map to the backbone(s) to make new contigs (if possible). Please note: while a simple mapping assembly is comparatively cheap in terms of memory and time consumed, setting this option to 'yes' means that behind the scenes data for a full blown de-novo assembly is generated in addition to the data needed for a mapping assembly. This means, that in terms of memory consumption and speed, this switch combines the worst of both worlds.

  Using this switch is not recommended. Beside the memory and speed considerations, a lot of different algorithms cannot work optimally in this mode. I recommend to use a two step approach instead: first map with MIRA, then assemble de-novo all reads which did not map. This will lead more often than not to the results expected (and in faster time).

#### Parameter group: -DATAPROCESSING (-DP)

Options for controlling some data processing during the assembly.

use_read_extension(ure)=on|y[es]|t[rue], off|n[o]|f[alse]

  Default is dependent of the sequencing technology used: yes for Sanger, no for all others. MIRA expects the sequences it is given to be quality clipped. During the assembly though, it will try to extend reads into the clipped region and gain additional coverage by analysing Smith-Waterman alignments between reads that were found to be valid. Only the right clip is extended though, the left clip (most of the time containing sequencing vector) is never touched.

read_extension_window_length(rewl)=integer > 0

  Default is dependent of the sequencing technology used. Only takes effect when -DP:ure (see above) is set to yes. The read extension routines use a sliding window approach on Smith-Waterman alignments. This parameter defines the window length.

read_extension_with_maxerrors(rewme)=integer > 0

  Default is dependent of the sequencing technology used. Only takes effect when -DP:ure (see above) is set to yes. The read extension routines use a sliding window approach on Smith-Waterman alignments. This parameter defines the number maximum number of errors (=disagreements) between two alignment in the given window.

first_extension_in_pass(feip)=integer ≥ 0

  Default is dependent of the sequencing technology used. Only takes effect when -DP:ure (see above) is set to yes. The read extension routines can be called before assembly and/or after each assembly pass (see -AS:nop). This parameter defines the first pass in which the read extension routines are called. The default of 0 tells MIRA to extend the reads the first time before the first assembly pass.

last_extension_in_pass(leip)=integer ≥ 0

  Default is dependent of the sequencing technology used. Only takes effect when -DP:ure (see above) is set to yes. The read extension routines can be called before assembly and/or after each assembly pass (see -AS:nop). This parameter defines the last pass in which the read extension routines are called. The default of 0 tells MIRA to extend the reads the last time before the first assembly pass.

#### Parameter group: -CLIPPING (-CL)

Controls for clipping options: when and how sequences should be clipped.

Every option in this section can be set individually for every sequencing technology, giving a very fine grained control on how reads are clipped for each technology.

msvs_gap_size(msvsgs)=integer ≥ 0

  Default is dependent of the sequencing technology used. Takes effect only when loading data from ancillary SSAHA2 or SMALT files.

  While performing the clip of screened vector sequences, MIRA will look if it can merge larger chunks of sequencing vector bases that are a maximum of -CL:msvgsgs apart.

msvs_max_front_gap(msvsmfg)=integer ≥ 0

  Default is dependent of the sequencing technology used. Takes effect only when loading data from ancillary SSAHA2 or SMALT files.

  While performing the clip of screened vector sequences at the start of a sequence, MIRA will allow up to this number of non-vector bases in front of a vector stretch.

msvs_max_end_gap(msvsmeg)=integer ≥ 0

  Default is dependent of the sequencing technology used. Takes effect only when loading data from ancillary SSAHA2 or SMALT files.

  While performing the clip of screened vector sequences at the end of a sequence, MIRA will allow up to this number of non-vector bases behind a vector stretch.

possible_vector_leftover_clip(pvlc)=on|y[es]|t[rue], off|n[o]|f[alse]

  Default is dependent of the sequencing technology used: yes for Sanger, no for any other. MIRA will try to identify possible sequencing vector relics present at the start of a sequence and clip them away. These relics are usually a few bases long and were not correctly removed from the sequence in data preprocessing steps of external programs.

  You might want to turn off this option if you know (or think) that your data contains a lot of repeats and the option below to fine tune the clipping behaviour does not give the expected results.

  You certainly want to turn off this option in EST assemblies as this will quite certainly cut back (and thus hide) different splice variants. But then make certain that you pre-processing of Sanger data (sequencing vector removal) is good, other sequencing technologies are not affected then.

pvc_maxlenallowed(pvcmla)=integer ≥ 0

  Default is dependent of the sequencing technology used. The clipping of possible vector relics option works quite well. Unfortunately, especially the bounds of repeats or differences in EST splice variants sometimes show the same alignment behaviour than possible sequencing vector relics and could therefore also be clipped.

  To refrain the vector clipping from mistakenly clip repetitive regions or EST splice variants, this option puts an upper bound to the number of bases a potential clip is allowed to have. If the number of bases is below or equal to this threshold, the bases are clipped. If the number of bases exceeds the threshold, the clip is NOT performed.

  Setting the value to 0 turns off the threshold, i.e., clips are then always performed if a potential vector was found.

quality_clip(qc)=on|y[es]|t[rue], off|n[o]|f[alse]

  Default is no. This will let MIRA perform its own quality clipping before sequences are entered into the assembly. The clip function performed is a sequence end window quality clip with back iteration to get a maximum number of bases as useful sequence. Note that the bases clipped away here can still be used afterwards if there is enough evidence supporting their correctness when the option -DP:ure is turned on.

  Warning: The windowing algorithm works pretty well for Sanger, but apparently does not like 454 type data. It's advisable to not switch it on for 454. Beside, the 454 quality clipping algorithm performs a pretty decent albeit not perfect job, so for genomic 454 data (not! ESTs), it is currently recommended to use a combination of -CL:emrc and -DP:ure.

qc_minimum_quality(qcmq)=integer ≥ 15 and ≤ 35

  Default is dependent of the sequencing technology used. This is the minimum quality bases in a window require to be accepted. Please be cautious not to take too extreme values here, because then the clipping will be too lax or too harsh. Values below 15 and higher than 30-35 are not recommended.

qc_window_length(qcwl)=integer ≥ 10

  Default is dependent of the sequencing technology used. This is the length of a window in bases for the quality clip.

bad_stretch_quality_clip (bsqc)=on|y[es]|t[rue], off|n[o]|f[alse]

  Default is no. This option allows to clip reads that were not correctly preprocess and have unclipped bad quality stretches that might prevent a good assembly.

  MIRA will search the sequence in forward direction for a stretch of bases that have in average a quality less than a defined threshold and then set the right quality clip of this sequence to cover the given stretch.

bsqc_minimum_quality (bsqcmq)=integer ≥ 0

  Default is dependent of the sequencing technology used. Defines the minimum average quality a given window of bases must have. If this quality is not reached, the sequence will be clipped at this position.

bsqc_window_length (bsqcwl)=integer ≥ 0

  Default is dependent of the sequencing technology used. Defines the length of the window within which the average quality of the bases are computed.

maskedbases_clip(mbc)=on|y[es]|t[rue], off|n[o]|f[alse]

  Default is dependent of the sequencing technology used. This will let MIRA perform a 'clipping' of bases that were masked out (replaced with the character X). It is generally not a good idea to use mask bases to remove unwanted portions of a sequence, the EXP file format and the NCBI traceinfo format have excellent possibilities to circumvent this. But because a lot of preprocessing software are built around cross_match, scylla- and phrap-style of base masking, the need arose for MIRA to be able to handle this, too. MIRA will look at the start and end of each sequence to see whether there are masked bases that should be 'clipped'.

mbc_gap_size(mbcgs)=integer ≥ 0

  Default is dependent of the sequencing technology used. While performing the clip of masked bases, MIRA will look if it can merge larger chunks of masked bases that are a maximum of -CL:mbcgs apart.

mbc_max_front_gap(mbcmfg)=integer ≥ 0

  Default is dependent of the sequencing technology used. While performing the clip of masked bases at the start of a sequence, MIRA will allow up to this number of unmasked bases in front of a masked stretch.

mbc_max_end_gap(mbcmeg)=integer ≥ 0

  Default is dependent of the sequencing technology used. While performing the clip of masked bases at the end of a sequence, MIRA will allow up to this number of unmasked bases behind a masked stretch.

lowercase_clip_front(lccf)=on|y[es]|t[rue], off|n[o]|f[alse]

  Default is dependent of the sequencing technology used: on for 454 and Ion Torrent data, off for all others. This will let MIRA perform a 'clipping' of bases that are in lowercase at the front end of a sequence, leaving only the uppercase sequence. Useful when handling 454 data that does not have ancillary data in XML format.

lowercase_clip_back(lccb)=on|y[es]|t[rue], off|n[o]|f[alse]

  Default is dependent of the sequencing technology used: on for 454 and Ion Torrent data, off for all others. This will let MIRA perform a 'clipping' of bases that are in lowercase at the back end of a sequence, leaving only the uppercase sequence. Useful when handling 454 data that does not have ancillary data in XML format.

clip_polyat(cpat)=on|y[es]|t[rue], off|n[o]|f[alse]

  Default is no. This option is useful in EST assembly. Poly-A stretches in forward reads and poly-T stretches in reverse reads that were not correctly masked or clipped in preprocessing steps from external programs get clipped or tagged here. The assembler will not use these stretches for critical operations.

cp_keep_poly_signal (cpkps)=on|y[es]|t[rue], off|n[o]|f[alse]

  Default is no. This option is currently not active (as of version 2.9.22).

  In future, this will allow to keep the poly-A signal in the reads and tag them. The tags provide a good visual anchor when looking at the assembly with different programs.

cp_min_signal_len(cpmsl)=integer > 0

  Default is 10. Only takes effect when -CP:cpat (see above) is set to yes. Defines the number of ``A'' (in forward direction) or ``T'' (in reverse direction'' must be present to be considered a poly-A signal stretch.

cp_max_errors_allowed(cpmea)=integer > 0

  Default is 1. Only takes effect when -CL:cpat (see above) is set to yes. Defines the maximum number of errors allowed in the potential poly-A signal stretch. The distribution of these errors is not important.

cp_max_gap_from_end(cpmgfe)=integer > 0

  Default is 9. Only takes effect when -CL:cpat (see above) is set to yes.Defines the number of bases from the end of a sequence (if masked: from the end of the masked area) within which a poly-A signal stretch is looked for.

ensure_minimum_left_clip(emlc)=on|y[es]|t[rue], off|n[o]|f[alse]

  Default is dependent of the sequencing technology used. If on, ensures a minimum left clip on each read according to the parameters in -CL:mlcr:smlc

minimum_left_clip_required(mlcr)=integer ≥ 0

  Default is dependent of the sequencing technology used. If -CL:emlc is on, checks whether there is a left clip which length is at least the one specified here.

set_minimum_left_clip(smlc)=integer ≥ 0

  Default is dependent of the sequencing technology used. If -CL:emlc is on and actual left clip is < -CL:mlcr, set left clip of read to the value given here.

ensure_minimum_right_clip(emrc)=on|y[es]|t[rue], off|n[o]|f[alse]

  Default is dependent of the sequencing technology used. If on, ensures a minimum right clip on each read according to the parameters in -CL:mrcr:smrc

minimum_right_clip_required(mrcr)=integer ≥ 0

  Default is dependent of the sequencing technology used. If -CL:emrc is on, checks whether there is a right clip which length is at least the one specified here.

set_minimum_right_clip(smrc)=integer ≥ 0

  Default is dependent of the sequencing technology used. If -CL:emrc is on and actual right clip is < -CL:mrcr, set the length of the right clip of read to the value given here.

apply_skim_chimeradetectionclip(ascdc)=on|y[es]|t[rue], off|n[o]|f[alse]

  Default is yes for --job=genome assemblies and no for --job=est assemblies.

  The SKIM routines of MIRA can be also used without much time overhead to find chimeric reads. When this parameter is set, MIRA will use that info to cut back chimeras to their longest non-chimeric length.

  When working on low coverage data (e.g. < 5 to 6x Sanger and < 10x 454 or 10x Ion Torrent, you may want to switch off this option if you try to go for the longest contigs. Reason: single reads joining otherwise disjunct contigs will probably be categorised as chimeras.

apply_skim_junkdetectionclip(asjdc)=on|y[es]|t[rue], off|n[o]|f[alse]

  Default is currently no.

  The SKIM routines of MIRA can be also used without much time overhead to find junk sequence at end of reads. When this parameter is set, MIRA will use that info to cut back junk in reads.

  It is currently suggested to leave this parameter switched off as the routines seem to be a bit too "trigger happy" and also cut back perfectly valid sequences.

propose_end_clips(pec)=on|y[es]|t[rue], off|n[o]|f[alse]

  Default is is dependent on --job quality: currently yes for all genome assemblies. Switched off for EST assemblies (but one wmight want to switch it on sometimes).

  This implements a pretty powerful strategy to ensure a good "high confidence region" (HCR) in reads, basically eliminating 99.9% of all junk at the 5' and 3' ends of reads. Note that one still must ensure that sequencing vectors (Sanger) or adaptor sequences (454, Solexa ion Torrent) are "more or less" clipped prior to assembly.

  Extremely effective, but should NOT be used for very low coverage genomic data, for EST projects or if one wants to retain rare transcripts.

handle_solexa_ggcxg_problem(pechsgp)=on|y[es]|t[rue], off|n[o]|f[alse]

  Default is is dependent yes.

  Solexa data has a pretty awful problem with in some reads when a `GGCxG` motif occurs (read more about it in the chapter on Solexa data). In short: the sequencing errors produced by this problem lead to many false positive SNP discoveries in mapping assemblies or problems in contig building in de-novo assembly.

  MIRA knows about this problem and can look for it in Solexa reads during the proposed end clipping and further clip back the reads, greatly minimising the impact of this problem.

pec_bases_per_hash(pecbph)=integer ≥ 10

  Default is is dependent on technology and quality in the --job switch: usually between 17 and 21 for Sanger, higher for 454 (up to 27) and highest for Solexa (31). Ion Toorent has at the moment 17, but this may change in the future to somewhat higher values.

  This parameter defines the minimum number of bases at each end of a read that should be free of any sequencing errors. Note that the algorithm is based on SKIM hashing (see below), and compares hashes of all reads with each other. Therefore, using values less than 12 will lead to false negative hits.

clip_phix174(cpx174)=on|y[es]|t[rue], off|n[o]|f[alse]

  Default is is on for Illumina data in EST assemblies, off otherwise.

  PhiX 174 is a small phage of enterobacteria whose DNA is often spiked-in during Illumina sequencing to determine error rates in datasets and to increase complexity in low-complexity samples (amplicon, chipseq etc) to help in cluster identification.

  If it remains in the sequenced data, it most often has to be seen as a contaminant as projects will work with organisms which should not contain the PhiX 174 phage. However, it may be part of some genome sequences (enterobacteria). Therefore the conservative approach of the MIRA default values to automatically filter only RNASeq data sets but not genome data sets.

rare_kmer_mask(rkm)=integer ≥ 0

  Default is is dependent on --job switch: currently it's 2 for Solexa data in EST / RNASeq assemblies, and 0 otherwise. If this parameter is >0, MIRA will completely mask with 'X' those parts of a read which lead to kmer occurence less than the given value.

  This is a quality ensuring move which improves assembly of ultra-high coverage contigs by cleaning out very likely, low frequency sequence dependent sequencing errors which passed all previous filters. The drawback is that very rare transcripts with an occurence less than the given value will also be masked out. However, RNASeq gives so much data that even the rarest transcripts should normally have more reads than the default setting.

#### Parameter group: -SKIM (-SK)

Options that control the behaviour of the initial fast all-against-all read comparison algorithm. Matches found here will be confirmed later in the alignment phase. The new SKIM3 algorithm that is in place since version 2.7.4 uses a hash based algorithm that works similarly to SSAHA (see Ning Z, Cox AJ, Mullikin JC; "SSAHA: a fast search method for large DNA databases."; Genome Res. 2001;11;1725-9).

The major differences of SKIM3 and SSAHA are:

1. the word length n of a hash can be up to 31 bases (in 64 bit versions of MIRA)

2. SKIM3 uses a maximum fixed amount of RAM that is independent of the word size. E.g., SSAHA would need 4 exabyte to work with word length of 30 bases ... SKIM3 just takes a couple of hundred MB.

The parameters for SKIM3:

number_of_threads(not)=integer ≥ 1

  Number of threads used in SKIM, default is 2. A few parts of SKIM are non-threaded, so the speedup is not exactly linear, but it should be very close. E.g., with 2 processors I get a speedup of 180-195%, with 4 between 350 and 395%.

  Although the main data structures are shared between the threads, there's some additional memory needed for each thread.

also_compute_reverse_complements(acrc)=on|y[es]|t[rue], off|n[o]|f[alse]

  Default is on. Defines whether SKIM searches for matches only in forward/forward direction or whether it also looks for forward/reverse direction.

  You usually will not want to touch the default, except for very special application cases where you do not want MIRA to use reverse complement sequences at all.

bases_per_hash(bph)=10 < integer ≤ 32

  Controls the number of consecutive bases n which are used as a word hash. The higher the value, the faster the search. The lower the value, the more weak matches are found. Values below 10 are not recommended. Defaults are dependend on "--job" switch.

hash_save_stepping(hss)=integer ≥ 1

  Default is 1. This is a parameter controlling the stepping increment s with which hashes are generated. This allows for more or less fine grained search as matches are found with at least n+s (see -SK:bph) equal bases. The higher the value, the faster the search. The lower the value, the more weak matches are found.

percent_required(pr)=integer ≥ 1

  Default is dependent of the sequencing technology used and assembly quality wished. Controls the relative percentage of exact word matches in an approximate overlap that has to be reached to accept this overlap as possible match. Increasing this number will decrease the number of possible alignments that have to be checked by Smith-Waterman later on in the assembly, but it also might lead to the rejection of weaker overlaps (i.e. overlaps that contain a higher number of mismatches).

  Note: most of the time it makes sense to keep this parameter in sync with -AL:mrs.

maxhits_perread(mhpr)=integer ≥ 1

  Default is 2000. Controls the maximum number of possible hits one read can maximally transport to the graph edge reduction phase. If more potential hits are found, only the best ones are taken.

  In the pre-2.9.x series, this was an important option for tackling projects which contain extreme assembly conditions. It still is if you run out of memory in the graph edge reduction phase. Try then to lower it to 1000, 500 or even 100.

  As the assembly increases in passes (-AS:nop), different combinations of possible hits will be checked, always the probably best ones first. So the accuracy of the assembly should only suffer when lowering this number too much.

sw_check_on_backbones(swcob)=on|y[es]|t[rue], off|n[o]|f[alse]

  Default is currently (3.4.0) yes for accurate mapping jobs. Takes effect only in mapping assemblies. Defines whether SKIM hits against a backbone (reference) sequence with less than 100% identity are double checked with Smith-Waterman to improve mapping accuracy.

  You will want to set this option to yes whenever your reference sequence contains more complex or numerous repeats and your data has SNPs in those areas.

max_megahub_ratio(mmhr)=integer ≥ 0

  Default is 0. If the number of reads identified as megahubs exceeds the allowed ratio, MIRA will abort.

  This is a fail-safe parameter to avoid assemblies where things look fishy. In case you see this, you might want to ask for advice on the mira_talk mailing list. In short: bacteria should never have megahubs (90% of all cases reported were contamination of some sort and the 10% were due to incredibly high coverage numbers). Eukaryotes are likely to contain megahubs if filtering is -HS:mnr not on.

  EST project however, especially from non-normalised libraries, will very probably contain megahubs. In this case, you might want to think about masking, see -HS:mnr.

max_hashes_in_memory(mhim)=integer ≥ 100000

  Default is 15000000. Has no influence on the quality of the assembly, only on the maximum memory size needed during the skimming. The default value is equivalent to approximately 500MB.

  Note: reducing the number will increase the run time, the more drastically the bigger the reduction. On the other hand, increasing the default value chosen will not result in speed improvements that are really noticeable. In short: leave this number alone if you are not desperate to save a few MB.

memcap_hitreduction(mchr)=integer ≥ 10

  Default is 1024, 2048 when Solexa sequences are used. Maximum memory used (in MiB) during the reduction of skim hits.

  Note: has no influence on the quality of the assembly, reducing the number will increase the runtime, the more drastically the bigger the reduction as hits then must be streamed multiple times from disk.

  The default is good enough for assembly of bacterial genomes or small eukaryotes (using Sanger and/or 454 sequences). As soon as assembling something bigger than 20 megabases, you should increase it to 2048 or 4096 (equivalent to 2 or 4 GiB of memory).

#### Parameter group: -HASHSTATISTICS (-HS)

Hash statistics (sometimes also called kmer statistics in literature or other software packages) allows to quickly assess reads from a coverage point of view without actually assembling the reads. MIRA uses this as a quick pre-assembly evaluation to find and tag reads which are from repetitive and non-repetitive parts of a project.

The length of the hash (the kmer size) is defined via -SK:bph while the parameters in this section define the boundaries of the different repeat levels.

A more in-depth description on hash statistics is given in the sections Introduction to 'masking' and How does 'nasty repeat' masking work? in the chapter dealing with the assembly of hard projects.

freq_est_minnormal(fenn)=float > 0

  During hash statistics analysism, MIRA will estimate how repetitive parts of reads are. Parts which are occuring less than -HS:fenn times the average occurence will be tagged with a HAF2 (less than average) tag.

freq_est_maxnormal(fexn)=float > 0

  During hash statistics analysism, MIRA will estimate how repetitive parts of reads are. Parts which are occuring more than -HS:fenn but less than -HS:fexn times the average occurence will be tagged with a HAF3 (normal) tag.

freq_est_repeat(fer)=float > 0

  During hash statistics analysism, MIRA will estimate how repetitive parts of reads are. Parts which are occuring more than -HS:fexn but less than -HS:fer times the average occurence will be tagged with a HAF4 (above average) tag.

freq_est_heavyrepeat(fehr)=float > 0

  During hash statistics analysism, MIRA will estimate how repetitive parts of reads are. Parts which are occuring more than -HS:fer but less than -HS:fehr times the average occurence will be tagged with a HAF5 (repeat) tag.

freq_est_crazyrepeat(fecr)=float > 0

  During hash statistics analysism, MIRA will estimate how repetitive parts of reads are. Parts which are occuring more than -HS:fehr but less than -HS:fecr times the average occurence will be tagged with a HAF6 (heavy repeat) tag. Parts which are occuring more than -HS:fecr but less than -HS:nrr times the average occurence will be tagged with a HAF7 (crazy repeat) tag.

mask_nasty_repeats(mnr)=on|y[es]|t[rue], off|n[o]|f[alse]

  Default is dependent on --job type: yes for de-novo, no for mapping.

  Tells MIRA to tag during the hash statistics phase read subsequences of length -SK:bph nucleotides that appear more that X times more often than the median occurrence of subsequences would otherwise suggest. The threshold X from which on subsequences are considered nasty is set by -HS:nrr or -HS:nrc, the action MIRA should take when encountering those sequences is defined by -HS:ldn (see below).

  This option is extremely useful for assembly of larger projects (fungi-size) with a high percentage of repeats. Or in non-normalised EST projects, to get at least the sequence of overrepresented transcripts assembled even if the coverage values then cannot be interpreted as expression values anymore.

  Although it is expected that bacteria will not really need this, leaving it turned on will probably not harm except in unusual cases like several copies of (pro-)phages integrated in a genome.

nasty_repeat_ratio(nrr)=integer ≥ 2

  Default is depending on the --job=... parameters. Normally it's high (around 100) for genome assemblies, but much lower (20 or less) for EST assemblies.

  Sets the ratio from which on subsequences are considered nasty and hidden from the hash statistics overlapper with a MNRr tag. E.g.: A value of 10 means: mask all k-mers of -SK:bph length which are occurring more than 10 times more often than the average of the whole project.

nasty_repeat_coverage(nrc)=integer ≥ 0

  Default is depending on the --job=... parameters: 0 for genome assemblies, 200 for EST assemblies.

  Closely related to the -HS:nrr parameter (see above), but while the above works on ratios derived from a calculated average, this parameter allows to set an absolute value. Note that this parameter will take precedence over -HS:nrr if the calculated value of nrr is larger that the absolute value given here. A value of 0 de-activates this parameter.

lossless_digital_normalisation(ldn)=on|y[es]|t[rue], off|n[o]|f[alse]

  Default is dependent on --job type: yes for denovo EST/RNAseq assembly, no otherwise.

  Tells MIRA how to treat reads containing nasty repeats when -HS:mnr is active.

  When set to no, the tag used by MIRA will be "MNRr" which stands for "Mask Nasty Repeat in read". This tag has an active masking function in MIRA and the fast all-against-all overlap searcher (SKIM) will then completely ignore the tagged subsequences of reads. There's one drawback though: the smaller the reads are that you try to assemble, the higher the probability that your reads will not span nasty repeats completely, therefore leading to a abortion of contig building at this site. Reads completely covered by the MNRr tag will therefore land in the debris file as no overlap will be found.

  When set to yes, MIRA will apply a modified digital normalisation step to the reads, effectively decreasing the coverage of a given repetitive stretch down to a minimum needed to correctly represent one copy of the repeat. However, contrary to the published method, MIRA will keep enough reads of repetitive regions to also correctly reconstruct slightly different variants of the repeats present in the genome or EST / RNASeq data set, even if they differ in only a single base.

  The tag used by MIRA to denote stretches which may have contributed to the digital normalisation will be "DGNr". Additionally, contigs which contain reads completely covered by a DGNr tag will get an additional "_dn" as part of their name to show that they contain read representatives for digital normalisation. E.g.: "contig_dn_c1" or "contig_dn_rep_c2"

repeatlevel_in_infofile(rliif)=integer; 0, 5-8

  Default is 6. Sets the minimum level of the HAF tags from which on MIRA will report tentatively repetitive sequence in the `*_info_readrepeats.lst` file of the info directory.

  A value of 0 means "switched off". The default value of 6 means all subsequences tagged with HAF6, HAF7 and MNRr will be logged. If you, e.g., only wanted MNRr logged, you'd use 8 as parameter value.

  See also -HS:fenn:fexn:fer:fehr:mnr:nrr to set the different levels for the HAF and MNRr tags.

#### Parameter group: -ALIGN (-AL)

The align options control the behaviour of the Smith-Waterman alignment routines. Only read pairs which are confirmed here may be included into contigs. Affects both the checking of possible alignments found by SKIM as well as the phase when reads are integrated into a contig.

Every option in this section can be set individually for every sequencing technology, giving a very fine grained control on how reads are aligned for each technology.

bandwidth_in_percent(bip)=integer > 0 and ≤100

  Default is dependent of the sequencing technology used. The banded Smith-Waterman alignment uses this percentage number to compute the bandwidth it has to use when computing the alignment matrix. E.g., expected overlap is 150 bases, bip=10 -> the banded SW will compute a band of 15 bases to each side of the expected alignment diagonal, thus allowing up to 15 unbalanced inserts / deletes in the alignment. INCREASING AND DECREASING THIS NUMBER: increase: will find more non-optimal alignments, but will also increase SW runtime between linear and \Circum2. decrease: the other way round, might miss a few bad alignments but gaining speed.

bandwidth_min(bmin)=integer > 0

  Default is dependent of the sequencing technology used. Minimum bandwidth in bases to each side.

bandwidth_max(bmax)=integer > 0

  Default is dependent of the sequencing technology used. Maximum bandwidth in bases to each side.

min_overlap(mo)=integer > 0

  Default is dependent of the sequencing technology used. Minimum number of overlapping bases needed in an alignment of two sequences to be accepted.

min_score(ms)=integer > 0

  Default is dependent of the sequencing technology used. Describes the minimum score of an overlap to be taken into account for assembly. MIRA uses a default scoring scheme for SW align: each match counts 1, a match with an N counts 0, each mismatch with a non-N base -1 and each gap -2. Take a bigger score to weed out a number of chance matches, a lower score to perhaps find the single (short) alignment that might join two contigs together (at the expense of computing time and memory).

min_relative_score(mrs)=integer > 0 and ≤100

  Default is dependent of the sequencing technology used. Describes the min % of matching between two reads to be considered for assembly. Increasing this number will save memory, but one might loose possible alignments. I propose a maximum of 80 here. Decreasing below 55% will make memory and time consumption probably explode.

  Note: most of the time it makes sense to keep this parameter in sync with -SK:pr.

solexa_hack_max_errors(shme)=integer > -1

  Currently a hack just for Solexa/Illumina data. When running in mapping mode, this defines the maximum number of mismatches and gaps a read may have compared to the reference to be allowed to map.

  The default value of -1 lets MIRA choose this value automatically. It sets it to 15% of the average read lengths loaded.

extra_gap_penalty(egp)=on|y[es]|t[rue], off|n[o]|f[alse]

  Default is dependent of the sequencing technology used. Defines whether or not to increase penalties applied to alignments containing long gaps. Setting this to 'yes' might help in projects with frequent repeats. On the other hand, it is definitively disturbing when assembling very long reads containing multiple long indels in the called base sequence ... although this should not happen in the first place and is a sure sign for problems lying ahead.

  When in doubt, set it to yes for EST projects and de-novo genome assembly, set it to no for assembly of closely related strains (assembly against a backbone).

  When set to no, it is recommended to have -CO:amgb and -CO:amgbemc both set to yes.

egp_level(egpl)=low|0, medium|1, high|2, split_on_codongaps|10

  Default is dependent of the sequencing technology used. Has no effect if extra_gap_penalty is off. Defines an extra penalty applied to 'long' gaps. There are these are predefined levels: low - use this if you expect your base caller frequently misses 2 or more bases. medium - use this if your base caller is expected to frequently miss 1 to 2 bases. high - use this if your base caller does not frequently miss more than 1 base.

  For some stages of the EST assembly process, a special value split_on_codongaps is used. It's even a tick harsher that the 'high' level.

  Also, usage of this parameter is probably a good thing if the repeat marker of the contig is set to not mark on gap bases (-CO:amgb equals to no). This is generally the case for 454 data.

egp_level(megpp)=0 ≤ integer ≤ 100

  Default is 100. Has no effect if extra_gap_penalty is off. Defines the maximum extra penalty in percent applied to 'long' gaps.

#### Parameter group: -CONTIG (-CO)

The contig options control the behaviour of the contig objects.

name_prefix(np)=string

  Default is <projectname>. Contigs will have this string prepended to their names. The -project= quick-switch will also change this option.

reject_on_drop_in_relscore(rodirs)=integer > 0 and ≤100

  Default is dependent of the sequencing technology used. When adding reads to a contig, reject the reads if the drop in the quality of the consensus is > the given value in %. Lower values mean stricter checking. This value is doubled should a read be entered that has a template partner (a read pair) at the right distance.

mark_repeats(mr)=on|y[es]|t[rue], off|n[o]|f[alse]

  Default is yes. One of the most important switches in MIRA: if set to yes, MIRA will try to resolve misassemblies due to repeats by identifying single base stretch differences and tag those critical bases as RMB (Repeat Marker Base, weak or strong). This switch is also needed when MIRA is run in EST mode to identify possible inter-, intra- and intra-and-interorganism SNPs.

only_in_result(mroir)=on|y[es]|t[rue], off|n[o]|f[alse]

  Default is no. Only takes effect when -CO:mr (see above) is set to yes. If set to yes, MIRA will not use the repeat resolving algorithm during build time (and therefore will not be able to take advantage of this), but only before saving results to disk.

  This switch is useful in some (rare) cases of mapping assembly.

assume_snp_instead_repeat(asir)=on|y[es]|t[rue], off|n[o]|f[alse]

  Default is no. Only takes effect when -CO:mr (see above) is set to yes, effect is also dependent on the fact whether strain data (see --SB:lsd) is present or not. Usually, MIRA will mark bases that differentiate between repeats when a conflict occurs between reads that belong to one strain. If the conflict occurs between reads belonging to different strains, they are marked as SNP. However, if this switch is set to yes, conflict within a strain are also marked as SNP.

  This switch is mainly used in assemblies of ESTs, it should not be set for genomic assembly.

min_reads_per_group(mrpg)=integer ≥ 2

  Default is dependent of the sequencing technology used. Only takes effect when -CO:mr (see above) is set to yes. This defines the minimum number of reads in a group that are needed for the RMB (Repeat Marker Bases) or SNP detection routines to be triggered. A group is defined by the reads carrying the same nucleotide for a given position, i.e., an assembly with mrpg=2 will need at least two times two reads with the same nucleotide (having at least a quality as defined in -CO:mgqrt) to be recognised as repeat marker or a SNP. Setting this to a low number increases sensitivity, but might produce a few false positives, resulting in reads being thrown out of contigs because of falsely identified possible repeat markers (or wrongly recognised as SNP).

min_neighbour_qual (mnq)=integer ≥ 10

  Default is dependent of the sequencing technology used. Takes only effect when -CO:mr is set to yes. This defines the minimum quality of neighbouring bases that a base must have for being taken into consideration during the decision whether column base mismatches are relevant or not.

min_groupqual_for_rmb_tagging(mgqrt)=integer ≥ 25

  Default is dependent of the sequencing technology used. Takes only effect when -CO:mr is set to yes. This defines the minimum quality of a group of bases to be taken into account as potential repeat marker. The lower the number, the more sensitive you get, but lowering below 25 is not recommended as a lot of wrongly called bases can have a quality approaching this value and you'd end up with a lot of false positives. The higher the overall coverage of your project, the better, and the higher you can set this number. A value of 35 will probably remove most false positives, a value of 40 will probably never show false positives ... but will generate a sizable number of false negatives.

endread_mark_exclusion_area(emea)=integer ≥ 0

  Default is dependent of the sequencing technology used. Takes only effect when -CO:mr is set to yes. Using the end of sequences of Sanger type shotgun sequencing is always a bit risky, as wrongly called bases tend to crowd there or some sequencing vector relics hang around. It is even more risky to use these stretches for detecting possible repeats, so one can define an exclusion area where the bases are not used when determining whether a mismatch is due to repeats or not.

emea_set1_on_clipping_pec(emeas1clpec)=on|y[es]|t[rue], off|n[o]|f[alse]

  Default is yes. When -CL:pec is set, the end-read exclusion area can be considerably reduced. Setting this parameter will automatically do this.

  Although the parameter is named "set to 1", it may be that the exclusion area is actually a bit larger (2 to 4), depending on what users will report back as "best" option.

also_mark_gap_bases(amgb)=on|y[es]|t[rue], off|n[o]|f[alse]

  Default is dependent of the sequencing technology used. Determines whether columns containing gap bases (indels) are also tagged.

  Note: it is strongly recommended to not set this to 'yes' for 454 type data.

also_mark_gap_bases_even_multicolumn(amgbemc)=on|y[es]|t[rue], off|n[o]|f[alse]

  Default is yes. Takes effect only when -CO:amgb is set to yes. Determines whether multiple columns containing gap bases (indels) are also tagged.

also_mark_gap_bases_need_both_strands(amgbnbs)=on|y[es]|t[rue], off|n[o]|f[alse]

  Default is yes. Takes effect only when -CO:amgb is set to yes. Determines whether both for tagging columns containing gap bases, both strands.need to have a gap. Setting this to no is not recommended except when working in desperately low coverage situations.

force_nonIUPACconsensus_perseqtype(fnicpst)=on|y[es]|t[rue], off|n[o]|f[alse]

  Default is no for all sequencing types. If set to yes, MIRA will be forced to make a choice for a consensus base (A,C,G,T or gap) even in unclear cases where it would normally put a IUPAC base. All other things being equal (like quality of the possible consensus base and other things), MIRA will choose a base by either looking for a majority vote or, if that also is not clear, by preferring gaps over T over G over C over finally A.

  MIRA makes a considerable effort to deduce the right base at each position of an assembly. Only when cases begin to be borderline it will use a IUPAC code to make you aware of potential problems. It is suggested to leave this option to no as IUPAC bases in the consensus are a sign that - if you need 100% reliability - you really should have a look at this particular place to resolve potential problems. You might want to set this parameter to yes in the following cases: 1) when your tools that use assembly result cannot handle IUPAC bases and you don't care about being absolutely perfect in your data (by looking over them manually). 2) when you assemble data without any quality values (which you should not do anyway), then this method will allow you to get a result without IUPAC bases that is "good enough" with respect to the fact that you did not have quality values.

  Important note: in case you are working with a hybrid assembly, MIRA will still use IUPAC bases at places where reads from different sequencing types contradict each other. In fact, when not forcing non-IUPAC bases for hybrid assemblies, the overall consensus will be better and probably have less IUPAC bases as MIRA can make a better use of available information.

merge_short_reads(msr)=on|y[es]|t[rue], off|n[o]|f[alse]

  Default is yes for all Solexas when in a mapping assembly, else it's no. Can only be used in mapping assemblies. If set to yes, MIRA will merge all perfectly mapping Solexa reads into longer reads (Coverage Equivalent Reads, CERs) while keeping quality and coverage information intact.

  This feature hugely reduces the number of Solexa reads and makes assembly results with Solexa data small enough to be handled by current finishing programs (gap4, consed, others) on normal workstations.

msr_keepcontigendsunmerged(msrme)=integer ≥ 0

  Default is 0 for all Solexas when in a mapping assembly. Takes only effect in mapping assemblies if -CO:msr=yes.

  Defines how many "errors" (i.e. differences) a read may have to be merged into a coverage equivalent read. Useful only when one does not need SNP information from an assembly but wants to concentrate either on coverage data or on paired-end information at contig ends.

  This feature allows to merge non-perfect reads, which makes most SNP information simply disappear from the alignment. Use with care!

msr_keepcontigendsunmerged(msrkceu)=-1, integer > 0

  Default is -1 for all Solexas when in a mapping assembly. Takes only effect in mapping assemblies if -CO:msr=yes and for reads which have a paired-end / mate-pair partner actively used in the assembly.

  If set to a value > 0, MIRA will not merge paired-end / mate-pair reads if they map within the given distance of a contig end of the original reference sequence (backbone). Instead of a fixed value, one can also use -1. MIRA will then automatically not merge reads if the distance from the contig end is within the maximum size of the template insert size of the sequencing library for that read (either given via -GE:tismax or via XML TRACEINFO for the given read).

  This feature allows to use the data reduction from -CO:msr while enabling the result of such a mapping to be useful in subsequent scaffolding programs to order contigs.

#### Parameter group: -EDIT (-ED)

General options for controlling the integrated automatic editor. The editors generally make a good job cleaning up alignments from typical sequencing errors like (like base overcalls etc.). However, they may prove tricky in certain situations:

- in EST assemblies, they may edit rare transcripts toward almost identical, more abundant transcripts. Usage must be carefully weighed.

- the editors will not only change bases, but also sometimes delete or insert non-gap bases as needed to improve an alignment when facts (trace signals or other) show that this is what should have been the sequence. However, this can make post processing of assembly results pretty difficult with some formats like ACE, where the format itself contains no way to specify certain edits like deletion. There's nothing one can do about it and the only way to get around this problem is to use file formats with more complete specifications like CAF, MAF (and BAF once supported by MIRA).

The following edit parameters are supported:

automatic_contig_editing(ace)=on|y[es]|t[rue], off|n[o]|f[alse]

  Default is no. Once contigs have been build, MIRA can call a built-in versions of the automatic contig editors. For Sanger reads this is EdIt, for 454 reads it is a specially crafted editor that knows about deficiencies of the 454 technology (homopolymers).

  EdIt will try to resolve discrepancies in the contig by performing trace analysis and correct even hard to resolve errors. This option is always useful, but especially in conjunction with -AS:nop and -DP:ure (see above).

  Notice 1: the current development version has a memory leak in the editor, therefore the option is not automatically turned on.

  Notice 2: it is strongly suggested to turn this option on for 454 data as this greatly improves the quality.

strict_editing_mode(sem)=on|y[es]|t[rue], off|n[o]|f[alse]

  Default is yes. Only for Sanger data. If set to yes, the automatic editor will not take error hypotheses with a low probability into account, even if all the requirements to make an edit are fulfilled.

confirmation_threshold(ct)=integer, 0 < x ≤ 100

  Default is 50. Only for Sanger data. The higher this value, the more strict the automatic editor will apply its internal rule set. Going below 40 is not recommended.

#### Parameter group: -MISC (-MI)

Options which would not fit elsewhere.

large_contig_size(lcs)=integer < 0

  Default is 500. This parameter has absolutely no influence whatsoever on the assembly process of MIRA. But is used in the reporting within the `*_assembly_info.txt` file after the assembly where MIRA reports statistics on large and all contigs. -MI:lcs is the threshold value for categorising contigs.

large_contig_size_for_stats(lcs4s)=integer < 0

  Default is 5000 for --job=genome and 1000 for --job=est.

  This parameter is used for internal statistics calculations and has a subtle influence when being in a --job=genome assembly mode.

  MIRA uses coverage information of an assembly project to find out about potentially repetitive areas in reads (and thus, a genome). To calculate statistics which are reflecting the approximate truth, the value of -MI:lcs4s is used as a cutoff threshold: contigs smaller than this value do not contribute to the calculation of average coverage while contigs larger or equal to this value do. Having this cutoff discards small contigs which tend to muddy the picture of average coverage of a project.

  If in doubt, don't touch this parameter.

#### Parameter group: -NAG_AND_WARN (-NW)

Parameters which let MIRA warn you about unusual things or potential problems.

stop_on_nfs(sonfs)=on|y[es]|t[rue], off|n[o]|f[alse]

  Default is yes. MIRA will check whether the tmp directory is running on an NFS mount. If it is and -MI:sonfs is active, MIRA will stop with a warning message.

  You should never ever at all run MIRA on a NFS mounted directory ... or face the the fact that the assembly process may very well take 5 to 10 times longer (or more) than normal. You have been warned.

  The reason for the slowdown is the same as why one should never run a BLAST search on a big database being located on a NFS volume: access via network is terribly slow when compared to local disks, at least if you have not invested a lot of money into specialised solutions.

stop_on_maxreadnamelength(somrnl)=integer ≥ 0

  Default is 40. MIRA will check whether the length of the names of your reads surpass the given number and stop if this is the case. A value of 0 will switch off the check.

  While MIRA and many other programs have no problem with that, some older programs have restrictions concerning the length of the read name. Example given: the pipeline `CAF -> caf2gap -> gap2caf` will stop working at the `gap2caf` stage if there are read names having > 40 characters where the names differ only at >40 characters.

  This is a warning only, but as a couple of people were bitten by this, the default behaviour of MIRA is to stop when it sees that potential problem. You might want to rename your reads to have ≤ 40 characters

  On the other hand, you also can ignore this potential problem and force MIRA to continue by using the parameter: -NW:somrnl=0

#### Parameter group: -DIRECTORY (-DIR, -DI)

General options for controlling where to find or where to write data.

tmp_redirected_to(trt)=<directoryname>

  Default is an empty string. When set to a non-empty string, MIRA will create the tmp directory at the given location instead of using the current working directory.

  This option is particularly useful for systems which have solid state disks (SSDs) and some very fast disk subsystems which can be used for temporary files. Or in projects where the input and output files reside on a NFS mounted directory (current working dir), to put the tmp directory somewhere outside the NFS (see also: Things you should not do).

  In both cases above, and for larger projects, MIRA then runs a lot faster.

#### Parameter group: -OUTPUT (-OUT)

Options for controlling which results to write to which type of files. Additionally, a few options allow output customisation of textual alignments (in text and HTML files).

There are 3 types of results: result, temporary results and extra temporary results. One probably needs only the results. Temporary and extra temporary results are written while building different stages of a contig and are given as convenience for trying to find out why MIRA set some RMBs or disassembled some contigs.

Output can be generated in these formats: CAF, Gap4 Directed Assembly, FASTA, ACE, TCS, WIG, HTML and simple text.

Naming conventions of the files follow the rules described in section Input / Output, subsection Filenames.

savesimplesingletsinproject(sssip)=on|y[es]|t[rue],off|n[o]|f[alse]

  Default is no. Controls whether 'unimportant' singlets are written to the result files.

  Note that a value larger 1 of the -AS:mrpc parameter will disable the function of this parameter.

savetaggedsingletsinproject(stsip)=on|y[es]|t[rue],off|n[o]|f[alse]

  Default is yes. Controls whether singlets which have certain tags (see below) are written to the result files, even if -OUT:sssip (see above) is set.

  If one of the (SRMr, CRMr, WRMr, SROr, SAOr, SIOr) tags appears in a singlet, MIRA will see that the singlets had been part of a larger alignment in earlier passes and even was part of a potentially 'important' decision. To give the possibility to human finishers to trace back the decision, these singlets can be written to result files.

  Note that a value larger 1 of the -AS:mrpc parameter will disable the function of this parameter.

remove_rollover_tmps(rrot)=on|y[es]|t[rue], off|n[o]|f[alse]

  Default is yes. Removes log and temporary files once they should not be needed anymore during the assembly process.

remove_tmp_directory(rtd)=on|y[es]|t[rue], off|n[o]|f[alse]

  Default is no. Removes the complete tmp directory at the end of the assembly process. Some logs and temporary files contain useful information that you may want to analyse though, therefore the default of MIRA is not to delete it.

output_result_caf(orc)=on|y[es]|t[rue], off|n[o]|f[alse]

  Default is yes.

output_result_maf(orm)=on|y[es]|t[rue], off|n[o]|f[alse]

  Default is yes.

output_result_gap4da(org)=on|y[es]|t[rue], off|n[o]|f[alse]

  Default is yes for projects only with Sanger reads, 'no' as soon as there are 454, Solexa or SOLiD reads involved.

  MIRA will automatically switch to no (and cannot be forced to 'yes') when 454 or Solexa reads are present in the project as this ensure that the file system does not get flooded with millions of files.

output_result_fasta(orf)=on|y[es]|t[rue], off|n[o]|f[alse]

  Default is yes.

output_result_ace(ora)=on|y[es]|t[rue], off|n[o]|f[alse]

  Default is no.

  The ACE output of MIRA is conforming to the file specification given in the consed documentation. However, due to a bug in consed, consed cannot correctly load tags set by MIRA.

  There is a workaround: the MIRA distribution comes with a small Tcl script `fixACE4consed.tcl` which implements a workaround to allow consed loading the ACE generated by MIRA. Use the script like this:

      $ fixACE4consed.tcl infile.ace >outfile.ace

  and then load the resulting outfile into consed.

  ACE is the least suited file format for NGS data. Use it only when absolutely necessary.

output_result_txt(ort)=on|y[es]|t[rue], off|n[o]|f[alse]

  Default is no.

output_result_tcs(ors)=on|y[es]|t[rue], off|n[o]|f[alse]

  Default is yes.

output_result_html(orh)=on|y[es]|t[rue], off|n[o]|f[alse]

  Default is no.

output_tmpresult_caf(otc)=on|y[es]|t[rue], off|n[o]|f[alse]

  Default is no.

output_tmpresult_maf(otm)=on|y[es]|t[rue], off|n[o]|f[alse]

  Default is no.

output_tmpresult_gap4da(otg)=on|y[es]|t[rue], off|n[o]|f[alse]

  Default is no.

output_tmpresult_fasta(otf)=on|y[es]|t[rue], off|n[o]|f[alse]

  Default is no.

output_tmpresult_ace(ota)=on|y[es]|t[rue], off|n[o]|f[alse]

  Default is no.

output_tmpresult_txt(ott)=on|y[es]|t[rue], off|n[o]|f[alse]

  Default is no.

output_result_tcs(ots)=on|y[es]|t[rue], off|n[o]|f[alse]

  Default is no.

output_tmpresult_html(oth)=on|y[es]|t[rue], off|n[o]|f[alse]

  Default is no.

output_exttmpresult_caf(oetc)=on|y[es]|t[rue], off|n[o]|f[alse]

  Default is no.

output_exttmpresult_gap4da(oetg)=on|y[es]|t[rue], off|n[o]|f[alse]

  Default is no.

output_exttmpresult_fasta(oetf)=on|y[es]|t[rue], off|n[o]|f[alse]

  Default is no.

output_exttmpresult_ace(oeta)=on|y[es]|t[rue], off|n[o]|f[alse]

  Default is no.

output_exttmpresult_txt(oett)=on|y[es]|t[rue], off|n[o]|f[alse]

  Default is no.

output_exttmpresult_html(oeth)=on|y[es]|t[rue], off|n[o]|f[alse]

  Default is no.

text_chars_per_line(tcpl)=integer > 0

  Default is 60. When producing an output in text format (-OUT:ort|ott|oett), this parameter defines how many bases each line of an alignment should contain.

html_chars_per_line(tcpl)=integer > 0

  Default is 60. When producing an output in HTML format, (-OUT:orh|oth|oeth), this parameter defines how many bases each line of an alignment should contain.

text_endgap_fillchar(tegfc)=<single character>

  Default is (a blank). When producing an output in text format (-OUT:ort|ott|oett), endgaps are filled up with this character.

html_endgap_fillchar(hegfc)=<single character>

  Default is (a blank). When producing an output in HTML format (-OUT:orh|oth|oeth), end-gaps are filled up with this character.

## Resuming assemblies

It may happen that a MIRA run is interrupted - sometimes rather harshly - due to events more or less outside your control like, e.g., power failures, machine shutdowns for maintenance, missing disk space, run-time quotas etc. This may be less of a problem when assembling or mapping small data sets with run times between a couple of minutes up to a few hours, but becomes a nuisance for larger data sets like in small eukaryotes or RNASeq samples where the run time is measured in days.

For cases like these, MIRA has a resume functionality: at predefined points in the assembly process, MIRA writes out special files to disk which enables it to resume the assembly at the point where these files were written. Starting MIRA in resume mode is pretty easy: simply add the resume flag -r on a command line like this:

    $ mira -r ...

where the ellipsis ("...") above stands for the rest of the command line you would have used to start a new assembly.

## Input / Output

### Directories

Since version 3.0.0, MIRA now puts all files and directories it generates into one sub-directory which is named `projectname_assembly`. This directory contains up to four sub-directories:

- `projectname_d_results`: this directory contains all the output files of the assembly in different formats.

- `projectname_d_info`: this directory contains information files of the final assembly. They provide statistics as well as, e.g., information (easily parseable by scripts) on which read is found in which contig etc.

- `projectname_d_tmp`: this directory contains tmp files and temporary assembly files. It can be safely removed after an assembly as there may be easily a few GB of data in there that are not normally not needed anymore.

  In case of problems: please do not delete. I will get in touch with you for additional information that might possibly be present in the tmp directory.

- `projectname_d_chkpt`: this directory contains checkpoint files needed to resume assemblies that crashed or were stopped.

### Filenames

#### Output

These result output files and sub-directories are placed in in the projectname_results directory after a run of MIRA.

`projectname_out.<type>`

  Assembled project written in type = (maf / gap4da / caf / ace / fasta / html / tcs / wig / text) format by MIRA, final result.

  Type gap4da is a directory containing experiment files and a file of filenames (called 'fofn'), all other types are files. gap4da, caf, ace contain the complete assembly information suitable for import into different post-processing tools (gap4, consed and others). html and text contain visual representations of the assembly suited for viewing in browsers or as simple text file. tcs is a summary of a contig suited for "quick" analyses from command-line tools or even visual inspection. wig is a file containing coverage information (useful for mapping assemblies) which can be loaded and shown by different genome browsers (IGB, GMOD, USCS and probably many more.

  fasta contains the contig consensus sequences (and .fasta.qual the consensus qualities). Please note that they come in two flavours: padded and unpadded. The padded versions may contain stars (*) denoting gap base positions where there was some minor evidence for additional bases, but not strong enough to be considered as a real base. Unpadded versions have these gaps removed. Padded versions have an additional postfix .padded, while unpadded versions .unpadded.

#### Assembly statistics and information files

These information files are placed in in the projectname_info directory after a run of MIRA.

`projectname_info_assembly.txt`

  This file contains basic information about the assembly. MIRA will split the information in two parts: information about large contigs and information about all contigs.

  For more information on how to interpret this file, please consult the chapter on "Results" of the MIRA documentation manual.

  In contrast to other information files, this file always appears in the "info" directory, even when just intermediate results are reported.

`projectname_info_contigreadlist.txt`

  This file contains information which reads have been assembled into which contigs (or singlets).

`projectname_info_contigstats.txt`

  This file contains statistics about the contigs themselves, their length, average consensus quality, number of reads, maximum and average coverage, average read length, number of A, C, G, T, N, X and gaps in consensus.

`projectname_info_consensustaglist.txt`

  This file contains information about the tags (and their position) that are present in the consensus of a contig.

`projectname_info_readrepeats.lst`

  Tab delimited file with three columns: read name, repeat level tag, sequence.

  This file permits a quick analysis of the repetitiveness of different parts of reads in a project. See -SK:rliif to control from which repetitive level on subsequences of reads are written to this file,

  Reads can have more than one entry in this file. E.g., with standard settings (`-SK:rliif=6`) if the start of a read is covered by MNRr, followed by a HAF3 region and finally the read ends with HAF6, then there will be two lines in the file: one for the subsequence covered by MNRr, one for HAF6.

`projectname_info_readstooshort`

  A list containing the names of those reads that have been sorted out of the assembly before any processing started only due to the fact that they were too short.

`projectname_info_readtaglist.txt`

  This file contains information about the tags and their position that are present in each read. The read positions are given relative to the forward direction of the sequence (i.e. as it was entered into the the assembly).

`projectname_error_reads_invalid`

  A list of sequences that have been found to be invalid due to various reasons (given in the output of the assembler).

### File formats

MIRA can write almost all of the following formats and can read most of them.

`EXP`

  Standard experiment files used in genome sequencing. Correct EXP files are expected. Especially the ID record (containing the id of the reading) and the LN record (containing the name of the corresponding trace file) should be correctly set. See for links to online format description.

`SCF`

  The Staden trace file format that has established itself as compact standard replacement for the much bigger ABI files. See for links to online format description.

  The SCF files should be V2-8bit, V2-16bit, V3-8bit or V3-16bit and can be packed with compress or gzip.

`CAF`

  Common Assembly Format (CAF) developed by the Sanger Centre. provides a description of the format and some software documentation as well as the source for compiling caf2gap and gap2caf (thanks to Rob Davies for this).

`ACE`

  The assembly file format used mainly by phrap and consed. Support for .ace output is currently only in test status in MIRA as documentation on that format is ... sparse and I currently don' have access to consed to verify my assumptions.

  Using consed, you will need to load projects with -nophd to view them. Tags /in reads and consensus) are fully supported. The only hitch: consed has a bug which prevents it to read consensus tags which are located throughout the whole file (as MIRA writes per default). The solution to that is easy: filter the CAF file through the fixACE4consed.tcl script which is provided in the MIRA distributions, then all should be well.

  If you don't have consed, you might want to try clview () from TIGR to look at .ace files.

`MAF`

  MIRA Assembly Format (MAF). A faster and more compact form than EXP, CAF or ACE. See documentation in separate file.

`HTML`

  Hypertext Markup Language. Projects written in HTML format can be viewed directly with any table capable browser. Display is even better if the browser knows style sheets (CSS).

`FASTA`

  A simple format for sequence data, see . An often used extension of that format is used to also store quality values in a similar fashion, these files have a .fasta.qual ending.

  MIRA writes two kinds of FASTA files for results: padded and unpadded. The difference is that the padded version still contains the gap (pad) character (an asterisk) at positions in the consensus where some of the reads apparently had some more bases than others but where the consensus routines decided that to treat them as artifacts. The unpadded version has the gaps removed.

`PHD`

  This file type originates from the phred base caller and contains basically -- along with some other status information -- the base sequence, the base quality values and the peak indices, but not the sequence traces itself.

`GBF, GBK`

  GenBank file format as used at the NCBI to describe sequences. MIRA is able to read this format for using sequences as backbones in an assembly. Features of the GenBank format are also transferred automatically to Staden compatible tags.

`traceinfo.XML`

  XML based file with information relating to traces. Used at the NCBI and ENSEMBL trace archive to store additional information (like clippings, insert sizes etc.) for projects. See further down for for a description of the fields used and for a full description of all fields.

`TCS`

  Transpose Contig Summary. A text file as written by MIRA which gives a summary of a contig in tabular fashion, one line per base. Nicely suited for "quick" analyses from command line tools, scripts, or even visual inspection in file viewers or spreadsheet programs.

  In the current file version (TCS 1.0), each column is separated by at least one space from the next. Vertical bars are inserted as visual delimiter to help inspection by eye. The following columns are written into the file:

  1. contig name (width 20)

  2. padded position in contigs (width 3)

  3. unpadded position in contigs (width 3)

  4. separator (a vertical bar)

  5. called consensus base

  6. quality of called consensus base (0-100), but MIRA itself caps at 90.

  7. separator (a vertical bar)

  8. total coverage in number of reads. This number can be higher than the sum of the next five columns if Ns or IUPAC bases are present in the sequence of reads.

  9. coverage of reads having an "A"

  10. coverage of reads having an "C"

  11. coverage of reads having an "G"

  12. coverage of reads having an "T"

  13. coverage of reads having an "*" (a gap)

  14. separator (a vertical bar)

  15. quality of "A" or "--" if none

  16. quality of "C" or "--" if none

  17. quality of "G" or "--" if none

  18. quality of "T" or "--" if none

  19. quality of "*" (gap) or "--" if none

  20. separator (a vertical bar)

  21. Status. This field sums up the evaluation of MIRA whether you should have a look at this base or not. The content can be one of the following:

      - everything OK: a colon (:)

      - unclear base calling (IUPAC base): a "!M"

      - potentially problematic base calling involving a gap or low quality: a "!m"

      - consensus tag(s) of MIRA that hint to problems: a "!$". Currently, the following tags will lead to this marker: SRMc, WRMc, DGPc, UNSc, IUPc.

  22. list of a consensus tags at that position, tags are delimited by a space. E.g.: "DGPc H454"

### STDOUT/STDERR

The actual stage of the assembly is written to STDOUT, giving status messages on what MIRA is actually doing. Dumping to STDERR is almost not used anymore by MIRA, remnants will disappear over time.

Some debugging information might also be written to STDOUT if MIRA generates error messages.

On errors, MIRA will dump these also to STDOUT. Basically, three error classes exist:

1. WARNING: Messages in this error class do not stop the assembly but are meant as an information to the user. In some rare cases these errors are due to (an always possible) error in the I/O routines of MIRA, but nowadays they are mostly due to unexpected (read: wrong) input data and can be traced back to errors in the preprocessing stages. If these errors arise, you definitively DO want to check how and why these errors came into those files in the first place.

   Frequent cause for warnings include missing SCF files, SCF files containing known quirks, EXP files containing known quirks etc.

2. FATAL: Messages in this error class actually stop the assembly. These are mostly due to missing files that MIRA needs or to very garbled (wrong) input data.

   Frequent causes include naming an experiment file in the 'file of filenames' that could not be found on the disk, same experiment file twice in the project, suspected errors in the EXP files, etc.

3. INTERNAL: These are true programming errors that were caught by internal checks. Should this happen, please mail the output of STDOUT and STDERR to the author.

### SSAHA2 / SMALT ancillary data

The `ssaha2` or `smalt` programs - both from the Sanger Centre - can be used to detect possible vector sequence stretches in the input data for the assembly. MIRA can load the result files of a `ssaha2` or `smalt` run and interpret the results to tag the possible vector sequences at the ends of reads.

Note that this also uses the parameters -CL:msvsgs:msvsmfg:msvsmeg (see below).

ssaha2 must be called like this "`ssaha2 <ssaha2options> vector.fasta sequences.fasta`" to generate an output that can be parsed by MIRA. In the above example, replace `vector.fasta` by the name of the file with your vector sequences and `sequences.fasta` by the name of the file containing your sequencing data.

smalt must be called like this: "`smalt map -f ssaha <ssaha2options> hash_index sequences.fasta`"

This makes you basically independent from any other commercial or license-requiring vector screening software. For Sanger reads, a combination of `lucy` and `ssaha2` or `smalt` together with this parameter should do the trick. For reads coming from 454 pyro-sequencing, `ssaha2` or `smalt` and this parameter will also work very well. See the usage manual for a walkthrough example on how to use SSAHA2 / SMALT screening data.

The output format of SSAHA2 must the native output format (`-output ssaha2`). For SMALT, the output option `-f ssaha` must be used. Other formats cannot be parsed by MIRA.

I currently use the following SSAHA2 options: `-kmer 8 -skip 1 -seeds 1 -score 12 -cmatch 9 -ckmer 6`

Anyone contributing SMALT parameters?

The sequence vector clippings generated from SSAHA2 / SMALT data do not replace sequence vector clippings loaded via the EXP, CAF or XML files, they rather extend them.

### XML TRACEINFO ancillary data

MIRA extracts the following data from the TRACEINFO files:

- trace_name (required)

- trace_file (recommended)

- trace_type_code (recommended)

- trace_end (recommended)

- clip_quality_left (recommended)

- clip_quality_right (recommended)

- clip_vector_left (recommended)

- clip_vector_right (recommended)

- strain (recommended)

- template_id (recommended for paired end)

- insert_size (recommended for paired end)

- insert_stdev (recommended for paired end)

- machine_type (optional)

- program_id (optional)

Other data types are also read, but the info is not used.

Here's the example for a TRACEINFO file with ancillary info:

    <?xml version="1.0"?>
    <trace_volume>
    <trace>
      <trace_name>GCJAA15TF</trace_name>
      <program_id>PHRED (0.990722.G) AND TTUNER (1.1)</program_id>
      <template_id>GCJAA15</template_id>
      <trace_direction>FORWARD</trace_direction>
      <trace_end>F</trace_end>
      <clip_quality_left>3</clip_quality_left>
      <clip_quality_right>622</clip_quality_right>
      <clip_vector_left>1</clip_vector_left>
      <clip_vector_right>944</clip_vector_right>
      <insert_stdev>600</insert_stdev>
      <insert_size>2000</insert_size>
    </trace>
    <trace>
      ...
    </trace>
    ...
    </trace_volume>

See for a full description of all fields and more info on the TRACEINFO XML format.

### Contig naming

MIRA names contigs the following way: <projectname>_<contigtype><number>. While <projectname> is dictated by the --project= parameter and <number> should be clear, the <contigtype> might need additional explaining. There are currently three contig types existing:

1. _c: these are "normal" contigs

2. _rep_c: these are contigs containing only repetitive areas. These contigs had _lrc as type in previous version of MIRA, this was changed to the _rep_c to make things clearer.

3. _s: these are singlet-contigs. Technically: "contigs" with a single read.

4. _dn: these is an additional contig type which can occur when MIRA ran a digital normalisation step during the assembly. Contigs which contain reads completely covered by a DGNr tag will get an additional "_dn" as part of their name to show that they contain read representatives for digital normalisation. E.g.: "contig_dn_c1" or "contig_dn_rep_c2".

   #### Important side note

   Due to the digital normalisation step, the coverage numbers in the info file regarding contig statistics will not represnt the number of reads in the contig, but they will show an approximation of the true coverage or expression value as if there had not been a digital normalisation step performed. The approximation may be around 10 to 20% below the true value.

Basically, for genome assemblies MIRA starts to build contigs in areas which seem "rock solid", i.e., not a repetitive region (main decision point) and nice coverage of good reads. Contigs which started like this get a _c name. If during the assembly MIRA reaches a point where it cannot start building a contig in a non-repetitive region, it will name the contig _rep_c instead of _c. This is why "_rep_c" contigs occur late in a genome assembly.

For EST/RNASeq assemblies, the distinction between _c and _rep_c makes less sense (a euphemism for "no sense at all"), but EST assemblies also use this scheme for no better reason than me not having an alternative or better naming scheme there. However, MIRA has a different understanding of "rock solid" when in EST/RNASeq assembly: here, MIRA will try to reconstruct a full length gene sequence, starting with the most abundant genes. This is why one more often sees "_rep" contigs at the beginning of a EST/RNASeq assembly.

Depending on the settings of -AS:mrpc, your project may or may not contain _s singlet-contigs. Also note that reads landing in the debris file will not get assigned to singlet-contigs and hence not get _s names.

### Recovering strain specific consensus as FASTA

In case you used strain information in an assembly, you can recover the consensus for just any given strain by using `convert_project` and convert from a full assembly format (e.g. MAF or CAF) which also carries strain information to FASTA. MIRA will automatically detect the strain information and create one FASTA file per strain encountered.

## Tags used in the assembly by MIRA and EdIt

MIRA uses and sets a couple of tags during the assembly process. That is, if information is known before the assembly, it can be stored in tags (in the EXP and CAF formats) and will be used in the assembly.

### Tags read (and used)

This section lists "foreign" tags, i.e., tags that whose definition was made by other software packages than MIRA.

- ALUS, REPT: Sequence stretches tagged as ALUS (ALU Sequence) or REPT (general repetitive sequence) will be handled with extreme care during the assembly process. The allowed error rate after automatic contig editing within these stretches is normally far below the general allowed error rate, leading to much higher stringency during the assembly process and subsequently to a better repeat resolving in many cases.

- FpAS: GenBank feature for a poly-A signal. Used in EST, cDNA or transcript assembly. Either read in the input files or set when using -CL:cpat. This allows to keep the poly-A signal in the reads during assembly without them interfering as massive repeats or as mismatches.

- FCDS, Fgen: GenBank features as described in GBF/GBK files or set in the Staden package are used to make some SNP impact analysis on genes.

- other. All other tags in reads will be read and passed through the assembly without being changed and they currently do not influence the assembly process.

### Tags set (and used)

This section lists tags which MIRA sets (and reads of course), but that other software packages might not know about.

- UNSr, UNSc: UNSure in Read respectively Contig. These tags denote positions in an assembly with conflicts that could not be resolved automatically by MIRA. These positions should be looked at during the finishing process.

  For assemblies using good sequences and enough coverage, something 0.01% of the consensus positions have such a tag. (e.g. ~300 UNSc tags for a genome of 3 megabases).

- SRMr, WRMc: Strong Repeat Marker and Weak Repeat Marker. These tags are set in two flavours: as SRMr and WRMr when set in reads, and as SRMc and WRMc when set in the consensus. These tags are used on an individual per base basis for each read. They denote bases that have been identified as crucial for resolving repeats, often denoting a single SNP within several hundreds or thousands of bases. While a SRM is quite certain, the WRM really is either weak (there wasn't enough comforting information in the vicinity to be really sure) or involves gap columns (which is always a bit tricky).

  MIRA will automatically set these tags when it encounters repeats and will tag exactly those bases that can be used to discern the differences.

  Seeing such a tag in the consensus means that MIRA was not able to finish the disentanglement of that special repeat stretch or that it found a new one in one of the last passes without having the opportunity to resolve the problem.

- DGPc: Dubious Gap Position in Consensus. Set whenever the gap to base ratio in a column of 454 reads is between 40% and 60%.

- SAO, SRO, SIO: SNP intrA Organism, SNP R Organism, SNP Intra and inter Organism. As for SRM and WRM, these tags have a r appended when set in reads and a c appended when set in the consensus. These tags denote SNP positions.

  MIRA will automatically set these tags when it encounters SNPs and will tag exactly those bases that can be used to discern the differences. They denote SNPs as they occur within an organism (SAO), between two or more organisms (SRO) or within and between organisms (SIO).

  Seeing such a tag in the consensus means that MIRA set this as a valid SNP in the assembly pass. Seeing such tags only in reads (but not in the consensus) shows that in a previous pass, MIRA thought these bases to be SNPs but that in later passes, this SNP does not appear anymore (perhaps due to resolved misassemblies).

- STMS: (only hybrid assemblies). The Sequencing Type Mismatch Solved is tagged to positions in the assembly where the consensus of different sequencing technologies (Sanger, 454, Ion Torrent, Solexa, PacBio, SOLiD) reads differ, but MIRA thinks it found out the correct solution. Often this is due to low coverage of one of the types and an additional base calling error.

  Sometimes this depicts real differences where possible explanation might include: slightly different bugs were sequenced or a mutation occurred during library preparation.

- STMU: (only hybrid assemblies). The Sequencing Type Mismatch Unresolved is tagged to positions in the assembly where the consensus of different sequencing technologies (Sanger, 454, Ion Torrent, Solexa, SOLiD) reads differ, but MIRA could not find a good resolution. Often this is due to low coverage of one of the types and an additional base calling error.

  Sometimes this depicts real differences where possible explanation might include: slightly different bugs were sequenced or a mutation occurred during library preparation.

- MCVc: The Missing Co{V}erage in Consensus. Set in assemblies with more than one strain. If a strain has no coverage at a certain position, the consensus gets tagged with this tag (and the name of the strain which misses this position is put in the comment). Additionally, the sequence in the result files for this strain will have an @ character.

- MNRr: (only with -HS:mnr active). The Masked Nasty Repeat tags are set over those parts of a read that have been detected as being many more times present than the average sub-sequence. MIRA will hide these parts during the initial all-against-all overlap finding routine (SKIM3) but will otherwise happily use these sequences for consensus generation during contig building.

- FpAS: See "Tags read (and used)" above.

- ED_C, ED_I, ED_D: EDit Change, EDit Insertion, EDit Deletion. These tags are set by the integrated automatic editor EdIt and show which edit actions have been performed.

- HAF2, HAF3, HAF4, HAF5, HAF6, HAF7. These are HAsh Frequency tags which show the status of read parts in comparison to the whole project. Only set if -AS:ard is active (default for genome assemblies).

  More info on how to use the information conveyed by HAF tags in the section dealing with repeats and HAF tags in finishing programs further down in this manual.

  HAF2 coverage below average ( standard setting at < 0.5 times average)

  HAF3 coverage is at average ( standard setting at ≥ 0.5 times average and ≤ 1.5 times average)

  HAF4 coverage above average ( standard setting at > 1.5 times average and < 2 times average)

  HAF5 probably repeat ( standard setting at ≥ 2 times average and < 5 times average)

  HAF6 'heavy' repeat ( standard setting at > 8 times average)

  HAF7 'crazy' repeat ( standard setting at > 20 times average)

## Where reads end up: contigs, singlets, debris

At the start, things are simple: a read either aligns with other reads or it does not. Reads which align with other reads form contigs, and these MIRA will save in the results with a contig name of _c.

However, not all reads can be placed in an assembly. This can have several reasons and these reads may end up at two different places in the result files: either in the debris file, then just as a name entry, or as singlet (a "contig" with just one read) in the regular results.

1. reads are too short and get filtered out (before or after the MIRA clipping stages). These invariably land in the debris file.

2. reads are real singlets: they contain genuine sequence but have no overlap with any other read. These get either caught by the -CL:pec clipping filter or during the SKIM phase

3. reads contain mostly or completely junk.

4. reads contain chimeric sequence (therefore: they're also junk)

MIRA filters out these reads in different stages: before and after read clipping, during the SKIM stage, during the Smith-Waterman overlap checking stage or during contig building.

The exact place where these single reads land is dependend on why they do not align with other reads.

## Detection of bases distinguishing non-perfect repeats and SNP discovery

MIRA is able to find and tag SNPs in any kind of data -- be it genomic or EST -- in both de-novo and mapping assemblies ... provided it knows which read in an assembly is coming from which strain, cell line or organism.

The SNP detection routines are based on the same routines as the routines for detecting non-perfect repeats. In fact, MIRA can even distinguish between bases marking a misassembled repeat from bases marking a SNP within the same project.

All you need to do to enable this feature is to set -CO:mr=yes (which is standard in all `--job=...` incantations of `mira` and in some steps of `miraSearchESTSNPs`. Furthermore, you will need to provide strain information, either in the manifest file or in ancillary NCBI TRACEINFO XML files.

The effect of using strain names attached to reads can be described briefly like this. Assume that you have 6 reads (called R1 to R6), three of them having an `A` at a given position, the other three a `C`.

    R1   ......A......
    R2   ......A......
    R3   ......A......
    R4   ......C......
    R5   ......C......
    R6   ......C......

This example is just that: an example. It uses just 6 reads, with two times three reads as read groups for demonstration purposes and without looking at qualities. For MIRA to recognise SNPs, a few things must come together (e.g. for many sequencing technologies it wants forward and backward reads when in de-novo assembly) and a couple of parameters can be set to adjust the sensitivity. Read more about the parameters: -CO:mrpg:mnq:mgqrt:emea:amgb:amgbemc:amgbnbs

Now, assume you did not give any strain information. MIRA will most probably recognise a problem and, having no strain information, assume it made an error by assembling two different repeats of the same organism. It will tag the bases in the reads with repeat marker tags (SRMr) and the base in the consensus with a SROc tag (to point at an unresolved problem). In a subsequent pass, MIRA will then not assemble these six reads together again, but create two contigs like this:

    Contig1:
    R1   ......A......
    R2   ......A......
    R3   ......A......

    Contig2:
    R4   ......C......
    R5   ......C......
    R6   ......C......

The bases in the repeats will keep their SROr tags, but the consensus base of each contig will not get SROc as there is no conflict anymore.

Now, assume you gave reads R1, R2 and R3 the strain information "human", and read R4, R5 and R6 "chimpanzee". MIRA will then create this:

    R1 (hum)  ......A......
    R2 (hum)  ......A......
    R3 (hum)  ......A......
    R4 (chi)  ......C......
    R5 (chi)  ......C......
    R6 (chi)  ......C......

Instead of creating two contigs, it will create again one contig ... but it will tag the bases in the reads with a SROr tag and the position in the contig with a SROc tag. The SRO tags (SNP inteR Organisms) tell you: there's a SNP between those two (or multiple) strains/organisms/whatever.

Changing the above example a little, assume you have this assembly early on during the MIRA process:

    R1 (hum)  ......A......
    R2 (hum)  ......A......
    R3 (hum)  ......A......
    R4 (chi)  ......A......
    R5 (chi)  ......A......
    R6 (chi)  ......A......
    R7 (chi)  ......C......
    R8 (chi)  ......C......
    R9 (chi)  ......C......

Because "chimp" has a SNP within itself (`A` versus `C`) and there's a SNP between "human" and "chimp" (also `A` versus `C`), MIRA will see a problem and set a tag, this time a SIOr tag: SNP Intra- and inter Organism.

MIRA does not like conflicts occurring within an organism and will try to resolve these cleanly. After setting the SIOr tags, MIRA will re-assemble in subsequent passes this:

    Contig1:
    R1 (hum)  ......A......
    R2 (hum)  ......A......
    R3 (hum)  ......A......
    R4 (chi)  ......A......
    R5 (chi)  ......A......
    R6 (chi)  ......A......

    Contig2:
    R7 (chi)  ......C......
    R8 (chi)  ......C......
    R9 (chi)  ......C......

The reads in Contig1 (hum+chi) and Contig2 (chi) will keep their SIOr tags, the consensus will have no SIOc tag as the "problem" was resolved.

When presented to conflicting information regarding SNPs and possible repeat markers or SNPs within an organism, MIRA will always first try to resolve the repeats marker. Assume the following situation:

    R1 (hum)  ......A...T......
    R2 (hum)  ......A...G......
    R3 (hum)  ......A...T......
    R4 (chi)  ......C...G......
    R5 (chi)  ......C...T......
    R6 (chi)  ......C...G......

While the first discrepancy column can be "explained away" by a SNP between organisms (it will get a SROr/SROc tag), the second column cannot and will get a SIOr/SIOc tag. After that, MIRA opts to get the SIO conflict resolved:

    Contig1:
    R1 (hum)  ......A...T......
    R3 (hum)  ......A...T......
    R5 (chi)  ......C...T......

    Contig2:
    R2 (hum)  ......A...G......
    R4 (chi)  ......C...G......
    R6 (chi)  ......C...G......

## Data reduction: subsampling vs. lossless digital normalisation

Some data sets have way too much data. Sometimes it is simply more than needed like, e.g., performing a de-novo genome assembly with reads enough for 300x coverage is like taking a sledgehammer for cracking a nut. Sometimes it is even more than is good for an assembly (see also: motif dependent sequencing errors).

MIRA being an overlap-based assembler, reducing a data set helps to keep time and memory requirements low. There are basically two ways to perform this: reduction by subsampling and reduction by digital normalisation. Both methods have their pros and cons and can be used effectively in different scenarios.

- Subsampling is a process to create a smaller, hopefully representative set from a larger data set.

  In sequencing, various ways exist to perform subsampling. As sequencing data sets from current sequencing technologies can be seen as essentially randomised when coming fresh from the machine, the selection step can be as easy as selecting the first n reads. When the input data set is not random (e.g. in SAM/BAM files with mapped data), one must resort to random selection of reads.

  Subsampling must be done by the user prior to assembly with MIRA.

  On the upside, subsampling preserves the exact copy number structure of the input data set: a repeat with n copies in a genome will always be represented by reads forming n copies of the repeat in the reduced data set. Furthermore, subsampling is comparatively insensitive to motif dependend sequencing errors. On the downside, subsampling will more probably loose rare events of the data set (e.g., rare SNPs of a cell population or rare transcripts in EST/RNASeq). Also, in EST/RNASeq projects, subsampling will not be able to reduce extraordinary coverage events to a level which make the assembly not painfully slow. Examples for the later being rRNA genes or highly expressed house-keeping genes where todays' Illumina data sets sometimes contains enough data to reach coverage numbers ≥ 100,000x or even a million x.

  Subsampling should therefore be used for single genome de-novo assemblies; or for EST/RNASeq assemblies which need reliable coverage numbers for transcript expression data but where at least all rDNA has been filtered out prior to assembly.

- Digital normalisation is a process to perform a reduction of sequencing data redundancy. It was made known to a wider audience by the paper "A Reference-Free Algorithm for Computational Normalization of Shotgun Sequencing Data" by Brown et al. (see ).

  The normalisation process works by progressively going through the sequencing data and selecting reads which bring new, previously unseen information to the assembly and discarding those which describe nothing new. For single genome assemblies, this has the effect that repeats with n copies in the genome are afterwards present often with just enough reads to reconstruct only a single copy of the repeat. In EST/RNASeq assemblies, this leads to reconstructed transcripts having all the more or less same coverage.

  The normalisation process as described in the paper allows for a certain lossiness during the data reduction as it was developed to cope with billions of reads. E.g., it will often loose borders in genome reorganisation events or SNP information from ploidies, from closely related genes copies or from closely related species.

  MIRA implements a variant of the algorithm: the lossless digital normalisation. Here, normalised data has copy numbers reduced like in the original algorithm, but all variants (SNPs, borders of reorganisation events etc.) present in the original data set are retained in the reduced data set. Furthermore, the normalisation is parameterised to take place only for excessively repetitive parts of a data set which would lead to overly increased run-time and memory consumption. This gives the assembler the opportunity to correctly evaluate and work with repeats which do not occur "too often" in a data set while still being able to reconstruct at least one copy of the really nasty repeats.

  Digital normalisation should not be done prior to an assembly with MIRA, rather the MIRA paramater to perform a digital normalisation on the complete data set should be used.

  The lossless digital normalisation of MIRA should be used for EST/RNASeq assemblies containing highly repetitive data. Metagenome assemblies may also profit from this feature.

  MIRA keeps track of the approximate coverage represented by the reads chosen in the digital normalisation process. That is, MIRA is able to give approximate coverage numbers as if digital normalisation had never happened. The approximation may be around 10 to 20% below the true value. Contigs affected by this coverage approximation are denoted with an additional "_dn" in their name.

## Caveats

### Using data not from sequencing instruments: artifical / syntethic reads

The default parameters for MIRA assemblies work best when given real sequencing data and they even expect the data to behave like real sequencing data. But some assembly strategies work in multiple rounds, using so called "artificial" or "synthetic" reads in later rounds, i.e., data which was not generated through sequencing machines but might be something like the consensus of previous assemblies.

If one doesn't take utter care to make these artificial reads at least behave a little bit like real sequencing data, a number of quality ensurance algorithms of MIRA might spot that they "look funny" and trim back these artificial reads ... sometimes even removing them completely.

#### Summary tips for creating artificial reads for MIRA assemblies

The following should lead to the least amount of surprises for most assembly use cases when calling MIRA only with the most basic switches `--project=... --job=...`

1. Length: between 50 and 20000 bp
2. Quality values: give your artificial reads quality values. Using 30 as quality value for your bases should be OK for most applications.
3. Orientation: for every read you create, create a read with the same data (bases and quality values) in reverse complement direction.

The following list gives all the gory details on how synthetic reads should look like or which MIRA algorithms to switch off in certain cases:

- Forward and reverse complement directions: most sequencing technologies and strategies yield a mixture of reads with both forward and reverse complement direction to the DNA sequenced. In fact, having both directions allows for a much better quality control of an alignment as sequencing technology dependent sequencing errors will often affect only one direction at a given place and not both (the exception being homopolymers and 454).

  The MIRA proposed end clipping algorithm -CL:pec uses this knowledge to initially trim back ends of reads to an area without sequencing errors. However, if reads covering a given area of DNA are present in only one direction, then these reads will be completely eliminated.

  If you use only artificial reads in an assembly, then switch off the proposed end clipping -CL:pec=no.

  If you mix artificial reads with "normal" reads, make sure that every part of an artificial read is covered by some other read in reverse complement direction (be it a normal or artificial read). The easiest way to do that is to add a reverse complement for every artificial read yourself, though if you use an overlapping strategy with artificial reads, you can calculate the overlaps and reverse complements of reads so that every second artificial read is in reverse complement to save time and memory afterwards during the computation.

- Sequencing type/technology: MIRA currently knows Sangers, 454, Ion Torrent, Solexa and PacBio as sequencing technologies, every read entered in an assembly must be one of those.

  Artificial reads should be classified depending on the data they were created from, that is, Sanger for consensus of Sanger reads, 454 for consensus of 454 reads etc. However, Should reads created from Illumina consensus be much longer than, say, 200 or 300 bases, you should treat them as Sanger reads.

- Quality values: be careful to assign decent quality values to your artificial reads as several quality clipping or consensus calling algorithms make extensive use of qualities. Pay attention to values of -CL:qc:bsqc as well as to -CO:mrpg:mnq:mgqrt.

- Read lengths: current maximum read length for MIRA is around ~30kb. However, to account for some safety, MIRA currently allows only 20kb reads as maximum length.

### Ploidy and repeats

MIRA treats ploidy differences as repeats and will therefore build a separate contigs for the reads of a ploidy that has a difference to the other ploidy/ploidies.

There is simply no other way to handle ploidy while retaining the ability to separate repeats based on differences of only a single base. Everything else would be guesswork. I thought for some time about doing a coverage analysis around the potential repeat/ploidy site, but came to the conclusion that due to the stochastic nature of sequencing data, this would very probably take wrong decisions in too many cases to be acceptable.

If someone has a good idea, I'll be happy to hear it.

### Handling of repeats

#### Uniform read distribution

Under the assumption that reads in a project are uniformly distributed across the genome, MIRA will enforce an average coverage and temporarily reject reads from a contig when this average coverage multiplied by a safety factor is reached at a given site. This strategy reduces overcompression of repeats during the contig building phase and keeps reads in reserve for other copies of that repeat.

It's generally a very useful tool disentangle repeats, but has some slight secondary effects: rejection of otherwise perfectly good reads. The assumption of read distribution uniformity is the big problem we have here: of course it's not really valid. You sometimes have less, and sometimes more than "the average" coverage. Furthermore, the new sequencing technologies - 454 perhaps but certainly the ones from Solexa - show that you also have a skew towards the site of replication origin.

Warning: Solexa data from late 2009 and 2010 show a high GC content bias. This bias can reach 200 or 300%, i.e., sequence part for with low GC

One example: let's assume the average coverage of a project is 8 and by chance at one place there 17 (non-repetitive) reads, then the following happens:

(Note: p is the parameter -AS:urdsip)

Pass 1 to p-1: MIRA happily assembles everything together and calculates a number of different things, amongst them an average coverage of ~8. At the end of pass p-1, it will announce this average coverage as first estimate to the assembly process.

Pass p: MIRA has still assembled everything together, but at the end of each pass the contig self-checking algorithms now include an "average coverage check". They'll invariably find the 17 reads stacked and decide (looking at the -AS:ardct parameter which is assumed to be 2 for this example) that 17 is larger than 2*8 and that this very well may be a repeat. The reads get flagged as possible repeats.

Pass p+1 to end: the "possibly repetitive" reads get a much tougher treatment in MIRA. Amongst other things, when building the contig, the contig now looks that "possibly repetitive" reads do not overstack by an average coverage multiplied by a safety value (-AS:urdcm) which we'll assume now to be 1.5 in this example. So, at a certain point, say when read 14 or 15 of that possible repeat want to be aligned to the contig at this given place, the contig will just flatly refuse and tell the assembler to please find another place for them, be it in this contig that is built or any other that will follow. Of course, if the assembler cannot comply, the reads 14 to 17 will end up as contiglet (contig debris, if you want) or if it was only one read that got rejected like this, it will end up as singlet or in the debris file.

Tough luck. I do have ideas on how to reintegrate those reads at the and of an assembly, but I have deferred doing this as in every case I had looked up, adding those reads to the contigs wouldn't have changed anything ... there's already enough coverage.

What should be done in those cases is simply filter away the contiglets (defined as being of small size and having an average coverage below the average coverage of the project divided 3 (or 2.5)) from a project.

#### Keeping 'long' repetitive contigs separate

MIRA had since 2.9.36 a feature to keep long repeats in separate contigs (-AS:klrs). Due to algorithm changes, this feature is now standard (even if the command line parameter is still present). The effect of this is that contigs with non-repetitive sequence will stop at a 'long repeat' border, including only the first few bases of the repeat. Long repeats will be kept as separate contigs.

This has been implemented to get a clean overview on which parts of an assembly are 'safe' and which parts will be 'difficult'. For this, the naming of the contigs has been extended: contigs named with a '_c' at the end are contigs which contain mostly 'normal' coverage. Contigs with "rep_c" are contigs which contain mostly sequence classified as repetitive and which could not be assembled together with a 'c' contig.

The question remains: what are 'long' repeats. MIRA defines these as repeats that are not spanned by any read that has non-repetitive parts at the end. So, basically, the mean length of the reads that go into the assembly defines the length of 'long' repeats that have to be kept in separate contigs.

It has to be noted that when using paired-end (or template) sequencing, 'long' repeats which can be spanned by read-pairs (or templates) are mostly integrated into 'normal' contigs as MIRA can correctly place them most of the time.

#### Helping finishing by tagging reads with HAF tags

HAF tags (HAsh Frequency) are set by MIRA when the option to colour reads by hash frequency (-GE:crhf, on by default in most --job combinations) is on. These tags show the status of k-mers (stretch of bases of given length k) in read sequences: whether MIRA recognised them as being present in sub-average, average, above average or repetitive numbers.

When using a finishing programs which can display tags in reads (and using the proposed tag colour schemes for gap4 or consed, the assembly will light up in colours ranging from light green to dark red, indicating whether a certain part of the assembly is deemed non-repetitive to extremely repetitive.

One of the biggest advantages of the HAF tags is the implicit information they convey on why the assembler stopped building a contig at an end.

- if the read parts composing a contig end are mostly covered with HAF2 tags (below average frequency, coloured light-green), then one very probably has a hole in the contig due to coverage problems which means there are no or not enough reads covering a part of the sequence.

- if the read parts composing a contig end are mostly covered with HAF3 tags (average frequency, coloured green), then you have an unusual situation as this should only very rarely occur. The reason is that MIRA saw that there are enough sequences which look the same as the one from your contig end, but that these could not be joined. Likely reasons for this scenario include non-random sequencing artifacts (seen in 454 data) or also non-random chimeric reads (seen in Sanger and 454 data).

- if the read parts composing a contig end are mostly covered with HAF4 tags (above average frequency, coloured yellow), then the assembler stopped at grey zone of the coverage not being normal anymore, but not quite repetitive yet. This can happen in cases where the read coverage is very unevenly distributed across the project. The contig end in question might be a repeat occurring two times in the sequence, but having less reads than expected. Or it may be non-repetitive coverage with an unusual excess of reads.

- if the read parts composing a contig end are mostly covered with HAF5 (repeat, coloured red), HAF6 (heavy repeat, coloured darker red) and HAF7 tags (crazy repeat, coloured very dark red), then there is a repetitive area in the sequence which could not be uniquely bridged by the reads present in the assembly.

This information can be especially helpful when joining reads by hand in a finishing program. The following list gives you a short guide to cases which are most likely to occur and what you should do.

- the proposed join involves contig ends mostly covered by HAF2 tags. Joining these contigs is probably a safe bet. The assembly may have missed this join because of too many errors in the read ends or because sequence having been clipped away which could be useful to join contigs. Just check whether the join seems sensible, then join.

- the proposed join involves contig ends mostly covered by HAF3 tags. Joining these contigs is probably a safe bet. The assembly may have missed this join because of several similar chimeric reads reads or reads with similar, severe sequencing errors covering the same spot. Just check whether the join seems sensible, then join.

- the proposed join involves contig ends mostly covered by HAF4 tags. Joining these contigs should be done with some caution, it may be a repeat occurring twice in the sequence. Check whether the contig ends in question align with ends of other contigs. If not, joining is probably the way to go. If potential joins exist with other contigs, then it's a repeat (see below).

- the proposed join involves contig ends mostly covered by HAF5, HAF6 or HAF7 tags. Joining these contigs should be done with utmost caution, you are almost certainly (HAF5) and very certainly (HAF6 and HAF7) in a repetitive area of your sequence. You will probably need additional information like paired-end or template info in order join your contigs.

### Consensus in finishing programs (gap4, consed, ...)

MIRA goes a long way to calculate a consensus which is as correct as possible. Unfortunately, communication with finishing programs is a bit problematic as there currently is no standard way to say which reads are from which sequencing technology.

It is therefore often the case that finishing programs calculate an own consensus when loading a project assembled with MIRA. This is the case for at least, e.g., gap4. This consensus may then not be optimal.

The recommended way to deal with this problem is: import the results from MIRA into your finishing program like you always do. Then finish the genome there, export the project from the finishing program as CAF and finally use convert_project (from the MIRA package ) with the "-r" option to recalculate the optimal consensus of your finished project.

E.g., assuming you have just finished editing the gap4 database `DEMO.3`, do the following. First, export the gap4 database back to CAF:

    $ gap2caf -project DEMO -version 3 >demo3.caf

Then, use convert_project with option '-r' to convert it into any other format that you need. Example for converting to a CAF and a FASTA format with correct consensus:

    $ convert_project -f caf -t caf -t fasta -r c demo3.caf final_result

### Some other things to consider

- MIRA cannot work with EXP files resulting from GAP4 that already have been edited. If you want to reassemble an edited GAP4 project, convert it to CAF format and use the -caf option to load.

- As also explained earlier, MIRA relies on sequencing vector being recognised in preprocessing steps by other programs. Sometimes, when a whole stretch of bases is not correctly marked as sequencing vector, the reads might not be aligned into a contig although they might otherwise match quite perfectly. You can use -CL:pvc and -CO:emea to address problem with incomplete clipping of sequencing vectors. Also having the assembler work with less strict parameters may help out of this.

- MIRA has been developed to assemble shotgun sequencing or EST sequencing data. There are no explicit limitations concerning length or number of sequences. However, there are a few implicit assumptions that were made while writing portions of the code:

  1. Sequence data produced by electrophoresis rarely surpasses 1000 usable bases and I never heard of, let alone seen, more than 1100. The fast filtering SKIM relies on the fact that sequences will never exceed 10000 bases in length.

  2. The next problem that might arise with 'unnatural' long sequence reads will be my implementation of the Smith-Waterman alignment routines. I use a banded version with linear running time (linear to the bandwidth) but quadratic space usage. So, comparing two 'reads' of length 5000 will result in memory usage of 100MB. I know that this could be considered as a flaw. On the other hand - unless someone comes up with electrophoresis producing reads with more than 2000 usable bases - I see no real need to change this as long as there are more important things on the TODO list. Of course, if anyone is willing to contribute a fast banded SW alignment routine which runs in linear time and space, just feel free to contact the author.

  3. 32 bit versions of MIRA are not supported anymore.

  4. to reduce memory overhead, the following assumptions have been made:

  5. MIRA is not fully multi-threaded (yet), though most bottlenecks are now in code areas which cannot be multi-threaded by algorithm design.

- a project does not contain sequences from more than 255 different:

  - sequencing machine types

  - primers

  - strains (in mapping mode: 7)

  - base callers

  - dyes

  - process status

- a project does not contain sequences from more than 65535 different

  - clone vectors

  - sequencing vectors

## Things you should not do

### Do not run MIRA on NFS mounted directories without redirecting the tmp directory

Of course one can run MIRA atop a NFS mount (a "disk" mounted over a network using the NFS protocol), but the performance will go down the drain as the NFS server respectively the network will not be able to cope with the amount of data MIRA needs to shift to and from disk (writes/reads to the tmp directory). Slowdowns of a factor of 10 and more have been observed. In case you have no other possibility, you can force MIRA to run atop a NFS using -MI:sonfs=no, but you have been warned.

In case you want to keep input and output files on NFS, you can use -DI:trt to redirect the tmp directory to a local filesystem. Then MIRA will run at almost full speed.

### Do not assemble without quality values

Assembling sequences without quality values is like ... like ... like driving a car downhill a sinuous mountain road with no rails at 200 km/h without brakes, airbags and no steering wheel. With a ravine on one side and a rock face on the other. Did I mention the missing seat-belts? You might get down safely, but experience tells the result will rather be a bloody mess.

All MIRA routines internally are geared toward quality values guiding decisions. No one should ever assembly anything without quality values. Never. Ever. Even if quality values are sometimes inaccurate, they do help.

Now, there are very rare occasions where getting quality values is not possible. If you absolutely cannot get them, and I mean only in this case, use the following switch:`--noqualities[=SEQUENCINGTECHNOLOGY]` and additionally give a default quality for reads of a readgroup. E.g.:

    parameters= --noqualities=454

    readgroup
    technology=454
    data=...
    default_qual=30

This tells MIRA not to complain about missing quality values and to fake a quality value of 30 for all reads (of a readgroup) having no qualities, allowing some MIRA routines (in standard parameter settings) to start disentangling your repeats.

Doing the above has some severe side-effects. You will be, e.g., at the mercy of non-random sequencing errors. I suggest combining the above with a -CO:mrpg=4 or higher. You also may want to tune the default quality parameter together with -CO:mnq and -CO:mgqrt in cases where you mix sequences with and without quality values.

## Useful third party programs

Viewing the results of a MIRA assembly or preprocessing the sequences for an assembly can be done with a number of different programs. The following ones are are just examples, there are a lot more packages available:

HTML browser

  If you have really nothing else as viewer, a browser who understands tables is needed to view the HTML output. A browser knowing style sheets (CSS) is recommended, as different tags will be highlighted. Konqueror, Opera, Mozilla, Netscape and Internet Explorer all do fine, lynx is not really ... optimal.

Assembly viewer / finishing / preprocessing

  You'll want GAP4 or its successor GAP5 (generally speaking: the Staden package) to preprocess the sequences, visualise and eventually rework the results when using gap4da output. The Staden package comes with a fully featured sequence preparing and annotating engine (pregap4) that is very useful to preprocess your Sanger data (conversion between file types, quality clipping, tagging etc.).

  See for further information and also a possibility to download precompiled binaries for different platforms.

Vector screening

  Reading result files from `ssaha2` or `smalt` from the Sanger centre is supported directly by MIRA to perform a fast and efficient tagging of sequencing vector stretches. This makes you basically independent from any other commercial or license-requiring vector screening software. For Sanger reads, a combination of `lucy` (see below), `ssaha2` or `smalt` together with the MIRA parameters for SSAHA2 / SMALT support (see all -CL:msvs* parameters) and quality clipping (-CL:qc) should do the trick. For reads coming from 454 pyro-sequencing, `ssaha2` or `smalt` and the SSAHA2 / SMALT support also work pretty well.

  See and / or for further information and also a possibility to download the source or precompiled binaries for different platforms.

Preprocessing

  `lucy` from TIGR (now JCVI) is another useful sequence preprocessing program for Sanger data. Lucy is a utility that prepares raw DNA sequence fragments for sequence assembly. The cleanup process includes quality assessment, confidence reassurance, vector trimming and vector removal.

  There's a small script in the MIRA 3rd party package which converts the clipping data from the lucy format into something MIRA can understand (NCBI Traceinfo).

  See to download the source code of lucy.

Assembly viewer

  Viewing `.ace` file output without consed can be done with clview from TIGR. See .

  A better alternative is Tablet which also reads SAM format.

Assembly coverage analysis

  The Integrated Genome Browser (IGB) of the GenoViz project at SourceForge () is just perfect for loading a genome and looking at mapping coverage (provided by the wiggle result files of MIRA).

Preprocessing (base calling)

  TraceTuner () is a tool for base and quality calling of trace files from DNA sequencing instruments. Originally developed by Paracel, this code base was released as open source in 2006 by Celera.

Preprocessing / viewing

  phred (basecaller) - cross_match (sequence comparison and filtering) - phrap (assembler) - consed (assembly viewer and editor). This is another package that can be used for this type of job, but requires more programming work. The fact that sequence stretches are masked out (overwritten with the character X) if they shouldn't be used in an assembly doesn't really help and is considered harmful (but it works).

  Note the bug of consed when reading ACE files, see more about this in the section on file types (above) in the entry for ACE.

  See for further information.

text viewer

  A text viewer for the different textual output files.

As always, most of the time a combination of several different packages is possible. My currently preferred combo for genome projects is `ssaha2` or `smalt` and or `lucy` (vector screening), MIRA (assembly, of course) and gap4 (assembly viewing and finishing).

For re-assembling projects that were edited in gap4, one will also need the gap2caf converter. The source for this is available at .

## Speed and memory considerations

### Estimating needed memory for an assembly project

Since the V2.9.24x3 version of MIRA, there is `miramem` as program call. When called from the command line, it will ask a number of questions and then print out an estimate of the amount of RAM needed to assemble the project. Take this estimate with a grain of salt, depending on the sequences properties, variations in the estimate can be +/- 30% for bacteria and 'simple' eukaryotes. The higher the number of repeats is, the more likely you will need to restrict memory usage in some way or another.

Here's the transcript of a session with miramem:

    This is MIRA V3.2.0rc1 (development version).

    Please cite: Chevreux, B., Wetter, T. and Suhai, S. (1999), Genome Sequence
    Assembly Using Trace Signals and Additional Sequence Information.
    Computer Science and Biology: Proceedings of the German Conference on
    Bioinformatics (GCB) 99, pp. 45-56.

    To (un-)subscribe the MIRA mailing lists, see:
            http://www.chevreux.org/mira_mailinglists.html

    After subscribing, mail general questions to the MIRA talk mailing list:
            mira_talk@freelists.org

    To report bugs or ask for features, please use the new ticketing system at:
            http://sourceforge.net/apps/trac/mira-assembler/
    This ensures that requests don't get lost.

    [...]

    miraMEM helps you to estimate the memory needed to assemble a project.
    Please answer the questions below.

    Defaults are give in square brackets and chosen if you just press return.
    Hint: you can add k/m/g modifiers to your numbers to say kilo, mega or giga.

    Is it a genome or transcript (EST/tag/etc.) project? (g/e/) [g]
    g
    Size of genome? [4.5m] 9.8m
    9800000
    Size of largest chromosome? [9800000]
    9800000
    Is it a denovo or mapping assembly? (d/m/) [d]
    d
    Number of Sanger reads? [0]
    0
    Are there 454 reads? (y/n/) [n] y
    y
    Number of 454 GS20 reads? [0]
    0
    Number of 454 FLX reads? [0]
    0
    Number of 454 Titanium reads? [0] 750k
    750000
    Are there PacBio reads? (y/n/) [n]
    n
    Are there Solexa reads? (y/n/) [n]
    n

    ************************* Estimates *************************

    The contigs will have an average coverage of ~ 30.6 (+/- 10%)

    RAM estimates:
               reads+contigs (unavoidable): 7.0 GiB
                    large tables (tunable): 688. MiB
                                            ---------
                              total (peak): 7.7 GiB

                add if using -CL:pvlc=yes : 2.6 GiB

    Estimates may be way off for pathological cases.

    Note that some algorithms might try to grab more memory if
    the need arises and the system has enough RAM. The options
    for automatic memory management control this:
      -AS:amm, -AS:kpmf, -AS:mps
    Further switches that might reduce RAM (at cost of run time
    or accuracy):
      -SK:mhim, -SK:mchr (both runtime); -SK:mhpr (accuracy)
    *************************************************************

If your RAM is not large enough, you can still assemble projects by using disk swap. Up to 20% of the needed memory can be provided by swap without the speed penalty getting too large. Going above 20% is not recommended though, above 30% the machine will be almost permanently swapping at some point or another.

### Some numbers on speed

NEW since 2.7.4: The new SKIM3 algorithm (initial all-against-all read comparison) is now approximately 60 times faster that the SKIM algorithms of earlier versions. E.g. SKIMming of 53,000 Sanger type shotguns reads now takes a bit more than a minute instead of 62 minutes.

The times given below are only approximate and were gathered on my home development box (Athlon 4800+) using a single core and minimal debug code compiled in, somewhat slowing down the whole process.

Example 1: a small genomic project with 720 reads forming 35k bases of contig sequences. Using `--job=denovo,genome,accurate,sanger` and resolving minor repeat misassemblies, full read extension and automatic contig editing takes 19 seconds.

Example 2: a bacterial genome project with two very closely related strains, 53000 Sanger reads forming a bit more than 3 megabases of contig sequences for each strain. Using the `--job=denovo,genome,accurate,sanger` (four main passes, read extension, clipping of vector remnants), resolving repeat misassemblies (mostly RNA stretches, but also some very closely related genes) takes 1hr and 48 minutes and uses a maximum of 1.2GB of RAM (miramem estimated the usage to be 1.5GB).

Example 3: Here are the times for miraSearchESTSNPs in a non-normalised (thus very repetitive) EST project, 9747 reads with a average length of 674 used bases,

- The fast filtering algorithm performs about 12 million sequence comparisons per second (8 seconds).

- Banded Smith-Waterman performs around 750 sequence alignments per second (with a 15% band to each side, which is quite generous), 4:07 for about 182000 alignment checks.

The three steps of miraSearchESTSNPs (each one again subdivided in a number of MIRA passes), including resolving very high coverage contigs (>500 sequences) in multiple passes and splitting them into different SNP and splice variants takes about 20 minutes.

## Known Problems / Bugs

File Input / Output:

1. MIRA can only read unedited EXP files.

2. There sometimes is a (rather important) memory leak occurring while using the assembly integrated Sanger read editor. I have not been able to trace the reason yet.

3. There's an unexpected bug for MacOS which leads to rubbish assemblies on large data sets which assemble totally fine with Linux versions of MIRA. I have not been able to find out the reason for this yet.

Assembly process:

1. The routines for determining Repeat Marker Bases (SRMr) are sometimes too sensitive, which sometimes leads to excessive base tagging and preventing right assemblies in subsequent assembly processes. The parameters you should look at for this problem are -CO:mrc:nrz:mgqrt:mgqwpc. Also look at -CL:pvc and -CO:emea if you have a lot of sequencing vector relics at the end of the sequences.

2. The assignment of reads to debris or singlets and whether or not they are put into the final result is messy, the statistic numbers about this sometimes even wrong. Needs to be redone.

## TODOs

These are some of the topics on my TODO list for the next revisions to come:

1. Making parts of the process multi-threaded (currently stopped due to other priorities like Solexa etc.)

2. Less disk usage when using EST assembly on 10 or more million Solexa reads

3. Others nifty ideas that I have not completely thought out yet.

## Working principles

Note: description is old and needs to be adapted to the current 2.9.x / 3.x line.

To avoid the "garbage-in, garbage-out" problematic, MIRA uses a 'high quality alignments first' contig building strategy. This means that the assembler will start with those regions of sequences that have been marked as good quality (high confidence region - HCR) with low error probabilities (the clipping must have been done by the base caller or other preprocessing programs, e.g. pregap4) and then gradually extends the alignments as errors in different reads are resolved through error hypothesis verification and signal analysis.

This assembly approach relies on some of the automatic editing functionality provided by the EdIt package which has been integrated in parts within MIRA.

This is an approximate overview on the steps that are executed while assembling:

1. All the experiment / phd / fasta sequences that act as input are loaded (or the CAF project). Qualities for the bases are loaded from the FASTA or SCF if needed.

2. the ends of the reads are cleaned ensure they have a minimum stretch of bases without sequencing errors

3. The high confidence region (HCR) of each read is compared with a quick algorithm to the HCR of every other read to see if it could match and have overlapping parts (this is the 'SKIM' filter).

4. All the reads which could match are being checked with an adapted Smith-Waterman alignment algorithm (banded version). Obvious mismatches are rejected, the accepted alignments form one or several alignment graphs.

5. Optional pre-assembly read extension step: MIRA tries to extend HCR of reads by analysing the read pairs from the previous alignment. This is a bit shaky as reads in this step have not been edited yet, but it can help. Go back to step 2.

6. A contig gets made by building a preliminary partial path through the alignment graph (through in-depth analysis up to a given level) and then adding the most probable overlap candidates to a given contig. Contigs may reject reads if these introduce to many errors in the existing consensus. Errors in regions known as dangerous (for the time being only ALUS and REPT) get additional attention by performing simple signal analysis when alignment discrepancies occur.

7. Optional: the contig can be analysed and corrected by the automatic editor ("EdIt" for Sanger reads, or the new MIRA editor for 454 reads).

8. Long repeats are searched for, bases in reads of different repeats that have been assembled together but differ sufficiently (for EdIT so that they didn't get edited and by phred quality value) get tagged with special tags (SRMr and WRMr).

9. Go back to step 5 if there are reads present that have not been assembled into contigs.

10. Optional: Detection of spoiler reads that prevent joining of contigs. Remedy by shortening them.

11. Optional: Write out a checkpoint assembly file and go back to step 2.

12. The resulting project is written out to different output files and directories.

## See Also

The other MIRA manuals and walkthroughs as well as `EdIt`, `gap4`, `pregap4`, `gap5`, `clview`, `caf2gap`, `gap2caf`, `ssaha2`, `smalt`, `compress` and `gzip`, `cap3`, `ttuner`, `phred`, `phrap`, `cross_match`, `consed`.