<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.docbook.org/xml/4.5/docbookx.dtd">
<chapter id="chap_reference">
  <chapterinfo>
    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="versionfile"/>
    <author>
      <firstname>Bastien</firstname>
      <surname>Chevreux</surname>
      <email>bach@chevreux.org</email>
    </author>
    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="copyrightfile"/>
  </chapterinfo>
  <blockquote>
    <attribution>Solomon Short</attribution>
    <para>
      <emphasis><quote>The manual only makes sense after you learn the program.
      </quote></emphasis>
    </para>
  </blockquote>
  <title>MIRA 4 reference manual</title> <subtitle>aka: The extended man page of MIRA 4,
  a genome and EST/RNASeq sequence assembly and mapping program for Sanger, 454, IonTorrent,
  PacBio and Illumina/Solexa sequencing data</subtitle>
  <sect1 id="sect_ref_synopsis">
    <title>
      Synopsis
    </title>
    <para>
      <literal>mira <arg>-chmMrtv</arg> <replaceable>manifest-file</replaceable> <arg><replaceable>manifest-file</replaceable> ...</arg></literal>
    </para>
    <para>
      The command line parameters in short:
    </para>
    <variablelist>
      <varlistentry>
	<term>
	  <arg>-c / --cwd=<replaceable>directory</replaceable></arg>
	</term>
	<listitem>
	  Change working directory.
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <arg>-h / --help</arg>
	</term>
	<listitem>
	  Print a short help and exit.
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <arg>-m / --mcheck</arg>
	</term>
	<listitem>
	  Only check the manifest file, then exit.
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <arg>-M / --mdcheck</arg>
	</term>
	<listitem>
	  Only check the manifest file and presence of data files, then exit.
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <arg>-r / --resume</arg>
	</term>
	<listitem>
	  Resume / restart an interrupted assembly. Works only for de-novo
	  assemblies at the moment.
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <arg>-t / --thread=<replaceable>integer &ge; 0</replaceable></arg>
	</term>
	<listitem>
	  Force number of threads (overrides equivalent <arg>-GE:not</arg>
          manifest entry).
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <arg>-v / --version</arg>
	</term>
	<listitem>
	  Print version and exit.
	</listitem>
      </varlistentry>
    </variablelist>
  </sect1>
  <sect1 id="sect_ref_requirements">
    <title>
      Requirements
    </title>
    <para>
      To use MIRA itself, one doesn't need very much:
    </para>
    <itemizedlist>
      <listitem>
	<para>
	  Sequence data in EXP, CAF, PHD, FASTA or FASTQ format
	</para>
      </listitem>
      <listitem>
	<para>
	  Optionally: ancillary information in NCBI traceinfo XML format;
	  ancillary information about strains in tab delimited format, vector
	  screen information generated with <command>ssaha2</command> or
	  <command>smalt</command>.
	</para>
      </listitem>
      <listitem>
	<para>
	  Some memory and disk space. Actually lots of both if you are
	  venturing into 454 or Illumina.
	</para>
      </listitem>
    </itemizedlist>
    <para>
    </para>
  </sect1>
  <sect1 id="sect_ref_working_modes">
    <title>
      Working modes
    </title>
    <para>
      MIRA has three basic working modes: genome, EST/RNASeq 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:
    </para>
    <orderedlist>
      <listitem>
	<para>
	  <command>mira</command> for assembly of genomic data as well as
	  assembly of EST data from one or multiple strains / organisms
	</para>
	<para>
	  and
	</para>
      </listitem>
      <listitem>
	<para>
	  <command>miraSearchESTSNPs</command> for assembly of EST data from
	  different strains (or organisms) and SNP detection within this
	  assembly. This is the former <command>miraEST</command> program
	  which was renamed as many people got confused regarding whether to
	  use MIRA in est mode or miraEST.
	</para>
      </listitem>
    </orderedlist>
    <para>
      Note that <command>miraSearchESTSNPs</command> is usually realised as
      a link to the <command>mira</command> executable, the executable
      decides by the name it was called with which module to start.
    </para>
  </sect1>
  <sect1 id="sect_ref_config">
    <title>
      Configuring an assembly: files and parameters
    </title>
    <para>
      All the configuration needed for an assembly is done in one (or several)
      configuration file(s): the <emphasis>manifest</emphasis> 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).
    </para>
    <sect2 id="sect_ref_manifest_introduction">
      <title>
	The manifest file: introduction
      </title>
      <para>
	A <emphasis>manifest</emphasis> 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
	single-end (also called shotgun) 454 data:
      </para>
<screen># 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)

<userinput>
project = <replaceable>MyFirstAssembly</replaceable>
job = <replaceable>genome,denovo,accurate</replaceable>
parameters = <replaceable>-GE:not=4</replaceable></userinput>

# 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 ...

<userinput>readgroup = <replaceable>SomeUnpaired454ReadsIGotFromTheLab</replaceable>
data = <replaceable>TCMFS456ZH345.fastq TQF92GT7H34.fastq</replaceable>
technology = <replaceable>454</replaceable></userinput></screen>
      <para>
	To make things a bit more interesting, here's an example using a
	couple more technologies and showing some more options of the manifest
	file like wild cards in file names, different paired-end/mate-pair
	libraries and how to let MIRA refine pairing information (or even find
	out everything by itself):
      </para>
<screen># Example for a manifest describing a de-novo assembly with
# unpaired 454, paired-end Illumina, a mate-pair Illumina
# and a paired Ion Torrent

# 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 passes with kmer sizes of
# 17, 31, 63 and 127 nucleotides. Obviously, read lengths of the
# libraries should be greater than 127 bp.
# Note: usually MIRA will choose sensible options for number of
#  passes and kmer sizes to be used by itself.

<userinput>project = <replaceable>MyFirstAssembly</replaceable>
job = <replaceable>genome,denovo,accurate</replaceable>
parameters = <replaceable>-AS:kms=17,31,63,127</replaceable></userinput>

# 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 ...

# defining the shotgun (i.e. unpaired) 454 reads
<userinput>readgroup = <replaceable>SomeUnpaired454ReadsIGotFromTheLab</replaceable>
data = <replaceable>TCMFS456ZH345.fastq TQF92GT7H34.fastq</replaceable>
technology = <replaceable>454</replaceable></userinput>

# defining the paired-end Illumina reads, fixing all needed pair information
<userinput>readgroup = <replaceable>SomePairedEndIlluminaReadsIGotFromTheLab</replaceable>
data = <replaceable>datape*.fastq</replaceable>
technology = <replaceable>solexa</replaceable>
template_size = <replaceable>100 300</replaceable>
segment_placement = <replaceable>---&gt; &lt;---</replaceable>
segment_naming = <replaceable>solexa</replaceable></userinput>

# defining the mate-pair Illumina reads, fixing most needed pair information
#  but letting MIRA refine the template_size via "autorefine"
<userinput>readgroup = <replaceable>SomeMatePairIlluminaReadsIGotFromTheLab</replaceable>
data = <replaceable>datamp*.fastq</replaceable>
technology = <replaceable>solexa</replaceable>
template_size = <replaceable>2000 4000 autorefine</replaceable>
segment_placement = <replaceable>&lt;--- ---&gt;</replaceable>
segment_naming = <replaceable>solexa</replaceable></userinput>

# defining paired Ion Torrent reads
# example to show how lazy one can be and simply let MIRA estimate by itself
#  all needed pairing information via "autopairing"
#  Hint: it usually does a better job at it than we do ;-)
<userinput>readgroup = <replaceable>SomePairedIonReadsIGotFromTheLab</replaceable>
<replaceable>autopairing</replaceable>
data = <replaceable>dataion*.fastq</replaceable>
technology = <replaceable>iontor</replaceable></userinput></screen>
    </sect2>
    <sect2 id="sect_ref_manifest_basics">
      <title>
	The manifest file: basics
      </title>
      <para>
	The first part of an assembly <emphasis>manifest</emphasis> 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:
      </para>
      <orderedlist>
	<listitem>
	  <para>
	    <emphasis role="bold">project =</emphasis><arg>=
	    <replaceable>project name</replaceable></arg> 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.
	  </para>
	  <para>
	    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.
	  </para>
	</listitem>
	<listitem>
	  <para>
	    <emphasis role="bold">job =</emphasis>
	    <arg><replaceable>denovo|mapping</replaceable></arg>,
	    <arg><replaceable>genome|est|fragments|clustering</replaceable></arg>,
	    <arg><replaceable>draft|accurate</replaceable></arg> tells the
	    assembler what kind of data it should expect and how it should
	    assemble it.
	  </para>
	  <para>
	  You need to make your choice mainly in three steps and in the end
	  concatenate your choices to the <arg>job=</arg> entry of the manifest:
	  </para>
	  <orderedlist>
	    <listitem>
	      <para>
		are you building an assembly from scratch
		(choose: <emphasis>denovo</emphasis>) or are you mapping reads
		to an existing backbone sequence
		(choose: <emphasis>mapping</emphasis>)?  Pick one. Leaving this
		out automatically chooses <emphasis>denovo</emphasis> as
		default.
	      </para>
	    </listitem>
	    <listitem>
	      <para>
		are the data you are assembling forming a larger contiguous
		sequence (choose: <emphasis>genome</emphasis>), are you
		assembling EST or mRNA libraries
		(choose: <emphasis>est</emphasis>), single genes or small
		plasmids (choose: <emphasis>fragments</emphasis>) or do you cluster assembled
		sequences (choose: <emphasis>clustering</emphasis>)?
		Pick one. Leaving this out
		automatically chooses <emphasis>genome</emphasis> as default.
	      </para>
	      <para>
		Since version 4.9.4, a new mode <emphasis>fragments</emphasis>
		is available. This mode is essentially similar to the
		<emphasis>EST</emphasis> mode, but has all safety features
		switched off which reduce data sizes. Use this mode for
		assembly of comparatively small EST/mRNA or small plasmid or
		single gene projects where you
		want to have highest accuracy and minimal filtering. Warning:
		contigs with coverages going into the 1000s will lead to
		really slow assemblies.
	      </para>
	      <para>
		Since version 4.9.6, a new mode <emphasis>clustering</emphasis>
		is available. This mode is essentially for clustering
		assembled contigs like they are created in mRNA or EST
		assemblies. Basic parameters are: single pass, no clipping, no
		editing, ~7.5% differences between sequences allowed,
		gaps >= 13 bases disallowed, single occurrence of disagreeing
		base leads to SNP tagging.
		Warning: do not use that with any type of real sequencing data
		... you probably would regret this.
	      </para>
	    </listitem>
	    <listitem>
	      <para>
		do you want a quick and dirty assembly for first insights
		(choose: <emphasis>draft</emphasis>) or an assembly that should
		be able to tackle even most nasty cases (choose:
		<emphasis>accurate</emphasis>)? Pick one. Leaving this out
		automatically chooses <emphasis>accurate</emphasis> as default.
	      </para>
	    </listitem>
	  </orderedlist>
	  <para>
	    Once you're done with your choices, concatenate everything with
	    commas and you're done. E.g.:
	    '<literal>--job=mapping,genome,draft</literal>' will give you a
	    mapping assembly of a genome in draft quality.
	  </para>
	  <note>
	    For de-novo assembly of genomes, these switches are optimised for
	    'decent' coverages that are commonly seen to get you something useful,
	    i.e., &ge; 7x for Sanger, >=18x for 454 FLX or Titanium, &ge; 25x for
	    454 GS20 and &ge; 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.
	  </note>
	</listitem>
	<listitem>
	  <para>
	    <emphasis role="bold">parameters =</emphasis> 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.
	  </para>
	</listitem>
      </orderedlist>
    </sect2>
    <sect2 id="sect_ref_manifest_readgroups">
      <title>
	The manifest file: information on the data you have
      </title>
      <para>
	The second part of an assembly <emphasis>manifest</emphasis> 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.
      </para>
      <sect3 id="sect_ref_manifest_readgroups_readgroup">
      <title>
	Starting a new readgroup
      </title>
	<para>
	  <emphasis role="bold">readgroup </emphasis><arg>= <replaceable>group name</replaceable></arg> is the keyword which tells MIRA that you are going to define a new read group. You can optionally name that group.
	</para>
	<sidebar id="sidebar_ref_manifest_readgroups_templates_and_readgroups">
	  <title>
	    Understanding readgroups and DNA templates
	  </title>
	  <para>
	    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.
	  </para>
	  <para>
	    With most library preps, your DNA is first amplified and then
	    cut into small pieces. These pieces are called
	    <emphasis>templates</emphasis> 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).
	  </para>
	  <para>
	    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.
	  </para>
	  <para>
	    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.
	  </para>
	  <para>
	    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.
	  </para>
	  <para>
	    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 <emphasis>read
	    groups</emphasis> 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.
	  </para>
	  <note>
	    The above was a <emphasis role="bold">very</emphasis> 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.
	  </note>
	</sidebar>
      </sect3>
      <sect3 id="sect_ref_manifest_readgroups_data">
      <title>
	Defining data files to load
      </title>
	<para>
	  <emphasis role="bold">data</emphasis> = <replaceable>filepath
	  <arg>filepath ...</arg></replaceable> 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
	  <emphasis>path</emphasis>, i.e., the directory (absolute or
	  relative) including the file name.
	</para>
	<para>
	  MIRA automatically recognises what type the sequence data is by
	  looking at the postfix of files. For postfixes not adhering widely
	  used naming schemes for file types, there's additionally a way of
	  explicitly defining the type (see further down at the end of this
	  item on how this is done). Currently allowed file types are:
	</para>
	<itemizedlist>
	  <listitem>
	    <para>
	      <filename>.fasta</filename> for sequences formatted in FASTA
	      format where there exists an additional
	      <filename>.fasta.qual</filename> file which contains quality
	      data. If the file with quality data is missing, this is
	      interpreted as error and MIRA will abort.
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      <filename>.fna</filename> and <filename>.fa</filename> also
	      for sequences formatted in FASTA format. The difference
	      to <filename>.fasta</filename> lies in the way MIRA treats a
	      missing quality file (called
	      <filename>.fna.qual</filename>
	      or <filename>.fa.qual</filename>): it does not see that as
	      critical error and continues.
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      <filename>.fastq</filename> or <filename>.fq</filename> for files in FASTQ format
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      <filename>.gff3</filename> or <filename>.gff</filename> for files in GFF3 format. Note that
	      MIRA will load all sequences and annotations contained in this
	      file.
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      <filename>.gbk</filename>, <filename>.gbf</filename>, <filename>.gbff</filename>
	      or <filename>.gb</filename> 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!
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      <filename>.caf</filename> for files in the CAF format (from Sanger Centre)
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      <filename>.maf</filename> for files in the MIRA MAF format
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      <filename>.exp</filename> for files in the Staden EXP format.
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      <filename>.fofnexp</filename> for a <emphasis>file of EXP
	      filenames</emphasis> which all point to files in the Staden EXP
	      format.
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      <filename>.xml</filename>, <filename>.ssaha2</filename> and <filename>.smalt</filename> for ancillary data in NCBI TRACEINFO, SSAHA2 or SMALT format respectively.
	    </para>
	  </listitem>
	</itemizedlist>
	<para>
	  Multiple 'data' lines and multiple entries per line (even
	  different formats) are allowed, as in, e.g.,
	</para>
	<screen>data = file1.fastq file2.fastq file3.fasta file4.gbk
data = myscreenings.smalt</screen>
	<para>
	  You can also use wildcards and/or directory names. E.g., loading
	  all file types MIRA understand from a given directory
	  <filename>mydir</filename>:
	</para>
	<screen>data = mydir</screen>
	<para>
	  or loading all files starting with <filename>mydata</filename> and
	  ending with <filename>fastq</filename>:
	</para>
	<screen>data = mydata*fastq</screen>
	<para>
	  or loading all files in directory <filename>mydir</filename>
	  starting with <filename>mydata</filename> and ending with
	  <filename>fastq</filename>:
	</para>
	<screen>data = mydir/mydata*fastq</screen>
	<para>
	  or loading all FASTQ files in all directories starting with <filename>mydir</filename>:
	</para>
	<screen>data = mydir*/*fastq</screen>
	<para>
	  or ... well, you get the gist.
	</para>
	<note>
	  Giving a directory like in <filename>mydir</filename> is
	  equivalent to <filename>mydir/*</filename> (saying: give me all
	  files in the directory <filename>mydir</filename>), however the
	  first version should be preferred when the directory contains
	  thousands of files.
	</note>
	<note>
	  <para>
	    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.
	  </para>
	  <para>
	    As security measure, annotations in GenBank and GFF3 files for which
	    absolutely no sequence or read has been defined are treated as
	    error.
	  </para>
	</note>
	<para>
	  <emphasis>Explicit definition of file types.</emphasis> It is
	  possible to explicitly tell MIRA the type of a file even if said
	  file does not have a 'standard' naming scheme. For this, the
	  EMBOSS double-colon notation has been adapted to work also for
	  MIRA, i.e., you prepend the type of a file and separate it from
	  the file name by a double colon. E.g.,
	  the <filename>.dat</filename> postfix is not anything MIRA will
	  recognise, but you can define it should be loaded as FASTQ file
	  like this:
	</para>
	<screen>data = fastq::myfile.dat</screen>
	<para>
	  Another frequent usage is forcing MIRA to load FASTA files
	  named <filename>.fasta</filename> without complaining in case
	  quality files (which MIRA wants you to provide) are not present:
	</para>
	<screen>data = fna::myfile.fasta</screen>
	<para>
	  This does (of course) work also with directories or wildcard
	  characters. In the following example, the first line will load all
	  files from <filename>mydirectory</filename> as FASTQ while the
	  second line loads just <filename>.dat</filename> files in a given
	  path as FASTA:
	</para>
	<screen>data = fastq::mydirectory
data = fasta::/path/to/somewhere/*.dat</screen>
	<para>
	  It is entirely possible (although not really sensible), to give
	  contradicting information to MIRA by using a different explicit
	  file type than one would guess from the standard postfix. In this
	  case, the explicit type takes precedence over the automatic
	  type. E.g.: to force MIRA to load a file as FASTA although it is
	  named <filename>.fastq</filename>, one could use this:
	</para>
	<screen>data = fasta::file.fastq</screen>
	<para>
	  Note that the above does not make any kind of file conversion,
	  <filename>file.fastq</filename> needs to be already in FASTA
	  format or else MIRA will fail loading that data.
	</para>
      </sect3>
      <sect3 id="sect_ref_manifest_readgroups_defaultqual">
      <title>
	Setting default quality
      </title>
	<para>
	  <emphasis role="bold">default_qual</emphasis>=
	  <replaceable>quality_value</replaceable> is meant to be used as
	  default fall-back 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.
	</para>
      </sect3>
      <sect3 id="sect_ref_manifest_readgroups_technology">
	<title>
	  Defining technology used to sequence
	</title>
	<para>
	  <emphasis role="bold">technology</emphasis>=
	  <replaceable>technology</replaceable> which names the technology
	  with which the sequences were produced. Allowed technologies are:
	  <emphasis>sanger, 454, solexa, iontor, pcbiolq, pcbiohq,
	  text</emphasis>.
	</para>
	<para>
	  The <emphasis>text</emphasis> technology is not a technology per
	  se, but should be used for sequences which are not coming 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
	</para>
      </sect3>
      <sect3 id="sect_ref_manifest_readgroups_nostatistics">
	<title>
	  Preventing statistics for technologies with biases
	</title>
	<para>
	  <emphasis role="bold">nostatistics</emphasis> used as keyword will
	  prevent MIRA to calculate coverage estimates from reads of the given
	  readgroup.
	</para>
	<para>
	  This keyword should be used in denovo genome assemblies for reads
	  from libraries which produce very uneven coverage (e.g.: old
	  Illumina mate-pair protocols) or have a bias in the randomness of
	  DNA fragmentations (e.g.: Nextera protocol from Illumina).
	</para>
      </sect3>
      <sect3 id="sect_ref_manifest_readgroups_asreference">
      <title>
	Setting reference sequence for mapping jobs
      </title>
	<para>
	  <emphasis role="bold">as_reference</emphasis> 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.
	</para>
      </sect3>
      <sect3 id="sect_ref_manifest_readgroups_autopairing">
      <title>
	Autopairing: letting MIRA find out pair info by itself
      </title>
	<para>
	  <emphasis role="bold">autopairing</emphasis> This keyword is used
	  to tell MIRA it should estimate values for
	  <emphasis>template_size</emphasis> and
	  <emphasis>segment_placement</emphasis> (see below).
	</para>
	<para>
	  This is basically the lazy way to tell MIRA that the data in the
	  corresponding readgroup consists of paired reads and that you
	  trust it will find out the correct values.
	</para>
	<note>
	  <emphasis>autopairing</emphasis> usually works quite well for
	  small and mid-sized libraries (up to, say, 10 kb). For larger
	  libraries it might be a good thing to tell MIRA some rough
	  boundaries via <emphasis>template_size</emphasis> /
	  <emphasis>segment_placement</emphasis> and let MIRA refine the
	  values for the template size via <emphasis>autorefine</emphasis>
	  (see below).
	</note>
	<note>
	  <emphasis>autopairing</emphasis> is a feature new to MIRA 4.0rc5,
	  it may contain bugs for some corner cases. Feedback appreciated.
	</note>
      </sect3>
      <sect3 id="sect_ref_manifest_readgroups_templatesize">
      <title>
	Setting size of read templates
      </title>
	<para>
	  <emphasis role="bold">template_size </emphasis>=
	  <replaceable>min_size max_size
	  <emphasis>[infoonly|exclusion_criterion]</emphasis>
	  <emphasis>[autorefine]</emphasis></replaceable>. Defines the
	  minimum and maximum size of "good" DNA templates in the library
	  prep for this read group. This defines at which distance the two
	  reads of a pair are to be expected in a contig, a very useful
	  information for an assembler to resolve repeats in a genome or
	  different splice variants in transcriptome data.
	</para>
	<para>
	  If the term <emphasis>infoonly</emphasis> 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 or mapping
	  assembly. The term <emphasis>exclusion_criterion</emphasis> makes
	  MIRA use the information for decision making.
	</para>
	<para>
	  If <emphasis>infoonly</emphasis>
	  or <emphasis>exclusion_criterion</emphasis> are missing, then MIRA
	  assumes <emphasis>exclusion_criterion</emphasis> for de-novo
	  assemblies and <emphasis>infoonly</emphasis> for mapping
	  assemblies.
	</para>
	<para>
	  If the term <emphasis>autorefine</emphasis> is present, MIRA will
	  start the assembly with the given size information but switch to
	  refined value computed from observed distances in an
	  assembly. However, please note that the size values
	  can <emphasis>never</emphasis> be expanded, only shrunk. It is
	  therefore advisable to use generous bounds when using the
	  autorefine feature.
	</para>
	<note>
	  The <emphasis>template_size</emphasis> line in the manifest file
	  replaces the parameters -GE:uti:tismin:tismax of earlier versions
	  of MIRA (3.4.x and below).
	</note>
	<note>
	  The minimum or the maximum size (or both) can be set to a negative
	  value for "don't care and don't check". This allows constructs
	  like <literal>template_size= 500 -1 exclusion_criterion</literal>
	  which would check only the minimum distance but not the maximum
	  distance.
	</note>
	<note>
	  <para>
	    For <emphasis>mapping</emphasis> assemblies with MIRA, you
	    usually will want to use <emphasis>infoonly</emphasis> as else -
	    in case of genome re-arrangements, larger deletions or
	    insertions - MIRA would probably reject one read of every read
	    pair in the corresponding areas 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.
	  </para>
	  <para>
	    For <emphasis>de-novo</emphasis> assemblies however
	    you <emphasis>should not</emphasis>
	    use <emphasis>infoonly</emphasis> except in very rare cases
	    where you know what you do.
	  </para>
	</note>
	<sidebar>
	  <title>
	    Understanding the size of DNA templates
	  </title>
	  <para>
	    When using a <emphasis>paired-end</emphasis> or
	    <emphasis>mate-pair</emphasis> 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, like so:
	  </para>
	  <screen>DNA template    ##############################################################
read 1          .......
read 2                                                                  ......
&lt;------------------------- ~6 kb ----------------------------&gt;</screen>
	  <para>
	    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.
	  </para>
	</sidebar>
      </sect3>
      <sect3 id="sect_ref_manifest_readgroups_segplace">
      <title>
	Read segment placement
      </title>
      <note>You do not need to use this when using 'autopairing' (see above).</note>
	<para>
	  <emphasis role="bold">segment_placement </emphasis>=
	  <replaceable>placementcode <emphasis>[infoonly|exclusion_criterion]</emphasis></replaceable>. Allowed
	  placement codes are:
	</para>
	<itemizedlist>
	  <listitem>
	    <para>
	      <emphasis role="bold">?</emphasis>
	      or <emphasis role="bold">unknown</emphasis> which are
	      place-holders for "well, in the end: don't care." Segments of
	      a template can be reads in any direction and in any
	      relationship to each other.
	    </para>
	    <para>
	      This is typically used for unpaired libraries (sometimes
	      called <emphasis>shotgun libraries</emphasis>), but may be
	      also useful for, e.g., primer walking with Sanger.
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      <emphasis role="bold">---&gt; &lt;---</emphasis> or <emphasis
	      role="bold">FR</emphasis> or <emphasis
	      role="bold">INNIES</emphasis>. The <emphasis>forward /
	      reverse</emphasis> scheme as used in traditional Sanger
	      sequencing as well as Illumina paired-end sequencing,
	    </para>
	    <para>
	      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.
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      <emphasis role="bold">&lt;--- ---&gt;</emphasis> or <emphasis
	      role="bold">RF</emphasis> or <emphasis
	      role="bold">OUTIES</emphasis>. The <emphasis>reverse /
	      forward</emphasis> scheme as used in Illumina mate-pair
	      sequencing.
	    </para>
	    <para>
	      This is the usual placement code for Illumina mate-pair protocols.
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      <emphasis role="bold">1---&gt; 2---&gt;</emphasis> or
	      <emphasis role="bold">samedir forward</emphasis> or <emphasis
	      role="bold">SF</emphasis> or <emphasis
	      role="bold">LEFTIES</emphasis>. The <emphasis>forward /
	      forward</emphasis> scheme. Segments of a template are all
	      placed in the same direction, the segment order in the contig
	      follows segment ordering of the reads.
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      <emphasis role="bold">2---&gt; 1---&gt;</emphasis> <emphasis
	      role="bold">samedir backward</emphasis> or <emphasis
	      role="bold">SB</emphasis> or <emphasis
	      role="bold">RIGHTIES</emphasis>. 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.
	    </para>
	    <para>
	      This is the usual placement code for 454 "paired-end" and IonTorrent
	      long-mate protocols.
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      <emphasis role="bold">samedir</emphasis> Segments of a
	      template are all placed in the same direction, the spatial
	      relationship however is not cared of.
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      <emphasis role="bold">&gt;&gt;&gt;</emphasis> (reserved for
	      sequencing of several equidistant fragments per template like
	      in PacBio strobe sequencing, not implemented yet)
	    </para>
	  </listitem>
	</itemizedlist>
	<para>
	  If the term <emphasis>infoonly</emphasis> 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 <emphasis>exclusion_criterion</emphasis> makes MIRA use the information for decision making.
	</para>
	<para>
	  If <emphasis>infoonly</emphasis> or <emphasis>exclusion_criterion</emphasis> are missing, then MIRA assumes <emphasis>exclusion_criterion</emphasis> for de-novo assemblies and <emphasis>infoonly</emphasis> for mapping assemblies.
	</para>
	<note>
	  <para>
	    For <emphasis>mapping</emphasis> assemblies with MIRA, you
	    usually will want to use <emphasis>infoonly</emphasis> as else -
	    in case of genome re-arrangements, larger deletions 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.
	  </para>
	  <para>
	    For <emphasis>de-novo</emphasis> assemblies however
	    you <emphasis>should not</emphasis>
	    use <emphasis>infoonly</emphasis> except in very rare cases
	    where you know what you do.
	  </para>
	</note>
	<note>
	  As soon as you tell MIRA that a readgroup contains paired reads (via one of the other typical readgroup parameters like template_size, segment_naming etc.), the <emphasis>segment_placement</emphasis> line becomes mandatory in the manifest. This is because different sequencing technologies and/or library preparations result in different read orientations. E.g., Illumina libraries come in paired-end flavour which have FR (forward/reverse) placements, but there are also mate-pair libraries which have reverse/forward (RF) placements.
	</note>
	<sidebar>
	  <title>
	    Understanding read segment placement on DNA templates
	  </title>
	  <para>
	    bla
	  </para>
	</sidebar>
      </sect3>
      <sect3 id="sect_ref_manifest_readgroups_segname">
      <title>
	Read segment naming
      </title>
	<para>
	  <emphasis role="bold">segment_naming </emphasis>= <replaceable>naming_scheme <emphasis>[rollcomment]</emphasis></replaceable>. Defines
	  the naming scheme reads are following to indicate the DNA template
	  they belong to. Allowed naming schemes are: <emphasis>sanger,
	  stlouis, tigr, FR, solexa, sra</emphasis>.
	</para>
	<para>
	  If not defined, the defaults are <emphasis
	  role="underline">sanger</emphasis> for Sanger sequencing data,
	  while <emphasis role="underline">solexa</emphasis> for Solexa, 454
	  and Ion Torrent.
	</para>
	<para>
	  For FASTQ files, the modifier <emphasis>rollcomment</emphasis> can
	  be used to let MIRA take the first token in the comment as name of
	  a read instead of the orginal name. E.g.: for a read
	</para>
	<screen>@DRR014327.1.1 HWUSI-EAS547_0013:1:1:1106:4597.1 length=91
TTAGAAGGAGATCTGGAGAACATTTTAAACCGGATTGAACAACGCGGCCGTGAGATGGAGCTTCAGACAAGCCGGTCTTATTGGGACGAAC
+
bbb`bbbbabbR`\_bb_bba`b`bb_bb_`\^\^Y^`\Zb^b``]]\S^a`]]a``bbbb_bbbb]bbb\`^^^]\aaY\`\\^aa__aB</screen>
	<para>
	  the rollcomment modifier will lead to the read being named
	  <filename> HWUSI-EAS547_0013:1:1:1106:4597.1</filename> (which
	  is almost the original instrument read name) instead of
	  <filename>DRR014327.1.1</filename> (which is the SRA read name).
	</para>
	<warning>
	  For data from the short read archive (SRA), one will usually need
	  to explicitly specify the 'sra' naming scheme or use the
	  'rollcomment' modifier in FASTQ files.
	</warning>
	<note>
	  This has changed with MIRA 3.9.1
	  and <command>sff_extract</command> 0.3.0. Before that, 454 and Ion
	  Torrent were given <emphasis role="underline">fr</emphasis> as naming
	  scheme.
	</note>
	<sidebar>
	  <title>
	    Understanding read naming schemes
	  </title>
	  <para>
	    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. See also XKCD entry on <ulink url="http://xkcd.com/927/">proliferating standards</ulink>.
	  </para>
	  <para>
	    How to choose: please read the documentation available at the
	    different centres or ask your sequence provider. In a nutshell
	    (and probably over-simplified):
	  </para>
	  <variablelist>
	    <varlistentry>
	      <term>
		Sanger scheme
	      </term>
	      <listitem>
		<para>
		  "somename<emphasis>.[pqsfrw][12][bckdeflmnpt][a|b|c|...</emphasis>"
		  (e.g.  U13a08f10.p1ca), but the length of the postfix
		  must be at least 4 characters, i.e., ".p" alone will not
		  be recognised.
		</para>
		<para>
		  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).
		</para>
	      </listitem>
	    </varlistentry>
	    <varlistentry>
	      <term>
		TIGR scheme
	      </term>
	      <listitem>
		<para>
		  "somename<emphasis>TF*|TR*|TA*</emphasis>"
		  (e.g. GCPBN02TF or GCPDL68TABRPT103A58B),
		</para>
		<para>
		  Forward reads take "TF*", reverse reads "TR*".
		</para>
	      </listitem>
	    </varlistentry>
	    <varlistentry>
	      <term>
		St. Louis scheme
	      </term>
	      <listitem>
		<para>
		  "somename<emphasis>.[sfrxzyingtpedca]*</emphasis>"
		</para>
	      </listitem>
	    </varlistentry>
	    <varlistentry>
	      <term>
		Forward/Reverse scheme
	      </term>
	      <listitem>
		<para>
		  "somename<emphasis>.[fr]*</emphasis>"
		  (e.g.  E0K6C4E01DIGEW.f or E0K6C4E01BNDXN.r2nd),
		</para>
		<para>
		  ".f*" for forward, ".r*" for reverse.
		</para>
	      </listitem>
	    </varlistentry>
	    <varlistentry>
	      <term>
		Solexa scheme
	      </term>
	      <listitem>
		<para>
		  Even simpler than the forward/reverse scheme, it allows
		  only for one two reads per template:
		  "somename<emphasis>/[12]</emphasis>"
		</para>
	      </listitem>
	    </varlistentry>
	    <varlistentry>
	      <term>
		SRA scheme
	      </term>
	      <listitem>
		<para>
		  The Short Read Archive (SRA) finally settled on a naming
		  scheme and renames each and every read within its
		  database. When you download sequences from the archive,
		  all reads will be named
		  <filename>XXX000000.Y[.Z]</filename> (where X's are
		  characters A-Z, 0 are digits from 0 to 9, Y is a counter
		  and Z is a number denoting the segment (usually 1,2 or
		  3)). This naming scheme is applied to reads from all
		  technologies, therefore the MIRA technology dependent
		  defaults will not apply and one must specify the 'sra'
		  naming scheme in the command line.
		</para>
	      </listitem>
	    </varlistentry>
	  </variablelist>
	</sidebar>
	<para>
	  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).
	</para>
      </sect3>
      <sect3 id="sect_ref_manifest_readgroups_strainname">
      <title>
	Strain naming
      </title>
	<para>
	  <emphasis role="bold">strain_name </emphasis>=
	  <replaceable>string</replaceable>. Defines the strain /
	  organism-code the reads of this read group are from. If not set,
	  MIRA will assign "StrainX" to normal readgroups and
	  "ReferenceStrain" to readgroups with reference sequences.
	</para>
	<para>
	  Restrictions: in de-novo assemblies you can have 255 strain. In
	  mapping assemblies, you can have at most 8 strains.
	</para>
	<sidebar>
	  <title>
	    Understanding how MIRA uses strain information
	  </title>
	  <para>
	    bla
	  </para>
	</sidebar>
      </sect3>
      <sect3 id="sect_ref_manifest_readgroups_datadirscf">
      <title>
	Data directory for SCF files
      </title>
	<para>
	  <emphasis role="bold">datadir_scf </emphasis>=
	  <replaceable>directory</replaceable>
	</para>
	<para>
	  For SANGER data only: tells MIRA in which directory it can find
	  SCF data belonging to reads of this read group.
	</para>
      </sect3>
      <sect3 id="sect_ref_manifest_readgroups_renameprefix">
      <title>
	Renaming read name prefixes
      </title>
	<para>
	  <emphasis role="bold">rename_prefix</emphasis>=
	  <replaceable>prefix replacement</replaceable>. Allows to rename
	  reads on the fly while loading data by searching each read name
	  for a given <emphasis>prefix</emphasis> string and, if found,
	  replace it with a given <emphasis>replacement</emphasis> string.
	</para>
	<para>
	  This is most useful for systems like Illumina or PacBio which
	  generate quite long read names which, in the end, are either
	  utterly useless for an end user or are even breaking older
	  programs which have a length restriction on read names. E.g.:
	</para>
	<screen>rename_prefix = DQT9AAQ4:436:H371HABMM: Sample1_</screen>
	<para>
	  will rename reads
	  like <emphasis>DQT9AAQ4:436:H371HABMM:5:1101:9154:3062</emphasis>
	  into <emphasis>Sample1_5:1101:9154:3062</emphasis>
	</para>
	<note>
	  <literal>rename_prefix</literal> entries are valid per
	  readgroup. I.e., an entry for a readgroup will not rename reads of
	  another readgroup.
	</note>
	<note>
	  <para>
	    Multiple <literal>rename_prefix</literal> entries are
	    allowed per readgroup. E.g.:
	  </para>
	  <screen>rename_prefix = DQT9AAQ4:436:H371HABMM: S1sxa_
rename_prefix = m140328_002546_42149_c100624422550000001823118308061414_s1_ S1pb_</screen>
	  <para>
	    will rename a read
	    called <literal>DQT9AAQ4:436:H371HABMM:1:1101:3099:2186</literal>
	    into <literal>S1sxa_1:1101:3099:2186</literal> while renaming
	    another read called <literal>m140328_002546_42149_c100624422550000001823118308061414_s1_p0/100084/10792_20790/0_9573</literal>
	    into <literal>S1pb_p0/100084/10792_20790/0_9573</literal>
	  </para>
	</note>
      </sect3>
    </sect2>
    <sect2 id="sect_ref_manifest_parameters">
      <title>
	The manifest file: extended parameters
      </title>
      <para>
	The <emphasis role="bold">parameters=</emphasis> 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.
      </para>
      <sect3 id="sect_ref_parameter_groups">
	<title>
	  Parameter groups
	</title>
	<para>
	  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.
	</para>
	<para>
	  MIRA uses <emphasis>parameter groups</emphasis> to keep parameters
	  together which somehow belong together. Example given:
	</para>
      <screen>
<userinput>parameters = <replaceable> -GENERAL:number_of_threads=4 \
              -ALIGN:min_relative_score=70 -ASSEMBLY:minimum_read_length=150 \
              -OUTPUT:output_result_caf=no</replaceable></userinput></screen>
      <para>
	The parameters of the different parameter groups are described in
	detail a bit later in this manual.
      </para>
      </sect3>
      <sect3 id="sect_ref_technology_sections">
	<title>
	  Technology sections
	</title>
	<para>
	  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.
	</para>
	<para>
	  To allow very fine grained behaviour, especially in hybrid
	  assemblies, and to prevent the explosion of parameter names, MIRA
	  knows two categories of parameters:
	</para>
	<orderedlist>
	  <listitem>
	    <para>
	      <emphasis role="bold">technology independent parameters</emphasis>
	      which control general behaviour of MIRA like, e.g., the number of
	      assembly passes or file names etc.
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      <emphasis role="bold">technology dependent parameters</emphasis>
	      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).
	    </para>
	  </listitem>
	</orderedlist>
	<para>
	  More on this a bit further down in this documentation.
	</para>
	<para>
	  As example, a manifest using technology dependent and independent parameters could
	  look like this:
	</para>
	<screen>
<userinput>parameters = <replaceable>COMMON_SETTINGS -GENERAL:number_of_threads=4 \
              SANGER_SETTINGS -ALIGN:min_relative_score=70 -ASSEMBLY:minimum_read_length=150 \
              454_SETTINGS -ALIGN:min_relative_score=75 -ASSEMBLY:minimum_read_length=100 \
              SANGER_SETTINGS -ALIGN:min_relative_score=90 -ASSEMBLY:minimum_read_length=75</replaceable></userinput></screen>
	<para>
	  Now, assume the following read group descriptions in a manifest:
	</para>
	<screen>
...

readgroup
technology=454
...

readgroup
technology=solexa
...</screen>
	<para>
	  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.
	</para>
	<para>
	  Here is as example a part of the output of used parameters that MIRA
	  will show when started with 454 and Illumina (Solexa) data:
	</para>
	<screen>
...

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)                   :  [454]  40
                                                   [sxa]  20
    Enforce presence of qualities (epoq)        :  [454]  no
                                                   [sxa]  yes

...</screen>
	<para>
	  You can see the two different kind of settings that MIRA uses:
	  <emphasis>common</emphasis> <emphasis>settings</emphasis> (like
	  <arg>-AS:nop</arg>) which allows only one value and
	  <emphasis>technology</emphasis> <emphasis>dependent</emphasis>
	  <emphasis>settings</emphasis> (like <arg>-AS:mrl</arg>), where for
	  each sequencing technology used in the project, the setting can be
	  different.
	</para>
	<para>
	  How would one set a minimum read length of 40 and not enforce
	  presence of base qualities for Sanger reads, but for 454 reads a
	  minimum read length of 30 and enforce base qualities? The answer:
	</para>
	<screen>
job=denovo,genome,draft
parameters= SANGER_SETTINGS -AS:mrl=40:epoq=mo 454_SETTINGS -AS:mrl=40:epoq=yes</screen>
	<para>
	  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.
	</para>
	<note>
	  <para>
	    For improved readability, you can distribute parameters across
	    several lines either by pre-fixing every line with
	    <literal>parameter=</literal>, like so:
	  </para>
	  <screen>
job=denovo,genome,draft
parameters= SANGER_SETTINGS -AS:mrl=80:epoq=no
parameters= 454_SETTINGS -AS:mrl=30:epoq=yes</screen>
          <para>
	    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:
	  </para>
	  <screen>
job=denovo,genome,draft
parameters= SANGER_SETTINGS -AS:mrl=80:epoq=no <userinput>\</userinput>
            454_SETTINGS -AS:mrl=30:epoq=yes</screen>
	  <para>
	    Note that the very last line of the parameters settings MUST NOT
	    end with a backslash.
	  </para>
	</note>
	<para>
	  Beside COMMON_SETTINGS there are currently 6 technology settings available:
	</para>
	<orderedlist>
	  <listitem>
	    <para>
	      SANGER_SETTINGS
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      454_SETTINGS
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      IONTOR_SETTINGS
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      PCBIOLQ_SETTINGS (currently not supported)
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      PCBIOHQ_SETTINGS
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      SOLEXA_SETTINGS
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      TEXT_SETTINGS
	    </para>
	  </listitem>
	</orderedlist>
	<para>
	</para>
	<para>
	  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
	</para>
	<screen>
<userinput>parameters= 454_SETTINGS -AS:nop=4 SOLEXA_SETTINGS -AS:nop=3</userinput></screen>
	<para>
	  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
	</para>
	<screen>
<userinput>parameters= COMMON_SETTINGS -AS:nop=4 454_SETTINGS ... SOLEXA_SETTINGS ...</userinput></screen>
	<para>
	</para>
	<para>
	  Since MIRA 3rc3, the parameter parser will help you by checking
	  whether parameters are correctly defined as COMMON_SETTINGS or
	  technology dependent setting.
	</para>
      </sect3>
      <sect3 id="sect_ref_parameter_shortnames">
	<title>
	  Parameter short names
	</title>
	<para>
	  Writing the verbose form of parameters can be quite a long task. Here a short example:
	</para>
	<screen>
<userinput>parameters = <replaceable>COMMON_SETTINGS -GENERAL:number_of_threads=4 \
              SANGER_SETTINGS -ALIGN:min_relative_score=70 -ASSEMBLY:minimum_read_length=150 \
              454_SETTINGS -ALIGN:min_relative_score=75 -ASSEMBLY:minimum_read_length=100 \
              SOLEXA_SETTINGS -ALIGN:min_relative_score=90 -ASSEMBLY:minimum_read_length=75</replaceable></userinput></screen>
	<para>
	  However, every parameter has a shortened form. The above could be written like this:
	</para>
	<screen>
<userinput>parameters = <replaceable>COMMON_SETTINGS -GE:not=4 \
              SANGER_SETTINGS -AL:mrs=70 -AS:mrl=150 \
              454_SETTINGS -AL:mrs=75 -AS:mrl=100 \
              SOLEXA_SETTINGS -AL:mrs=90 -AS:mrl=75</replaceable></userinput></screen>
      <para>
	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):
      </para>
      <screen>
<userinput>parameters = <replaceable>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</replaceable></userinput></screen>
      </sect3>
      <sect3 id="sect_ref_order_dependent_quick_switches">
	<title>
	  Order dependent quick switches
	</title>
	<para>
	  For some parameters, the order of appearance in the parameter lines
	  of the manifest is important. This is because the <emphasis>quick
	  parameters</emphasis> 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.
	</para>
	<variablelist>
	  <varlistentry>
	    <term>
	      <arg>--hirep_best</arg>
	    </term>
	    <term>
	      <arg>--hirep_good</arg>
	    </term>
	    <term>
	      <arg>--hirep_something</arg>
	    </term>
	    <listitem>
	      <para>
		These are modifier switches for genome data that is deemed to
		be highly repetitive. With <emphasis>hirep_good</emphasis> and
		<emphasis>hirep_best</emphasis>, the assemblies will run
		slower due to more iterative cycles and slightly different
		default parameter sets that give MIRA a chance to resolve many
		nasty repeats. The <emphasis>hirep_something</emphasis> switch
		goes the other way round and resolves repeats less well than a
		normal assembly, but allows MIRA to finish even on more
		complex data.
	      </para>
	      <para>
		Usage recommendations bacteria: starting MIRA without any
		hirep switches yields good enough result in most cases. Under
		normal circumstances one can use
		<emphasis>hirep_good</emphasis> or
		even <emphasis>hirep_best</emphasis> without remorse as data
		sets and genome complexities are small enough to run within a
		couple of hours at most.
	      </para>
	      <para>
		Usage recommendations for 'simple' lower eukaryotes: starting
		MIRA without any hirep switches yields good enough result in
		most cases. If the genomes are not too complex,
		using <emphasis>hirep_good</emphasis> can be a possibility.
	      </para>
	      <para>
		Usage recommendations for lower eukaryotes with complex
		repeats: starting MIRA without any hirep switches might
		already take too long or create temporary data files which are
		too big. For these cases, using
		<emphasis>hirep_something</emphasis> makes MIRA use a
		parameter set which is targeted as resolving the
		non-repetitive areas of a genome and additionally all repeats
		which occur less than 10 times in the genome. Repeats occurring
		more often will not be resolved, but using the debris
		information one can recover affected reads and use these with
		harsh data reduction algorithms (e.g. digital normalisation)
		to get a glimpse into these.
	      </para>
	      <note>
		These switches replace the '--highlyrepetitive' switch from
		earlier versions.
	      </note>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>--noclipping=...</arg>
	    </term>
	    <listitem>
	      <para>
		Switching off clipping options. If used
		as <literal>--noclipping</literal>
		or <literal>--noclipping=all</literal>, this switches off
		really everything, both technology dependent and independent switches.
		Clipping options for technology dependent options be switched
		off via entries being <emphasis>sanger</emphasis>,
		<emphasis>454</emphasis>, <emphasis>iontor</emphasis>,
		<emphasis>solexa</emphasis> or
		<emphasis>solid</emphasis>. Multiple entries separated by
		comma are allowed.
	      </para>
	      <para> Examples:
	      </para>
	      <orderedlist>
		<listitem>
		  <para>
		    Switch off 454 and Solexa, but keep technology independent
		    clippings and all clippings for other technologies, (like,
		    e.g., Sanger) <literal>--noclipping=454,solexa</literal>
		  </para>
		</listitem>
		<listitem>
		  <para>
		    Switch off really
		    everything: <literal>--noclipping</literal>
		    or <literal>--noclipping=all</literal>
		  </para>
		</listitem>
	      </orderedlist>
	      <note>
		<para>
		  Switching off technology independent clippings
		  (<arg>-CL:pec</arg>, <arg>-CL:gbcdc</arg>, <arg>-CL:kjd</arg>)
		  via this switch has been implemented for consistency in MIRA
		  4.9.6. Prior to this they were kept active, which created a
		  good deal of confusion with a number of users.
		</para>
		<para>
		  As soon as you have any kind of 'real' sequencing data, you
		  really should use at least <arg>-CL:pec</arg>
		  and <arg>-CL:gbcdc</arg>.
		</para>
	      </note>
	    </listitem>
	  </varlistentry>
	</variablelist>
      </sect3>
      <sect3 id="sect_ref_general_ge">
	<title>
	  Parameter group: -GENERAL (-GE)
	</title>
	<para>
	  General options control the type of assembly to be performed and
	  other switches not belonging anywhere else.
	</para>
	<variablelist>
	  <varlistentry>
	    <term>
	      <arg>number_of_threads(not)=<replaceable>0 &le; integer &le; 256</replaceable></arg>
	    </term>
	    <listitem>
	      <para> Default is <emphasis
	      role="underline">0</emphasis>. Master switch to set the number
	      of threads used in different parts of MIRA.
	      </para>
	      <para>
		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.
	      </para>
	      <para>
		In case MIRA cannot find out the number of cores, the
		fall-back value is <emphasis role="underline">2</emphasis>.
	      </para>
	      <para>
		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.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>automatic_memory_management(amm)=<replaceable>on|y[es]|t[rue], off|n[o]|f[alse]</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		Default is <emphasis role="underline">Yes</emphasis>. 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.
	      </para>
	      <para>
		Note 1: This functionality currently relies on the
		<filename>/proc</filename> file system giving information on
		the system memory ("MemTotal" in /proc/meminfo) and the memory
		usage of the current process ("VmSize" in
		<filename>/proc/self/status</filename>). If this is not
		available, the functionality is switched off.
	      </para>
	      <para>
		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.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>max_process_size(mps)=<replaceable>0 &le; integer</replaceable></arg>
	    </term>
	    <listitem>
	      <para> Default is <emphasis role="underline">0</emphasis>. 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.
	      </para>
	      <para>
		Note: when in competition to <arg>-GE:kpmf</arg> (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.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>keep_percent_memory_free(kpmf)=<replaceable>0 &le; integer</replaceable></arg>
	    </term>
	    <listitem>
	      <para> Default is <emphasis role="underline">10</emphasis>. If
	      automatic memory management is used (see above), this number
	      works a bit like <arg>-GE:mps</arg> but the other way round: it
	      tries to keep x percent of the memory free.
	      </para>
	      <para>
		Note: when in competition to <arg>-GE:mps</arg> (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 <arg>-GE:mps</arg> but have a
		<arg>-GE:kpmf</arg> of 50, then the MIRA process will try to
		stay within 64-(64*50%)=32 GiB.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>preprocess_only(ppo)=<replaceable>on|y[es]|t[rue], off|n[o]|f[alse]</replaceable></arg>
	    </term>
	    <listitem>
	      <para> Default is <emphasis role="underline">no</emphasis> As a
	      special use case, MIRA will just run the following tasks:
	      loading and clipping of reads as well as calculating kmer
	      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.
	      </para>
	      <para>
		No assembly is performed.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>est_snp_pipeline_step(esps)=<replaceable>1 &le; integer &le; 4</replaceable></arg>
	    </term>
	    <listitem>
	      <para> Default is <emphasis
	      role="underline">1</emphasis>. Controls the starting step of the
	      SNP search in EST pipeline and is therefore only useful in
	      miraSearchESTSNPs.
	      </para>
	      <para>
		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.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>print_date(pd)=<replaceable>on|y[es]|t[rue], off|n[o]|f[alse]</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		Default is <emphasis role="underline">yes</emphasis>. Controls
		whether date and time are printed out during the
		assembly. Suppressing it is not useful in normal operation,
		only when debugging or benchmarking.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>bang_on_throw(bot)=<replaceable>on|y[es]|t[rue], off|n[o]|f[alse]</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		Default is <emphasis role="underline">no</emphasis>. For
		debugging purposes only. Controls whether MIRA raises a signal
		when detecting an error which triggers a running debugger like
		gdb.
	      </para>
	    </listitem>
	  </varlistentry>
	</variablelist>
	<para>
	</para>
      </sect3>
      <sect3 id="sect_ref_assembly_as">
	<title>
	  Parameter group: -ASSEMBLY (-AS)
	</title>
	<para>
	  General options for controlling the assembly.
	</para>
	<variablelist>
	  <varlistentry>
	    <term>
	      <arg>num_of_passes(nop)=<replaceable>integer &ge; 0</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		Default is <emphasis role="underline">0</emphasis>. Defines how many iterations of the whole
		assembly process are done.
	      </para>
	      <para>
		The default of 0 will let MIRA choose automatically the number
		of passes and the kmer sizes used in each pass
		(see also <arg>-AS:kms</arg> below).
	      </para>
	      <para>
		Early termination: if the number of passes was chosen too
		high, one can simply create a file
		<filename><replaceable>projectname</replaceable>_assembly/<replaceable>projectname</replaceable>_d_chkpt/terminate</filename>. 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
		<filename>terminate_acknowledged</filename> and then run 2
		more passes (with special "last pass routines") before
		finishing the assembly.
	      </para>
	      <note>
		As a rule of thumb, <emphasis>de-novo</emphasis> assemblies
		should always have at least two passes,
		while <emphasis>mapping</emphasis> assemblies should work with
		only one pass. Not doing this will lead to results unexpected
		by users. The reason is that the 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).
	      </note>
	      <warning>
		MIRA versions &le; 4.0.2 were interpreting the value of '0' in
		a different way and only performed pre-processing of
		reads. MIRA can still do this, but this is controlled by the
		new parameter <arg>-GE:ppo</arg>.
	      </warning>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>kmer_series(kms)=<replaceable>comma separated list of integers &ge; 0 and &le; 256</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		Default is an empty value. If set, overrides <arg>-AS:nop</arg> and <arg>-SK:kms</arg>.
	      </para>
	      <para>
		If set, this parameter provides a one-stop-shop for defining the number of passes and the kmer size used in each pass. E.g.: <literal>-AS:kms=17,31,63,127</literal> defines an assembly with 4 passes which uses a kmer size of 17 in pass 1, 31 in pass 2, 63 in pass 3 and 127 in pass 4.
	      </para>
	      <para>
		Note that it is perfectly valid to use the same kmer size more than once, e.g.: <literal>17,31,63,63</literal> will perform a 4 pass assembly, using a kmer size of 63 in passes 3 and 4. It also makes sense to do this, as with default parameters MIRA uses its integrated automatic editor which edits away obvious sequencing errors in each step, thus the second pass with a kmer size of 63 bases can rely on improved reads.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>rmb_break_loops(rbl)=<replaceable>integer &gt; 0</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		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 pass
		(see <arg>-AS:nop</arg> or <arg>-AS:kms</arg>) if misassemblies due to possible repeats
		are found.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>max_contigs_per_pass(mcpp)=<replaceable>integer</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		Default is <emphasis role="underline">0</emphasis>. Defines
		how many contigs are maximally built in each pass. A value of
		0 stands for 'unlimited'. Values &gt;0 can be used for special
		use cases like test assemblies etc.
	      </para>
	      <para>
		If in doubt, do not touch this parameter.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>automatic_repeat_detection(ard)=<replaceable>on|y[es]|t[rue], off|n[o]|f[alse]</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		Default is is currently <emphasis role="underline">yes</emphasis>. Tells MIRA to use coverage
		information accumulated over time to more accurately pinpoint reads that are
		in repetitive regions.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>coverage_threshold(ardct)=<replaceable>float &gt; 1.0</replaceable></arg>
	    </term>
	    <listitem>
	      <para> Default is
	      <emphasis role="underline">2.0</emphasis> 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 <arg>-AS:ardct</arg> (over a length of
	      <arg>-AS:ardml</arg>, see below), then this read is considered to be
	      repetitive.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>min_length(ardml)=<replaceable>integer &gt; 1</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		Default is dependent of the sequencing technology, currently
		<emphasis role="underline">400</emphasis> for Sanger and
		<emphasis role="underline">200</emphasis> for 454 and Ion
		Torrent.
	      </para>
	      <para>
		A coverage must be at least this number of bases higher than
		<arg>-AS:ardct</arg> before being really treated as repeat.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>grace_length(ardgl)=<replaceable>integer &gt; 1</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		Default is dependent of the sequencing technology.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>uniform_read_distribution(urd)=<replaceable>on|y[es]|t[rue],
	      off|n[o]|f[alse]</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		Default is currently always <emphasis role="underline">no</emphasis>
		as these algorithms were supplanted by better ones in MIRA 4.0.
	      </para>
	      <para>
		Takes effect only if uniform read distribution
		(<arg>-AS:urd</arg>) is on.
	      </para>
	      <para>
		When set to <emphasis role="underline">yes</emphasis>, 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.
	      </para>
	      <para>
		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.
	      </para>
	      <para>
		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).
	      </para>
	      <para>
		This switch must be set to <emphasis
		role="underline">no</emphasis> for EST assembly, assembly of
		transcripts etc. It is recommended to also switch this off for
		mapping assemblies.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>urd_startinpass(urdsip)=<replaceable>integer &gt; 0</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		Default is dependent of the sequencing technology and assembly
		quality level. Recommended values are: 3 for an assembly with
		3 to 4 passes (<arg>-AS:nop</arg>). Assemblies with 5 passes
		or more should set the value to the number of passes minus 2.
	      </para>
	      <para>
		Takes effect only if uniform read distribution
		(<arg>-AS:urd</arg>) is on.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>urd_clipoffmultiplier(urdcm)=<replaceable>float &gt; 1.0</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		Default is <emphasis role="underline">1.5</emphasis> for all
	        sequencing technologies in most assembly cases.
	      </para>
	      <para>
		This option says this: if MIRA determined that the average
		coverage is <emphasis>x</emphasis>, 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
		<emphasis>x*urdcm</emphasis>. 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).
	      </para>
	      <para>
		Please note that the lower <arg>-AS:urdcm</arg> 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).
	      </para>
	      <para>
		Takes effect only if uniform read distribution (<arg>-AS:urd</arg>) is on.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>spoiler_detection(sd)=<replaceable>on|y[es]|t[rue], off|n[o]|f[alse]</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		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 <arg>-CL:pvc</arg> 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.
	      </para>
	      <para>
		Recommended for assemblies of mid- to high-coverage genomic
		assemblies, not recommended for assemblies of ESTs as one
		might loose splice variants with that.
	      </para>
	      <para>
		A minimum number of two assembly passes (<arg>-AS:nop</arg>)
		must be run for this option to take effect.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>sd_last_pass_only(sdlpo)=<replaceable>on|y[es]|t[rue], off|n[o]|f[alse]</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		Default is <emphasis role="underline">yes</emphasis>. Defines
		whether the spoiler detection algorithms are run only for the
		last pass or for all passes (<arg>-AS:nop</arg>).
	      </para>
	      <para>
		Takes effect only if spoiler detection (<arg>-AS:sd</arg>) is on. If in
		doubt, leave it to 'yes'.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>minimum_read_length(mrl)=<replaceable>integer &ge; 20</replaceable></arg>
	    </term>
	    <listitem>
	      <para> 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.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>minimum_reads_per_contig(mrpc)=<replaceable>integer &ge; 1</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		Default is dependent of the sequencing technology and the
		<arg>--job</arg> parameter. For genome assemblies it's usually
		around <emphasis role="underline">2</emphasis> for Sanger,
		<emphasis role="underline">5</emphasis> for 454, <emphasis
		role="underline">5</emphasis> for Ion Torrent, <emphasis
		role="underline">5</emphasis> for PacBio and <emphasis
		role="underline">10</emphasis> for Solexa. In EST assemblies,
		it's currently <emphasis role="underline">2</emphasis> for all
		sequencing technologies.
	      </para>
	      <para>
		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.
	      </para>
	      <para>
		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.
	      </para>
	      <note>
		Important: a value larger 1 of this parameter interferes with
		the functioning of <arg>-OUT:sssip</arg> and
		<arg>-OUT:stsip</arg>.
	      </note>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>enforce_presence_of_qualities(epoq)=<replaceable>on|y[es]|t[rue], off|n[o]|f[alse]</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		Default is <emphasis role="underline">yes</emphasis>. When set
		to yes, MIRA will stop the assembly if any read has no quality
		values loaded.
	      </para>
	      <note>
		<arg>-AS:epoq</arg> switches on/off the quality check for a
		complete sequencing technology. A more fine grained control
		for switching checks of per readgroup is available via
		the <emphasis>default_qual</emphasis> readgroup parameter in
		the manifest file.
	      </note>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>use_genomic_pathfinder(ugpf)=<replaceable>on|y[es]|t[rue], off|n[o]|f[alse]</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		Default is <emphasis role="underline">yes</emphasis>. 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.
	      </para>
	      <para>
		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 <emphasis
		role="underline">yes</emphasis> for genome projects and set to
		<emphasis role="underline">no</emphasis> for EST projects.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>use_emergency_search_stop(uess)=<replaceable>on|y[es]|t[rue], off|n[o]|f[alse]</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		Default is <emphasis role="underline">yes</emphasis>. 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.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>ess_partnerdepth(esspd)=<replaceable>integer &gt; 0</replaceable></arg>
	    </term>
	    <listitem>
	      <para> Default is <emphasis
	      role="underline">500</emphasis>. Defines the number of potential
	      partners a read must have for MIRA switching into emergency
	      search stop mode for that read.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>use_max_contig_buildtime(umcbt)=<replaceable>on|y[es]|t[rue],off|n[o]|f[alse]</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		Default is <emphasis role="underline">no</emphasis>. 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.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>buildtime_in_seconds(bts)=<replaceable>integer &gt; 0</replaceable></arg>
	    </term>
	    <listitem>
	      <para> Default is
	      <emphasis role="underline">3600</emphasis> for genome
	      assemblies, <emphasis role="underline">720</emphasis> for EST
	      assemblies with Sanger or 454
	      and <emphasis role="underline">360</emphasis> for EST assemblies
	      with Solexa or Ion Torrent. Depending on <arg>-AS:umcbt</arg>
	      above, this number defines the time in seconds allocated to
	      building one contig.
	      </para>
	    </listitem>
	  </varlistentry>
	</variablelist>
	<para>
	</para>
      </sect3>
      <sect3 id="sect_ref_strain_backbone_sb">
	<title>
	  Parameter group: -STRAIN/BACKBONE (-SB)
	</title>
	<para>
	  Controlling backbone options in mapping assemblies:
	</para>
	<variablelist>
	  <varlistentry>
	    <term>
	      <arg>bootstrap_new_backbone(bnb)=<replaceable>on|y[es]|t[rue], off|n[o]|f[alse]</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		Default is <emphasis role="underline">yes</emphasis> for
		mapping assemblies with Illumina data, no otherwise.
	      </para>
	      <para>
		When set to 'yes', MIRA will use a two stage mapping process
		which bootstraps an intermediate backbone (reference) sequence
		and greatly improves mapping accuracy at indel sites.
	      </para>
	      <note>
		Currently only works with Illumina data, other sequencing
		technologies will not be affected by this flag.
	      </note>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>startbackboneusage_inpass(sbuip)=<replaceable>0 &lt; integer</replaceable></arg>
	    </term>
	    <listitem>
	      <para> Default is
	      dependent on assembly quality level chosen: 0 for 'draft'
	      and <arg>-AS:nop</arg> divided by 2 for 'accurate'.
	      </para>
	      <para>
		When assembling against backbones, this parameter defines the
		pass iteration (see <arg>-AS:nop</arg>) 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.
	      </para>
	      <para>
		Rule of thumb: if backbones belong to same strain as reads to assemble, set
		to <emphasis role="underline">1</emphasis>. If backbones are a different strain, then set
		<arg>-SB:sbuib</arg> to 1 lower than <arg>-AS:nop</arg> (example: nop=4 and
		sbuip=3).
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>backbone_raillength(brl)=<replaceable>0 &le; integer &le; 10000</replaceable></arg>
	    </term>
	    <listitem>
	      <para> Default
	      is <emphasis role="underline">0</emphasis>. 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.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>backbone_railoverlap(bro)=<replaceable>0 &le; integer &le; 2000</replaceable></arg>
	    </term>
	    <listitem>
	      <para> Default is <emphasis role="underline">0</emphasis>.
	      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.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>trim_overhanging_reads(tor)=<replaceable>on|y[es]|t[rue], off|n[o]|f[alse]</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		Default is <emphasis role="underline">yes</emphasis>.
	      </para>
	      <para>
		When set to 'yes', MIRA will trim back reads at end of contigs
		which outgrow the reference sequence so that boundaries of
		the reference and the mapped reads align perfectly. That is,
		the mapping does not perform a sequence extension.
	      </para>
	      <note>
		The trimming is performed via setting low quality cutoffs in
		the reads, i.e., the trimmed parts are not really gone but
		just not part of the active contig anymore. They can be
		uncovered when working on the assembly in finishing programs
		like, e.g., <command>gap4</command>
		or <command>gap5</command>.
	      </note>
	      <warning>
		Previous versions of MIRA (up to and including 3.9.18) behaved
		as if this option had been set to 'no'. This is a major change
		in behaviour, but it is also what probably most people expect
		from a mapping.
	      </warning>
	    </listitem>
	  </varlistentry>
	</variablelist>
      </sect3>
      <sect3 id="sect_ref_dataprocessing_dp">
	<title>
	  Parameter group: -DATAPROCESSING (-DP)
	</title>
	<para>
	  Options for controlling some data processing during the assembly.
	</para>
	<variablelist>
	  <varlistentry>
	    <term>
	      <arg>use_read_extension(ure)=<replaceable>on|y[es]|t[rue], off|n[o]|f[alse]</replaceable></arg>
	    </term>
	    <listitem>
	      <para> Default
	      is dependent of the sequencing technology used: <emphasis role="underline">yes</emphasis> 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.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>read_extension_window_length(rewl)=<replaceable>integer &gt; 0</replaceable></arg>
	    </term>
	    <listitem>
	      <para> Default
	      is dependent of the sequencing technology used. Only takes effect when
	      <arg>-DP:ure</arg> (see above) is set to <emphasis role="underline">yes</emphasis>. The read extension
	      routines use a sliding window approach on Smith-Waterman alignments. This
	      parameter defines the window length.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>read_extension_with_maxerrors(rewme)=<replaceable>integer &gt; 0</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		Default is dependent of the sequencing technology used. Only takes effect
		when <arg>-DP:ure</arg> (see above) is set to <emphasis role="underline">yes</emphasis>. 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.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>first_extension_in_pass(feip)=<replaceable>integer &ge; 0</replaceable></arg>
	    </term>
	    <listitem>
	      <para> Default is
	      dependent of the sequencing technology used. Only takes effect when
	      <arg>-DP:ure</arg> (see above) is set to <emphasis role="underline">yes</emphasis>. The read extension
	      routines can be called before assembly and/or after each assembly pass (see
	      <arg>-AS:nop</arg>). This parameter defines the first pass in which the read
	      extension routines are called. The default of <emphasis role="underline">0</emphasis> tells
	      MIRA to extend the reads the first time before the first assembly
	      pass.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>last_extension_in_pass(leip)=<replaceable>integer &ge; 0</replaceable></arg>
	    </term>
	    <listitem>
	      <para> Default is
	      dependent of the sequencing technology used. Only takes effect when
	      <arg>-DP:ure</arg> (see above) is set to <emphasis role="underline">yes</emphasis>. The read extension
	      routines can be called before assembly and/or after each assembly pass (see
	      <arg>-AS:nop</arg>). This parameter defines the last pass in which the read
	      extension routines are called. The default of <emphasis role="underline">0</emphasis> tells
	      MIRA to extend the reads the last time before the first assembly
	      pass.
	      </para>
	    </listitem>
	  </varlistentry>
	</variablelist>
      </sect3>
      <sect3 id="sect_ref_clipping_cl">
	<title>
	  Parameter group: -CLIPPING (-CL)
	</title>
	<para>
	  Controls for clipping options: when and how sequences should be clipped.
	</para>
	<para>
	  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.
	</para>
	<variablelist>
	  <varlistentry>
	    <term>
	      <arg>msvs_gap_size(msvsgs)=<replaceable>integer &ge; 0</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		Default is dependent of the sequencing technology used. Takes
		effect only when loading data from ancillary SSAHA2 or SMALT
		files.
	      </para>
	      <para>
		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 <arg>-CL:msvgsgs</arg> apart.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>msvs_max_front_gap(msvsmfg)=<replaceable>integer &ge; 0</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		Default is dependent of the sequencing technology used. Takes
		effect only when loading data from ancillary SSAHA2 or SMALT
		files.
	      </para>
	      <para>
		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.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>msvs_max_end_gap(msvsmeg)=<replaceable>integer &ge; 0</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		Default is dependent of the sequencing technology used. Takes
		effect only when loading data from ancillary SSAHA2 or SMALT
		files.
	      </para>
	      <para>
		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.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>possible_vector_leftover_clip(pvlc)=<replaceable>on|y[es]|t[rue], off|n[o]|f[alse]</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		Default is dependent of the sequencing technology
		used: <emphasis role="underline">yes</emphasis> for
		Sanger, <emphasis role="underline">no</emphasis> 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.
	      </para>
	      <para>
		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.
	      </para>
	      <para>
		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.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>pvc_maxlenallowed(pvcmla)=<replaceable>integer &ge; 0</replaceable></arg>
	    </term>
	    <listitem>
	      <para> 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.
	      </para>
	      <para>
		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 <emphasis role="bold">NOT</emphasis> performed.
	      </para>
	      <para>
		Setting the value to 0 turns off the threshold, i.e., clips are then always
		performed if a potential vector was found.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>quality_clip(qc)=<replaceable>on|y[es]|t[rue], off|n[o]|f[alse]</replaceable></arg>
	    </term>
	    <listitem>
	      <para> Default is
	      <emphasis role="underline">no</emphasis>. 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 <arg>-DP:ure</arg>
	      is turned on.
	      </para>
	      <para>
		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 <arg>-CL:emrc</arg> and
		<arg>-DP:ure</arg>.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>qc_minimum_quality(qcmq)=<replaceable>integer &ge; 15 and &le; 35</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		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.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>qc_window_length(qcwl)=<replaceable>integer &ge; 10</replaceable></arg>
	    </term>
	    <listitem>
	      <para> Default is
	      dependent of the sequencing technology used. This is the length of a window
	      in bases for the quality clip.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>bad_stretch_quality_clip (bsqc)=<replaceable>on|y[es]|t[rue], off|n[o]|f[alse]</replaceable></arg>
	    </term>
	    <listitem>
	      <para> Default is <emphasis role="underline">no</emphasis>. This
		option allows to clip reads that were not correctly preprocess
		and have unclipped bad quality stretches that might prevent a
		good assembly.
	      </para>
	      <para> 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.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>bsqc_minimum_quality (bsqcmq)=<replaceable>integer &ge; 0</replaceable></arg>
	    </term>
	    <listitem>
	      <para> 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.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>bsqc_window_length (bsqcwl)=<replaceable>integer &ge; 0</replaceable></arg>
	    </term>
	    <listitem>
	      <para> Default is dependent of the
	      sequencing technology used. Defines the length of the window within which
	      the average quality of the bases are computed.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>maskedbases_clip(mbc)=<replaceable>on|y[es]|t[rue], off|n[o]|f[alse]</replaceable></arg>
	    </term>
	    <listitem>
	      <para> 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'.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>mbc_gap_size(mbcgs)=<replaceable>integer &ge; 0</replaceable></arg>
	    </term>
	    <listitem>
	      <para> 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 <arg>-CL:mbcgs</arg> apart.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>mbc_max_front_gap(mbcmfg)=<replaceable>integer &ge; 0</replaceable></arg>
	    </term>
	    <listitem>
	      <para> 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.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>mbc_max_end_gap(mbcmeg)=<replaceable>integer &ge; 0</replaceable></arg>
	    </term>
	    <listitem>
	      <para> 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.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>lowercase_clip_front(lccf)=<replaceable>on|y[es]|t[rue], off|n[o]|f[alse]</replaceable></arg>
	    </term>
	    <listitem>
	      <para> 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.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>lowercase_clip_back(lccb)=<replaceable>on|y[es]|t[rue], off|n[o]|f[alse]</replaceable></arg>
	    </term>
	    <listitem>
	      <para> 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.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>clip_polyat(cpat)=<replaceable>on|y[es]|t[rue], off|n[o]|f[alse]</replaceable></arg>
	    </term>
	    <listitem>
	      <para> Default is
	      <emphasis role="underline">yes</emphasis> for all EST/RNASeq
	      assemblies. Poly-A stretches in forward reads and poly-T
	      stretches in reverse reads get either clipped or tagged here
	      (see <arg>-CL:cpkps</arg> below). The assembler will not use
	      these stretches for finding overlaps, but it will use these to
	      discern and disassemble different 3' UTR endings.
	      </para>
	      <warning>
		Should poly-A / poly-T stretches have been trimmed in
		pre-processing steps before MIRA got the reads, this option
		MUST be switched off.
	      </warning>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>cp_keep_poly_stretch (cpkps)=<replaceable>on|y[es]|t[rue], off|n[o]|f[alse]</replaceable></arg>
	    </term>
	    <listitem>
	      <para> Default is
	      <emphasis role="underline">yes</emphasis> but takes effect only
	      if <arg>-CL:cpat</arg> (see above) is also set to yes.
	      </para>
	      <para>
		Instead of clipping the poly-A / poly-T sequence away, the
		stretch in question in the reads is kept and tagged. The tags
		provide additional information for MIRA to discern between
		different 3' UTR endings and alse a good visual anchor when
		looking at the assembly with different programs.
	      </para>
	      <note>
		One side-effect of this option is that the poly-A / poly-T
		stretch are 'cleaned'. That is, single non-poly A / poly-T
		bases within the stretch are automatically edited to be
		conforming to the surrounding stretch. This is necessary as
		homopolymers are by nature one of the hardest motifs to be
		sequenced correctly by any sequencing technology and one
		frequently gets 'dirty' poly-A sequence from sequencing and
		this interferes heavily with the methods MIRA uses to discern
		repeats.
	      </note>
	      <note>
		Keeping the poly-A sequence is a two-edged sword: on one hand it
		enabled to discern different 3' UTR endings, on the other hand
		it might be that sequencing problems toward the end of reads
		create false-positive different endings. If you find that this
		is the case for your data, just switch off this option: MIRA
		will then simply build the longest possible 3' UTRs.
	      </note>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>cp_min_sequence_len(cpmsl)=<replaceable>integer &gt;
	      0</replaceable></arg>
	    </term>
	    <listitem>
	      <para> Default is
	      <emphasis role="underline">10</emphasis>. Only takes effect
	      when <arg>-CP:cpat</arg> (see above) is set
	      to <emphasis role="underline">yes</emphasis>. Defines the number
	      of 'A' (in forward direction) or 'T' (in reverse direction) must
	      be present to be considered a poly-A sequence stretch.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>cp_max_errors_allowed(cpmea)=<replaceable>integer &gt; 0</replaceable></arg>
	    </term>
	    <listitem>
	      <para> Default is
	      <emphasis role="underline">1</emphasis>. Only takes effect
	      when <arg>-CL:cpat</arg> (see above) is set
	      to <emphasis role="underline">yes</emphasis>. Defines the
	      maximum number of errors allowed in the potential poly-A
	      sequence stretch. The distribution of these errors is not
	      important.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>cp_max_gap_from_end(cpmgfe)=<replaceable>integer &gt; 0</replaceable></arg>
	    </term>
	    <listitem>
	      <para> Default is <emphasis role="underline">9</emphasis>. Only
	      takes effect when <arg>-CL:cpat</arg> (see above) is set
	      to <emphasis role="underline">yes</emphasis>.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 sequence stretch is
	      looked for.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>clip_3ppolybase (c3pp)=<replaceable>on|y[es]|t[rue], off|n[o]|f[alse]</replaceable></arg>
	    </term>
	    <listitem>
	      c3p* options to be described ...
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>clip_known_adaptorsright (ckar)=<replaceable>on|y[es]|t[rue], off|n[o]|f[alse]</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		Default is <emphasis role="underline">yes</emphasis>. Defines
		whether MIRA should search and clip known sequencing technology
		specific sequencing adaptors. MIRA knows adaptors for Illumina
		best, followed by Ion Torrent and some 454 adaptors.
	      </para>
	      <para>
		As the list of known adaptors changes quite frequently, the
		best place to get a list of known adaptors by MIRA is by
		looking at the text files in the program
		sources: <filename>src/mira/adaptorsforclip.*.xxd</filename>.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>ensure_minimum_left_clip(emlc)=<replaceable>on|y[es]|t[rue], off|n[o]|f[alse]</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		Default is dependent of the sequencing technology used. If on, ensures a
		minimum left clip on each read according to the parameters in
		<arg>-CL:mlcr:smlc</arg>
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>minimum_left_clip_required(mlcr)=<replaceable>integer &ge; 0</replaceable></arg>
	    </term>
	    <listitem>
	      <para> Default
	      is dependent of the sequencing technology used. If <arg>-CL:emlc</arg> is
	      on, checks whether there is a left clip which length is at least the one
	      specified here.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>set_minimum_left_clip(smlc)=<replaceable>integer &ge; 0</replaceable></arg>
	    </term>
	    <listitem>
	      <para> Default is
	      dependent of the sequencing technology used. If <arg>-CL:emlc</arg> is on
	      and actual left clip is &lt; <arg>-CL:mlcr</arg>, set left clip of read to
	      the value given here.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>ensure_minimum_right_clip(emrc)=<replaceable>on|y[es]|t[rue], off|n[o]|f[alse]</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		Default is dependent of the sequencing technology used. If on, ensures a
		minimum right clip on each read according to the parameters in
		<arg>-CL:mrcr:smrc</arg>
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>minimum_right_clip_required(mrcr)=<replaceable>integer &ge; 0</replaceable></arg>
	    </term>
	    <listitem>
	      <para> Default
	      is dependent of the sequencing technology used. If <arg>-CL:emrc</arg> is
	      on, checks whether there is a right clip which length is at least the one
	      specified here.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>set_minimum_right_clip(smrc)=<replaceable>integer &ge; 0</replaceable></arg>
	    </term>
	    <listitem>
	      <para> Default is
	      dependent of the sequencing technology used. If <arg>-CL:emrc</arg> is on
	      and actual right clip is &lt; <arg>-CL:mrcr</arg>, set the length of the
	      right clip of read to the value given here.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>gb_chimeradetectionclip(gbcdc)=<replaceable>on|y[es]|t[rue], off|n[o]|f[alse]</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		Default is <emphasis role="underline">yes</emphasis> for all jobs.
	      </para>
	      <para>
		Very safe chimera detection, should have no false
		positives. For repetitive data, a low number of false
		negatives is possible.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>kmerjunk_detection(kjd)=<replaceable>on|y[es]|t[rue], off|n[o]|f[alse]</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		Default is currently <emphasis role="underline">yes</emphasis>.
	      </para>
	      <para>
		Reads that look "fishy" are marked as potentially
		chimeric. This mark leads either to a read being completely
		killed or to a read being included into a contig only if no
		other possibility remains.
	      </para>
	      <para>
		It is currently suggested to leave this parameter switched on
		and to fine-tune via <arg>-CL:kjck</arg> (see below).
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>kmerjunk_completekill(kjck)=<replaceable>on|y[es]|t[rue], off|n[o]|f[alse]</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		Default is currently <emphasis role="underline">no</emphasis>
		for genome assemblies and <emphasis
		role="underline">yes</emphasis> for EST/RNASeq assemblies.
	      </para>
	      <para>
		If set to yes, reads marked as junk (see above) are completely
		removed from an assembly. If set to no, reads are not removed
		but included only into a contig as a very last resort.
	      </para>
	      <para>
		Having reads killed guarantees assemblies of extremely high
		quality containing virtually no missassembly due to chimeric
		sequencing errors. The downside is that, computationally,
		there is no difference between junk and stretches with correct
		but very low coverage data (generally &lt; 3x coverage). It's
		up to you to decide what is more important: total accuracy or
		longer contigs.
	      </para>
	      <note>
		<para>
		  As a rule of thumb: I set this to no for genome assemblies
		  with at least medium average coverage (&ge; 20-30x) as MIRA
		  does a pretty good job to incorporate these reads so late in
		  an assembly that they do not lead to misassemblies. In
		  transcript assemblies I set this to yes as there is a high
		  chance that high coverage transcripts could be extended via
		  chimeric reads.
		</para>
		<para>
		  With this in mind: deciding for metagenome assemblies would
		  be really difficult though. It probably depends on what you
		  need the data for.
		</para>
	      </note>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>propose_end_clips(pec)=<replaceable>on|y[es]|t[rue], off|n[o]|f[alse]</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		Default is is dependent on --job quality: currently <emphasis
		role="underline">yes</emphasis> for all genome assemblies.
		Switched off for EST assemblies (but one might want to switch
		it on sometimes).
	      </para>
	      <para>
		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.
	      </para>
	      <warning>
		Extremely effective, but should NOT be used for very low
		coverage genomic data, or for EST projects if one wants to
		retain the rareest transcripts.
	      </warning>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>handle_solexa_ggcxg_problem(pechsgp)=<replaceable>on|y[es]|t[rue],
	      off|n[o]|f[alse]</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		Default is is dependent <emphasis
		role="underline">yes</emphasis>.
	      </para>
	      <para>
		Solexa data has a pretty awful problem with in some reads when
		a <literal>GGCxG</literal> 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.
	      </para>
	      <para>
		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.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>pec_kmer_size(peckms)=<replaceable>10 &le; integer &le; 32</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		Default is is dependent on technology and quality in the --job
		switch: usually
		between <emphasis role="underline">17</emphasis>
		and <emphasis role="underline">21</emphasis> for Sanger,
		higher for 454 (up to
		<emphasis role="underline">27</emphasis>) and highest for
		Solexa (<emphasis role="underline">31</emphasis>). Ion Torrent
		has at the moment <emphasis role="underline">17</emphasis>,
		but this may change in the future to somewhat higher values.
	      </para>
	      <para>
		This parameter defines the minimum number of bases at each end
		of a read that should be free of any sequencing errors.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>pec_minimum_kmer_forward_reverse(pmkfr)=<replaceable>integer &ge; 0</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		Default is is dependent on technology and quality in the --job
		switch: usually
		between <emphasis role="underline">1</emphasis>
		and <emphasis role="underline">3</emphasis>
		when <arg>-CL:pec=yes</arg>.
	      </para>
	      <para>
		This parameter defines the minimum number of occurrence of a
		kmer at each end of a read that should be free of any
		sequencing errors.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>rare_kmer_mask(rkm)=<replaceable>on|y[es]|t[rue],
	      off|n[o]|f[alse]</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		Default is is dependent on --job switch: currently
		it's <emphasis role="underline">yes</emphasis> for Solexa data
		and <emphasis role="underline">no</emphasis> otherwise.  If
		this parameter is active, MIRA will completely mask with 'X'
		those parts of a read which have kmer occurrence (in forward
		and reverse direction) less than the value specified
		via <arg>-CL:pmkfr</arg>.
	      </para>
	      <para>
		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 or very lowly covered genome parts with an
		occurrence less than the given value will also be masked
		out. However, Illumina gives so much data that this is almost
		never the case.
	      </para>
	      <note>
		This works only if <arg>-CL:pec</arg> is active.
	      </note>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>search_phix174(spx174)=<replaceable>on|y[es]|t[rue],
	      off|n[o]|f[alse]</replaceable></arg>
	    </term>
	    <listitem>
	      <para> Default is <emphasis>on</emphasis> for Illumina data, off
	      otherwise.
	      </para>
	      <para>
		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.
	      </para>
	      <para>
		If it remains in the sequenced data, it has to be
		seen as a contaminant for projects working with organisms
		which should not contain the PhiX 174 phage.
	      </para>
	      <note>
		However, PhiX may be part of some genome sequences
		(enterobacteria). In these cases, the PhiX174 search will
		report genuine genome data.
	      </note>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>filter_phix174(fpx174)=<replaceable>on|y[es]|t[rue],
	      off|n[o]|f[alse]</replaceable></arg>
	    </term>
	    <listitem>
	      <para> Default is <emphasis>on</emphasis> for Illumina data in
	      EST (RNASeq) assemblies, off otherwise.
	      </para>
	      <para>
		If <arg>-CL:spx174</arg> is on and <arg>-CL:fpx174</arg> also,
		MIRA will filter out as contaminants all reads which have
		PhiX174 sequence recognised.
	      </para>
	      <para>
		The default value of having the filtering on only for Illumina
		EST (RNASeq) data is a conservative approach: the overwhelming
		majority of RNASeq data will indeed not sequence some
		enterobacteria, so having PhiX174 containing reads thrown out
		is indeed a valid move. For genomes however, MIRA currently is
		cautious and will not filter these reads by default.
	      </para>
	      <warning>
		However, PhiX may be part of some genome sequences
		(enterobacteria). In these cases, the PhiX174 filter will
		remove reads from valid genome or expression data.
	      </warning>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>filter_rrna(frrna)=<replaceable>on|y[es]|t[rue],
	      off|n[o]|f[alse]</replaceable></arg>
	    </term>
	    <listitem>
	      <para> Default is <emphasis>on</emphasis> for EST (RNASeq)
	      assemblies, off otherwise.
	      </para>
	      <para>
		If enabled, MIRA will filter out (and not assemble) all reads
		(or pairs, see below) it recognises as being rRNA or
		rDNA. This is useful to reduce computing time on data sets
		which contain large contamination of rRNA which were not
		filtered away in wet lab.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>filter_rrna_pairs(frrnap)=<replaceable>on|y[es]|t[rue],
	      off|n[o]|f[alse]</replaceable></arg>
	    </term>
	    <listitem>
	      <para> Default is <emphasis>on</emphasis> for EST (RNASeq)
	      assemblies, off otherwise.
	      </para>
	      <para>
		If enabled together with <arg>-CL:frrna</arg>, MIRA will
		filter out (and not assemble) all reads pairs where at least
		one of the reads is recognised as being rRNA or rDNA.
	      </para>
	      <para>
		This option is useful to also catch less conserved parts of
		rRNA transcribed like, e.g. the internal transcribed spacers
		(ITS) in eukaryotic data.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>filter_rrna_numkmers(frrnank)=<replaceable>integer &gt; 0
	      </replaceable></arg>
	    </term>
	    <listitem>
	      <para> Default is <emphasis>20</emphasis>.
	      </para>
	      <para>
		The rRNA recognition in MIRA works with a precompiled set of
		preserved rRNA kmers, at the time of this writing with
		21-mers. To allow for specific recognition, the rRNA filtering
		process expects to find at least this number of kmers per read
		before identifying it as rRNA.
	      </para>
	      <para>
		To increase sensitivity (and at the same time risk more false
		positives): reduce this parameter. To increase specificity
		(and at the same time risk more reads not being recognised):
		increase this parameter.
	      </para>
	      <para>
		The default parameters together with the default database seem
		to work pretty well and this is expected to work for all but
		the most exotic rRNA containing organisms.
	      </para>
	    </listitem>
	  </varlistentry>
	</variablelist>
      </sect3>
      <sect3 id="sect_ref_skim_sk">
	<title>
	  Parameter group: -SKIM (-SK)
	</title>
	<para>
	  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 kmer 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).
	</para>
	<para>
	  The major differences of SKIM3 and SSAHA are:
	</para>
	<orderedlist>
	  <listitem>
	    <para>
	      the word length <emphasis>n</emphasis> of a kmer (hash) in
	      SSAHA2 must be &lt; 15, but can be up to 32 bases in 64 bit
	      versions of MIRA &lt; 4.0.2 and lower, and up to 256 bases for
	      higher versions of MIRA.
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      SKIM3 uses a maximum fixed amount of RAM that is independent of
	      the word size. E.g., SSAHA would need 4 <emphasis
	      role="underline">exabyte</emphasis> to work with word length of
	      30 bases ... SKIM3 just takes a couple of hundred MB.
	    </para>
	  </listitem>
	</orderedlist>
	<para>
	  The parameters for SKIM3:
	</para>
	<variablelist>
	  <varlistentry>
	    <term>
	      <arg>number_of_threads(not)=<replaceable>integer &ge; 1</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		Number of threads used in SKIM, default is <emphasis
		role="underline">2</emphasis>. 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%.
	      </para>
	      <para>
		Although the main data structures are shared between the
		threads, there's some additional memory needed for each
		thread.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>also_compute_reverse_complements(acrc)=<replaceable>on|y[es]|t[rue], off|n[o]|f[alse]</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		Default is <emphasis role="underline">on</emphasis>. Defines
		whether SKIM searches for matches only in forward/forward
		direction or whether it also looks for forward/reverse
		direction.
	      </para>
	      <para>
		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.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>kmer_size(kms)=<replaceable>10 &lt; integer &le; 256</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		Defaults are dependent on "--job" switch and sequencing
		technologies used.
	      </para>
	      <para>
		Controls the number of consecutive bases
		<emphasis>n</emphasis> which are used as a kmer. The
		higher the value, the faster the search. The lower the value,
		the slower the search and the more weak matches are found.
	      </para>
	      <para>
		A secondary effect of this parameter is the estimation of MIRA
		on whether stretches within a read sequence are repetitive or
		not. Large values of <arg>-SK:kms</arg> allow a better
		distinction between "almost identical" repeats early in the
		assembly process and, given enough coverage, generally lead to
		less and longer contigs.
	      </para>
	      <note>
		This parameter gets overriden by the one-stop-shop parameter
		<arg>-AS:kms</arg> which determines number of passes and kmer
		size to use in each pass.
	      </note>
	      <warning>
		For de-novo assemblies, values below 15 are not
		recommended. For mapping assemblies, values below 10 should
		not be used.
	      </warning>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>kmer_save_stepping(kss)=<replaceable>integer &ge; 1</replaceable></arg>
	    </term>
	    <listitem>
	      <para> Default is
	      <emphasis role="underline">1</emphasis>. This is a parameter
	      controlling the stepping increment <emphasis>s</emphasis> with which kmers are
	      generated. This allows for more or less fine grained search as
	      matches are found with at least <emphasis>n+s</emphasis> (see <arg>-SK:kms</arg>)
	      equal bases. The higher the value, the faster the search. The
	      lower the value, the more weak matches are found.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>percent_required(pr)=<replaceable>integer &ge; 1</replaceable></arg>
	    </term>
	    <listitem>
	      <para> 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).
	      </para>
	      <para>
		Note: most of the time it makes sense to keep this parameter
		in sync with <arg>-AL:mrs</arg>.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>maxhits_perread(mhpr)=<replaceable>integer &ge; 1</replaceable></arg>
	    </term>
	    <listitem>
	      <para> Default is
	      <emphasis role="underline">2000</emphasis>. Controls the maximum
	      number of possible hits one read can maximally transport to the
	      overlap edge reduction phase. If more potential hits are found,
	      only the best ones are taken.
	      </para>
	      <para>
		In the pre-2.9.x series, this was an important option for
		tackling projects which contain <emphasis>extreme</emphasis>
		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.
	      </para>
	      <para>
		As the assembly increases in passes (<arg>-AS:nop</arg>),
		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.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>filter_megahubs(fmh)=<replaceable>on|y[es]|t[rue], off|n[o]|f[alse]</replaceable></arg>
	    </term>
	    <listitem>
	      <para> Default is <emphasis
	      role="underline">yes</emphasis>. Defines whether megahubs (reads
	      with extremely many overlaps to other reads) are filtered.
	      See also <arg>-SK:mhc:mmhr</arg>.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>megahub_cap(mhc)=<replaceable>integer &gt; 0</replaceable></arg>
	    </term>
	    <listitem>
	      <para> Default is <emphasis
	      role="underline">150000</emphasis>. Defines the number of kmer
	      overlaps a read may have before it is categorised as megahub.
	      </para>
	      <note>
		You basically don't want to mess with this one. Except for
		assemblies containing very long reads. Rule of thumb: you
		might want to multiply the 150k value by n where n is the
		average read length divided by 2000. Don't overdo, max n at 15
		or so.
	      </note>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>max_megahub_ratio(mmhr)=<replaceable>integer &ge; 0</replaceable></arg>
	    </term>
	    <listitem>
	      <para> Default is
	      <emphasis role="underline">0</emphasis>. If the number of reads
	      identified as megahubs exceeds the allowed ratio, MIRA will
	      abort.
	      </para>
	      <para>
		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 <arg>-KS:mnr</arg> not on.
	      </para>
	      <para>
		EST project however, especially from non-normalised libraries,
		will very probably contain megahubs. In this case, you might
		want to think about masking, see <arg>-KS:mnr</arg>.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>sw_check_on_backbones(swcob)=<replaceable>on|y[es]|t[rue], off|n[o]|f[alse]</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		Default is currently (3.4.0) <emphasis
		role="underline">yes</emphasis> 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.
	      </para>
	      <para>
		You will want to set this option to <emphasis
		role="underline">yes</emphasis> whenever your reference
		sequence contains more complex or numerous repeats and your
		data has SNPs in those areas.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>max_kmers_in_memory(mkim)=<replaceable>integer &ge; 100000</replaceable></arg>
	    </term>
	    <listitem>
	      <para> Default is
	      <emphasis role="underline">15000000</emphasis>. 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.
	      </para>
	      <para>
		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.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>memcap_hitreduction(mchr)=<replaceable>integer &ge; 10</replaceable></arg>
	    </term>
	    <listitem>
	      <para> Default is
	      <emphasis role="underline">1024</emphasis>, <emphasis role="underline">2048</emphasis>
	      when Solexa sequences are used. Maximum memory used (in MiB)
	      during the reduction of skim hits.
	      </para>
	      <para>
		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.
	      </para>
	      <para>
		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).
	      </para>
	    </listitem>
	  </varlistentry>
	</variablelist>
	<para>
	</para>
      </sect3>
      <sect3 id="sect_ref_hashstatistics_hs">
	<title>
	  Parameter group: -KMERSTATISTICS (-KS)
	</title>
	<para>
	  Hash statistics (nowadays 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.
	</para>
	<para>
	  The length of the kmer is defined via <arg>-SK:kms</arg>
	  or <arg>-AS:kms</arg> while the parameters in this section define
	  the boundaries of the different repeat levels.
	</para>
	<para>
	  A more in-depth description on kmer statistics is given in the
	  sections <emphasis>Introduction to 'masking'</emphasis>
	  and <emphasis>How does 'nasty repeat' masking work?</emphasis> in
	  the chapter dealing with the assembly of hard projects.
	</para>
	<variablelist>
	  <varlistentry>
	    <term>
	      <arg>freq_est_minnormal(fenn)=<replaceable>float &gt; 0</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		During kmer statistics analysis, MIRA will estimate how repetitive parts
		of reads are. Parts which are occurring less than
		<arg>-KS:fenn</arg> times the average occurrence will be tagged
		with a HAF2 (less than average) tag.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>freq_est_maxnormal(fexn)=<replaceable>float &gt; 0</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		During kmer statistics analysis, MIRA will estimate how repetitive parts
		of reads are. Parts which are occurring more than
		<arg>-KS:fenn</arg> but less than <arg>-KS:fexn</arg> times
		the average occurrence will be tagged with a HAF3 (normal) tag.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>freq_est_repeat(fer)=<replaceable>float &gt; 0</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		During kmer statistics analysis, MIRA will estimate how repetitive parts
		of reads are. Parts which are occurring more than
		<arg>-KS:fexn</arg> but less than <arg>-KS:fer</arg> times
		the average occurrence will be tagged with a HAF4 (above average) tag.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>freq_est_heavyrepeat(fehr)=<replaceable>float &gt; 0</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		During kmer statistics analysis, MIRA will estimate how repetitive parts
		of reads are. Parts which are occurring more than
		<arg>-KS:fer</arg> but less than <arg>-KS:fehr</arg> times
		the average occurrence will be tagged with a HAF5 (repeat) tag.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>freq_est_crazyrepeat(fecr)=<replaceable>float &gt; 0</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		During kmer statistics analysis, MIRA will estimate how repetitive parts
		of reads are. Parts which are occurring more than
		<arg>-KS:fehr</arg> but less than <arg>-KS:fecr</arg> times
		the average occurrence will be tagged with a HAF6 (heavy
		repeat) tag. Parts which are occurring more than
		<arg>-KS:fecr</arg> but less than <arg>-KS:nrr</arg> times the
		average occurrence will be tagged with a HAF7 (crazy repeat)
		tag.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>mask_nasty_repeats(mnr)=<replaceable>on|y[es]|t[rue], off|n[o]|f[alse]</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		Default is dependent on --job
		type: <emphasis role="underline">yes</emphasis> for
		de-novo, <emphasis role="underline">no</emphasis> for mapping.
	      </para>
	      <para>
		Tells MIRA to tag (during the kmer statistics phase) read
		subsequences of length <arg>-SK:kms</arg> 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
		<arg>-KS:nrr</arg> or <arg>-KS:nrc</arg>, the action MIRA
		should take when encountering those sequences is defined
		by <arg>-KS:ldn</arg> (see below).
	      </para>
	      <para>
		When not using lossless digital normalisation
		(<arg>-KS:ldn</arg>), 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.
	      </para>
	      <para>
		This option is extremely useful for assembly of larger
		projects (fungi-size) with a high percentage of repeats.
	      </para>
	      <note>
		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.
	      </note>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>nasty_repeat_ratio(nrr)=<replaceable>integer &ge; 2</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		Default is depending on the <arg>--job=...</arg>
		parameters. Normally it's high (around 100) for genome
		assemblies, but much lower (20 or less) for EST assemblies.
	      </para>
	      <para>
		Sets the ratio from which on subsequences are considered nasty
		and hidden from the kmer statistics overlapper with a
		<emphasis>MNRr</emphasis> tag. E.g.: A value of 10 means: mask all
		k-mers of <arg>-SK:kms</arg> length which are occurring more
		than 10 times more often than the average of the whole project.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>nasty_repeat_coverage(nrc)=<replaceable>integer &ge; 0</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		Default is depending on the <arg>--job=...</arg>
		parameters: <emphasis role="underline">0</emphasis> for genome
		assemblies, <emphasis role="underline">200</emphasis> for EST assemblies.
	      </para>
	      <para>
		Closely related to the <arg>-KS:nrr</arg> 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 <arg>-KS:nrr</arg> if the calculated value of nrr is
		larger that the absolute value given here. A value of 0
		de-activates this parameter.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>lossless_digital_normalisation(ldn)=<replaceable>on|y[es]|t[rue], off|n[o]|f[alse]</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		Default is dependent on --job
		type: <emphasis role="underline">yes</emphasis> for denovo
		EST/RNAseq assembly, <emphasis role="underline">no</emphasis>
		otherwise.
	      </para>
	      <para>
		Tells MIRA how on whether or not digitally normalising reads containing nasty repeats
		when <arg>-KS:mnr</arg> is active.
	      </para>
	      <para>
		When set to <emphasis>yes</emphasis>, 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.
	      </para>
	      <para>
		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".
	      </para>
	      <para>
		This option is extremely useful for non-normalised EST /
		RNASeq projects, to get at least the sequence of
		overrepresented transcripts assembled even if the coverage
		values then cannot be interpreted as expression values
		anymore.
	      </para>
	      <note>
		The lossless digital normalisation will be applied as soon as
		the kmer size of the active pass (see <arg>-AS:kms</arg>)
		reaches a size of at least 50 or, at the latest, in the second
		to last pass.
	      </note>
	      <note>
		Once digital normalisation has been applied, the
		parameters <arg>-KS:nrr</arg> and <arg>-KS:nrc</arg> do not
		take effect anymore.
	      </note>
	      <warning>
		The effect of lossless digital normalisation on genome data
		has not been studied sufficiently by me to approve it for
		genomes. Use with care in genome assemblies.
	      </warning>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>repeatlevel_in_infofile(rliif)=<replaceable>integer; 0, 5-8</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		Default is <emphasis role="underline">6</emphasis>. Sets the
		minimum level of the HAF tags from which on MIRA will report
		tentatively repetitive sequence in the
		<filename>*_info_readrepeats.lst</filename> file of the info
		directory.
	      </para>
	      <para>
		A value of <emphasis role="underline">0</emphasis> means
		"switched off". The default value of <emphasis
		role="underline">6</emphasis> means all subsequences tagged
		with <emphasis>HAF6</emphasis>, <emphasis>HAF7</emphasis> and
		<emphasis>MNRr</emphasis> will be logged. If you, e.g., only
		wanted MNRr logged, you'd use <emphasis
		role="underline">8</emphasis> as parameter value.
	      </para>
	      <para>
		See also <arg>-KS:fenn:fexn:fer:fehr:mnr:nrr</arg> to set the
		different levels for the <emphasis>HAF</emphasis> and
		<emphasis>MNRr</emphasis> tags.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>memory_to_use(mtu)=<replaceable>integer</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		Default is <emphasis role="underline">75</emphasis>. Defines
		the memory MIRA can use to compute kmer statistics.
	      </para>
	      <para>
		A value of <emphasis role="underline">&gt;100</emphasis> is
		interpreted as absolute value in megabyte. E.g., 16384 = 16384
		megabyte = 16 gigabyte.
	      </para>
	      <para>
		A value of <emphasis role="underline">0 &le; x &le;100</emphasis> is
		interpreted as relative value of free memory at the time of
		computation. E.g.: for a value of 75% and 10 gigabyte of free
		memory, it will use 7.5 gigabyte.
	      </para>
	      <note>
		The minimum amount of memory this algorithm will use is 512 Mib
		on 32 bit systems and 2 Gib on 64 bit systems.
	      </note>
	    </listitem>
	  </varlistentry>
	</variablelist>
      </sect3>
      <sect3 id="sect_ref_align_al">
	<title>
	  Parameter group: -ALIGN (-AL)
	</title>
	<para>
	  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.
	</para>
	<para>
	  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.
	</para>
	<variablelist>
	  <varlistentry>
	    <term>
	      <arg>bandwidth_in_percent(bip)=<replaceable>integer &gt; 0 and &le;100</replaceable></arg>
	    </term>
	    <listitem>
	      <para> 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:
	      <emphasis>increase</emphasis>: will find more non-optimal alignments, but will also
	      increase SW runtime between linear and \Circum2.  <emphasis>decrease</emphasis>: the other
	      way round, might miss a few bad alignments but gaining speed.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>bandwidth_min(bmin)=<replaceable>integer &gt; 0</replaceable></arg>
	    </term>
	    <listitem>
	      <para> Default is dependent of the
	      sequencing technology used. Minimum bandwidth in bases to each side.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>bandwidth_max(bmax)=<replaceable>integer &gt; 0</replaceable></arg>
	    </term>
	    <listitem>
	      <para> Default is dependent of the
	      sequencing technology used. Maximum bandwidth in bases to each side.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>min_overlap(mo)=<replaceable>integer &gt; 0</replaceable></arg>
	    </term>
	    <listitem>
	      <para> Default is dependent of the
	      sequencing technology used. Minimum number of overlapping bases needed in an
	      alignment of two sequences to be accepted.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>min_score(ms)=<replaceable>integer &gt; 0</replaceable></arg>
	    </term>
	    <listitem>
	      <para> 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).
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>min_relative_score(mrs)=<replaceable>integer &gt; 0 and &le;100</replaceable></arg>
	    </term>
	    <listitem>
	      <para> 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.
	      </para>
	      <para>
		Note: most of the time it makes sense to keep this parameter
		in sync with
		<arg>-SK:pr</arg>.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>solexa_hack_max_errors(shme)=<replaceable>integer &gt; -1</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		Currently a hack just for Solexa/Illumina data.
	      </para>
	      <para>
		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 result is usually a much
		better mapping in areas with larger discrepancies between
		reference sequence and mapped data. Note that the mapping
		process takes longer if this value is unequal to 0 as MIRA
		will use iterative mapping which involves a certain amount of
		trial and error.
	      </para>
	      <para>
		The default value of <emphasis role="underline">-1</emphasis>
		lets MIRA choose this value automatically. It sets it to 15%
		of the average Illumina read lengths loaded.
	      </para>
	      <para>
		A value of <emphasis role="underline">0</emphasis> switches of
		this functionality, leading to a much faster mapping
		process. Useful when mapping expression data where coverage
		values may be more important than the best possible alignment.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>extra_gap_penalty(egp)=<replaceable>on|y[es]|t[rue], off|n[o]|f[alse]</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		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.
	      </para>
	      <para>
		When in doubt, set it
		to <emphasis role="underline">yes</emphasis> for EST projects
		and de-novo genome assembly, set it
		to <emphasis role="underline">no</emphasis> for assembly of
		closely related strains (assembly against a backbone).
	      </para>
	      <para>
		When set to <emphasis role="underline">no</emphasis>, it is
		recommended to have <arg>-CO:amgb</arg>
		and <arg>-CO:amgbemc</arg> both set to yes.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>egp_level(egpl)=<replaceable>comma separated list of integer &ge; 0 and &le; 100</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		Default is dependent of the sequencing technology and job
		used. Has no effect if extra_gap_penalty is off.
	      </para>
	      <para>
		...
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>egp_level(megpp)=<replaceable>0 &le; integer &le; 100</replaceable></arg>
	    </term>
	    <listitem>
	      <para> Default is
	      <emphasis role="underline">100</emphasis>. Has no effect if
	      extra_gap_penalty is off. Defines the maximum extra penalty in
	      percent applied to 'long' gaps.
	      <!--%\item[\OptArg{extra\_mismatch\_penalty(emp)=}{on$|$yes$|$1, off$|$no$|$0}]-->
	      <!--%  Default is \underline{yes}. Defines whether or not to reject alignments-->
	      <!--%  containing long stretches of mismatches. Setting this to 'yes' might help in-->
	      <!--%  projects with frequent repeats. \\ Also very useful in EST projects to-->
	      <!--%  prevent the assembly of different splice variants.-->
	      <!--%\item[\OptArg{emp\_windowlen(empwl)=}{integer$>$0}] Default is \underline{30}.-->
	      <!--%  Has no effect if extra\_mismatch\_penalty is off. Defines the length of the-->
	      <!--%  window of bases that is looked for to contain too many mismatches.-->
	      <!--%\item[\OptArg{emp\_maxmitches(empmm)=}{integer$>$0}] Default is-->
	      <!--%  \underline{15}.  Has no effect if extra\_mismatch\_penalty is off. Defines-->
	      <!--%  how many errors must occur in the window before an alignment is rejected.-->
	      </para>
	    </listitem>
	  </varlistentry>
	</variablelist>
	<para>
	</para>
      </sect3>
      <sect3 id="sect_ref_contig_co">
	<title>
	  Parameter group: -CONTIG (-CO)
	</title>
	<para>
	  The contig options control the behaviour of the contig objects.
	</para>
	<variablelist>
	  <varlistentry>
	    <term>
	      <arg>name_prefix(np)=<replaceable>string</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		Default is
		<emphasis role="underline">&lt;projectname&gt;</emphasis>. Contigs
		will have this string prepended to their names. Normally,
		the <arg>project=</arg> line in the manifest will set this.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>reject_on_drop_in_relscore(rodirs)=<replaceable>integer &ge; 0 and &le;100</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		Default is dependent of the sequencing technology used.
	      </para>
	      <para>
		When adding reads to a contig, reject the reads if the drop in
		the minimum relative score of the alignment of the current
		consensus and the new read is &gt; the expected value
		calculated during the alignment phase. Lower values mean
		stricter checking.
	      </para>
	      <para>
		This value is doubled should a read be entered that has an
		assembled template partner (a read pair) at the right distance
		in the current contig.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>cmin_relative_score(cmrs)=<replaceable>integer &ge; -1 and &le;100</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		Default is <emphasis role="underline">-1</emphasis>. Works
		similarly to <arg>-AL:mrs</arg>, but during contig
		construction phase instead of read vs read alignment phase:
		describes the min % of matching between a read being added to
		a contig and the current contig consensus.
	      </para>
	      <para>
		If value is set to -1, then the value of <arg>-AL:mrs</arg> is used.
	      </para>
	      <para>
		Note: most of the time it makes sense to keep this parameter
		at -1. Else have it at
		approximately <emphasis><arg>-AL:mrs</arg>-10</emphasis> or
		switch it completely off via 0.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>mark_repeats(mr)=<replaceable>on|y[es]|t[rue], off|n[o]|f[alse]</replaceable></arg>
	    </term>
	    <listitem>
	      <para> Default is
	      <emphasis role="underline">yes</emphasis>. One of the most important switches in MIRA: if set to
	      <emphasis role="underline">yes</emphasis>, 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.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>only_in_result(mroir)=<replaceable>on|y[es]|t[rue], off|n[o]|f[alse]</replaceable></arg>
	    </term>
	    <listitem>
	      <para> Default is <emphasis role="underline">no</emphasis>. Only
	      takes effect when <arg>-CO:mr</arg> (see above) is set
	      to <emphasis role="underline">yes</emphasis>. If set
	      to <emphasis role="underline">yes</emphasis>, 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.
	      </para>
	      <para>
		This switch is useful in some (rare) cases of mapping assembly.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>assume_snp_instead_repeat(asir)=<replaceable>on|y[es]|t[rue], off|n[o]|f[alse]</replaceable></arg>
	    </term>
	    <listitem>
	      <para> Default is <emphasis role="underline">no</emphasis>.
	      Only takes effect when <arg>-CO:mr</arg> (see above) is set to
	      <emphasis role="underline">yes</emphasis>, effect is also
	      dependent on the fact whether strain data (see
	      -<arg>-SB:lsd</arg>) 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 <emphasis role="underline">yes</emphasis>, conflict within a
	      strain are also marked as SNP.
	      </para>
	      <para>
		This switch is mainly used in assemblies of ESTs, it should
		not be set for genomic assembly.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>min_reads_per_group(mrpg)=<replaceable>integer &ge; 2</replaceable></arg>
	    </term>
	    <listitem>
	      <para> Default is
	      dependent of the sequencing technology used. Only takes effect when
	      <arg>-CO:mr</arg> (see above) is set
	      to <emphasis role="underline">yes</emphasis>. 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 <arg>-CO:mgqrt</arg>)
	      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).
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>min_neighbour_qual (mnq)=<replaceable>integer &ge;
	      10</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		Default is dependent of the sequencing technology used. Takes
		only effect when <arg>-CO:mr</arg> is set
		to <emphasis role="underline">yes</emphasis>. 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.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>min_groupqual_for_rmb_tagging(mgqrt)=<replaceable>integer &ge; 25</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		Default is dependent of the sequencing technology used. Takes
		only effect when <arg>-CO:mr</arg> is set
		to <emphasis role="underline">yes</emphasis>. 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.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>min_coverage_percentage(mcp)=<replaceable>0 &lt; integer &le; 100</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		Default is currently <emphasis
		role="underline">10</emphasis>. Used to reduce the number of
		IUPAC bases due to non-random PCR artefacts or sequencing
		errors in very high coverage areas (e.g. Illumina &ge;
		80). Once the most probable base has been determined,
		<arg>-CO:mcp</arg> defines the minimum percentage (calculated
		from the most probable base) the coverage of alternative bases
		must have to be considered for consensus. E.g.: with mcp=10
		and the most probable base having a coverage of 200x, other
		bases must have a coverage of 20x.
	      </para>
	      <para>
		Drawback is that valid low frequency variants will not show up
		anymore as IUPAC in the FASTA.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>endread_mark_exclusion_area(emea)=<replaceable>integer &ge; 0</replaceable></arg>
	    </term>
	    <listitem>
	      <para> Default is dependent of the sequencing technology
	      used. Takes only effect when <arg>-CO:mr</arg> is set to
	      <emphasis role="underline">yes</emphasis>. 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.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>emea_set1_on_clipping_pec(emeas1clpec)=<replaceable>on|y[es]|t[rue],
	      off|n[o]|f[alse]</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		Default is <emphasis role="underline">yes</emphasis>. When
		<arg>-CL:pec</arg> is set, the end-read exclusion area can be
		considerably reduced. Setting this parameter will
		automatically do this.
	      </para>
	      <note>
		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.
	      </note>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>also_mark_gap_bases(amgb)=<replaceable>on|y[es]|t[rue], off|n[o]|f[alse]</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		Default is dependent of the sequencing technology
		used. Determines whether columns containing gap bases (indels)
		are also tagged.
	      </para>
	      <para>
		Note: it is strongly recommended to not set this to 'yes' for
		454 type data.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>also_mark_gap_bases_even_multicolumn(amgbemc)=<replaceable>on|y[es]|t[rue],
	      off|n[o]|f[alse]</replaceable></arg>
	    </term>
	    <listitem>
	      <para> Default is <emphasis role="underline">yes</emphasis>.
	      Takes effect only when <arg>-CO:amgb</arg> is set to
	      <emphasis role="underline">yes</emphasis>. Determines whether multiple columns containing gap bases
	      (indels) are also tagged.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>also_mark_gap_bases_need_both_strands(amgbnbs)=<replaceable>on|y[es]|t[rue], off|n[o]|f[alse]</replaceable></arg>
	    </term>
	    <listitem>
	      <para> Default is <emphasis role="underline">yes</emphasis>.  Takes effect only when
	      <arg>-CO:amgb</arg> is set to <emphasis role="underline">yes</emphasis>. Determines whether both for
	      tagging columns containing gap bases, both strands.need to have a gap.
	      Setting this to <emphasis role="underline">no</emphasis> is not recommended except when working in
	      desperately low coverage situations.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>force_nonIUPACconsensus_perseqtype(fnic)=<replaceable>on|y[es]|t[rue], off|n[o]|f[alse]</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		Default is <emphasis role="underline">no</emphasis> for
		de-novo genome assemblies, yes for all others. If set to
		<emphasis role="underline">yes</emphasis>, 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.
	      </para>
	      <para>
		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 <emphasis role="bold">suggested</emphasis> to leave this
		option to <emphasis role="underline">no</emphasis> 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.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>merge_short_reads(msr)=<replaceable>on|y[es]|t[rue], off|n[o]|f[alse]</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		Default is <emphasis role="underline">yes</emphasis> for all
		Solexas when in a mapping assembly, else it's <emphasis
		role="underline">no</emphasis>. Can only be used in mapping
		assemblies. If set to <emphasis
		role="underline">yes</emphasis>, MIRA will merge all perfectly
		mapping Solexa reads into longer reads (Coverage Equivalent
		Reads, CERs) while keeping quality and coverage information
		intact.
	      </para>
	      <para>
		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.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>msr_keepcontigendsunmerged(msrme)=<replaceable>integer &ge; 0</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		Default is <emphasis role="underline">0</emphasis> for all
		Solexas when in a mapping assembly. Takes only effect in
		mapping assemblies if <arg>-CO:msr=yes</arg>.
	      </para>
	      <para>
		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.
	      </para>
	      <warning>
		This feature allows to merge non-perfect reads, which makes
		most SNP information simply disappear from the alignment. Use
		with care!
	      </warning>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>msr_keepcontigendsunmerged(msrkceu)=<replaceable>-1, integer &gt; 0</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		Default is <emphasis role="underline">-1</emphasis> for all
		Solexas when in a mapping assembly. Takes only effect in
		mapping assemblies if <arg>-CO:msr=yes</arg> and for reads
		which have a paired-end / mate-pair partner actively used in
		the assembly.
	      </para>
	      <para>
		If set to a value &gt; 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 <arg>-GE:tismax</arg> or via XML TRACEINFO
		for the given read).
	      </para>
	      <para>
		This feature allows to use the data reduction from
		<arg>-CO:msr</arg> while enabling the result of such a mapping
		to be useful in subsequent scaffolding programs to order
		contigs.
	      </para>
	    </listitem>
	  </varlistentry>
	</variablelist>
      </sect3>
      <sect3 id="sect_ref_edit_ed">
	<title>
	  Parameter group: -EDIT (-ED)
	</title>
	<para>
	  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:
	</para>
	<itemizedlist>
	  <listitem>
	    <para>
	      in EST assemblies, they may edit rare transcripts toward almost
	      identical, more abundant transcripts. Usage must be carefully weighed.
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      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).
	    </para>
	  </listitem>
	</itemizedlist>
	<para>
	</para>
	<para>
	  The following edit parameters are supported:
	</para>
	<variablelist>
	  <varlistentry>
	    <term>
	      <arg>_mira_automatic_contig_editing(mace)=<replaceable>on|y[es]|t[rue], off|n[o]|f[alse]</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		Default is <emphasis role="underline">yes</emphasis>. When set
		to yes, MIRA will use built-in versions of own automatic
		contig editors (see parameters below) to improve alignments.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>edit_kmer_singlets(eks)=<replaceable>on|y[es]|t[rue], off|n[o]|f[alse]</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		Default is <emphasis role="underline">yes</emphasis> for all
		sequencing technologies, but only takes effect
		if <arg>-ED:mace</arg> is on (see above).
	      </para>
	      <para>
		When set to yes, MIRA uses the alignment information of a
		complete contig at places with sequencing errors which lead to
		unique kmers and correct the error according to the alignment.
	      </para>
	      <para>
		This is an extremely conservative yet very effective editing
		strategy and can therefore be kept always activated.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>edit_homopolymer_overcalls(ehpo)=<replaceable>on|y[es]|t[rue], off|n[o]|f[alse]</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		Default is <emphasis role="underline">yes</emphasis> for 454
		and Ion Torrent, but only takes effect if <arg>-ED:mace</arg>
		is on (see above).
	      </para>
	      <para>
		When set to yes, MIRA use the alignment information of a
		complete contig at places with potential homopolymer
		sequencing errors and correct the error according to the
		alignment.
	      </para>
	      <para>
		This editor should be switched on only for sequencing
		technologies with known homopolymer sequencing problems. That
		is: currently only 454 and Ion.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>edit_automatic_contig_editing(eace)=<replaceable>on|y[es]|t[rue], off|n[o]|f[alse]</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		Default is <emphasis role="underline">no</emphasis>. When set
		to yes, MIRA will use built-in versions of the "EdIt"
		automatic contig editor (see parameters below) to correct
		sequencing errors in Sanger reads.
	      </para>
	      <para>
		EdIt will try to resolve discrepancies in the contig by
		performing trace signal analysis and correct even hard to resolve
		errors.
	      </para>
	      <note>
		The current development version has a memory leak in
		this editor, therefore the option cannot be turned
		on.
	      </note>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>strict_editing_mode(sem)=<replaceable>on|y[es]|t[rue], off|n[o]|f[alse]</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		Default is <emphasis role="underline">yes</emphasis>. 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.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>confirmation_threshold(ct)=<replaceable>integer, 0 &lt; x &le; 100</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		Default is <emphasis role="underline">50</emphasis>. 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.
	      </para>
	    </listitem>
	  </varlistentry>
	</variablelist>
	<para>
	</para>
      </sect3>
      <sect3 id="sect_ref_misc_mi">
	<title>
	  Parameter group: -MISC (-MI)
	</title>
	<para>
	  Options which would not fit elsewhere.
	</para>
	<variablelist>
	  <varlistentry>
	    <term>
	      <arg>iknowwhatido(ikwid)=<replaceable>on|y[es]|t[rue], off|n[o]|f[alse]</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		Default is <emphasis role="underline">no</emphasis>. This
		switch tells MIRA that you know what you do in some
		situations and force it not to stop when it thinks something is
		really wrong, but simply continue.
	      </para>
	      <warning>
		You generally should not to set this flag except in cases
		where MIRA stopped and the warning / error message told you to
		get around that very specific problem by setting this flag.
	      </warning>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>large_contig_size(lcs)=<replaceable>integer &lt;
	      0</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		Default is <emphasis role="underline">500</emphasis>. This
		parameter has absolutely no influence whatsoever on the
		assembly process of MIRA. But is used in the reporting within
		the <filename>*_assembly_info.txt</filename> file after the
		assembly where MIRA reports statistics on
		<emphasis>large</emphasis> contigs and
		<emphasis>all</emphasis> contigs. <arg>-MI:lcs</arg> is the
		threshold value for dividing the contigs into these two
		categories.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>large_contig_size_for_stats(lcs4s)=<replaceable>integer &lt;
	      0</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		Default is <emphasis role="underline">5000</emphasis> for
		<arg>--job=genome</arg> and <emphasis
		role="underline">1000</emphasis> for <arg>--job=est</arg>.
	      </para>
	      <para>
		This parameter is used for internal statistics calculations
		and has a subtle influence when being in a
		<arg>--job=genome</arg> assembly mode.
	      </para>
	      <para>
		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 regarding the average coverage of a genome,
		the "large contig size for stats" value of
		<arg>-MI:lcs4s</arg> 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.
	      </para>
	      <para>
		This reflects two facts: on the one hand - especially with
		short read sequencing technologies and in projects without
		read pair libraries - contigs containing predominantly
		repetitive sequences are of a relatively small size. On the
		other hand, reads which could not be placed into contigs
		(maybe due to a sequencing technology dependent motif error)
		often enough form small contigs with extremely low
		coverage.
	      </para>
	      <para>
		 It should be clear that one does not want any of the above
		 when calculating average coverage statistics and having this
		 cutoff discards small contigs which tend to muddy the
		 picture. If in doubt, don't touch this parameter.
	      </para>
	    </listitem>
	  </varlistentry>
	</variablelist>
      </sect3>
      <sect3 id="sect_ref_misc_nw">
	<title>
	  Parameter group: -NAG_AND_WARN (-NW)
	</title>
	<para>
	  Parameters which let MIRA warn you about unusual things or potential
	  problems. The flags in this parameter section come in three
	  flavours: <emphasis>stop</emphasis>, <emphasis>warn</emphasis> and
	  <emphasis>no</emphasis> which let MIRA either stop, give a warning
	  or do nothing if a specific problem is detected.
	</para>
	<variablelist>
	  <varlistentry>
	    <term>
	      <arg>check_nfs(cnfs)=<replaceable>stop|warn|no</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		Default is <emphasis role="underline">stop</emphasis>. MIRA
		will check whether the tmp directory is running on a NFS
		mount.
	      </para>
	      <warning>
		<para>
		  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.
		</para>
		<para>
		  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.
		</para>
	      </warning>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>check_duplicate_readnames(cdrn)=<replaceable>stop|warn|no</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		Default is <emphasis role="underline">stop</emphasis>. MIRA
		will check for duplicate read names after loading.
	      </para>
	      <warning>
		<para>
		  Duplicate read names usually hint to a serious problem with
		  your input and should really, really be fixed. You can
		  choose to ignore this error by switching off this flag, but
		  this will almost certainly lead to problems with result
		  files (ACE and CAF for sure, maybe also SAM) and probably to
		  other unexpected effects.
		</para>
	      </warning>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>check_template_problems(ctp)=<replaceable>stop|warn|no</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		Default is <emphasis role="underline">stop</emphasis>. MIRA
		will check read template naming after loading.
	      </para>
	      <warning>
		<para>
		  Problems in read template naming point to problems with read
		  names or to broken template information. You should try to
		  find the cause of the problem instead of ignoring this error
		  message.
		</para>
	      </warning>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>check_maxreadnamelength(cmrnl)=<replaceable>stop|warn|no</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		Default is <emphasis role="underline">stop</emphasis>. MIRA
		will check whether the length of the names of your reads
		surpass the given number of characters (see <arg>-NW:mrnl</arg>).
	      </para>
	      <para>
		While MIRA and many other programs have no problem with long read names,
		some older programs have restrictions concerning the length of
		the read name. Example given: the pipeline <literal>CAF ->
		caf2gap -> gap2caf</literal> will stop working at
		the <command>gap2caf</command> stage if there are read names
		having &gt; 40 characters where the names differ only at >40
		characters.
	      </para>
	      <para>
		This should be 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 &le; 40 characters.
	      </para>
	      <para>
		On the other hand, you also can ignore this potential problem
		and force MIRA to continue by using the parameter:
		<arg>-NW:cmrnl=warn</arg> or <arg>-NW:cmrnl=no</arg>
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>maxreadnamelength(mrnl)=<replaceable>integer &ge;
	      0</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		Default is <emphasis role="underline">40</emphasis>. This
		defines the effective check length for <arg>-NW:cmrnl</arg>.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>check_average_coverage(cac)=<replaceable>stop|warn|no</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		Default is <emphasis role="underline">stop</emphasis>. In
		genome de-novo assemblies, MIRA will perform checks early in
		the assembly process whether the average coverage to be
		expected exceeds a given value (see <arg>-NW:acv</arg>).
	      </para>
	      <para>
		With todays' sequencing technologies (especially Illumina, but
		also Ion Torrent and 454), many people simply take everything
		they get and throw it into an assembly. Which, in the case of
		Illumina and Ion, can mean they try to assemble their organism
		with a coverage of 100x, 200x and more (I've seen trials with
		more than 1000x).
	      </para>
	      <para>
		This is not good. Not. At. All! For two reasons (well, three
		to be precise).
	      </para>
	      <para>
		The first reason is that, usually, one does not sequence a
		single cell but a population of cells. If this population is
		not clonal (i.e., it contains subpopulations with genomic
		differences with each other), assemblers will be able to pick
		up these differences in the DNA once a certain sequence count
		is reached and they will try reconstruct a genome containing
		all clonal variations, treating these variations as potential
		repeats with slightly different sequences. Which, of course,
		will be wrong and I am pretty sure you do not want that.
	      </para>
	      <para>
		The second and way more important reason is that none of the
		current sequencing technologies is completely error free. Even
		more problematic, they contain both random and non-random
		sequencing errors. Especially the latter can become a big
		hurdle if these non-random errors are so prevalent that they
		suddenly appear to be valid sequence to an assembler. This in
		turn leads to false repeat detection, hence possibly contig
		breaks or even wrong consensus sequence. You don't want that,
		do you?
	      </para>
	      <para>
		The last reason is that overlap based assemblers (like MIRA
		is) need <emphasis>exponentially</emphasis> more time and
		memory when the coverage increases. So keeping the coverage
		comparatively low helps you there.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>average_coverage_value(acv)=<replaceable>integer &ge;
	      0</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		Default is <emphasis role="underline">80</emphasis> for
		de-novo assemblies, in mapping assemblies it is 120 for Ion
		Torrent and 160 for Illumina data (might change in
		future). This defines the effective coverage to check for in
		<arg>-NW:cac</arg>.
	      </para>
	    </listitem>
	  </varlistentry>
 	</variablelist>
      </sect3>
      <sect3 id="sect_ref_directory_dir_di">
	<title>
	  Parameter group: -DIRECTORY (-DIR, -DI)
	</title>
	<para>
	  General options for controlling where to find or where to write data.
	</para>
	<variablelist>
	  <varlistentry>
	    <term>
	      <arg>tmp_redirected_to(trt)=<replaceable>&lt;directoryname&gt;</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		Default is an empty string. When set to a non-empty string,
		MIRA will create the MIRA-temporary directory at the given
		location instead of using the current working directory.
	      </para>
	      <para>
		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).
	      </para>
	      <para>
		In both cases above, and for larger projects, MIRA then runs
		a lot faster.
	      </para>
	      <note>
		Prior to MIRA 4.0rc2, users had to make sure themselves that
		the target directory did not already exist. MIRA now handles
		this automatically by creating directory names with a random
		substring attached.
	      </note>
	    </listitem>
	  </varlistentry>
	</variablelist>
      </sect3>
       <sect3 id="sect_ref_output_out">
	<title>
	  Parameter group: -OUTPUT (-OUT)
	</title>
	<para>
	  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).
	</para>
	<para>
	  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.
	</para>
	<para>
	  Output can be generated in these formats: CAF, Gap4 Directed
	  Assembly, FASTA, ACE, TCS, WIG, HTML and simple text.
	</para>
	<para>
	  Naming conventions of the files follow the rules described in
	  section <emphasis role="bold">Input / Output</emphasis>, subsection
	  <emphasis role="bold">Filenames</emphasis>.
	</para>
	<variablelist>
	  <varlistentry>
	    <term>
	      <arg>savesimplesingletsinproject(sssip)=<replaceable>on|y[es]|t[rue],off|n[o]|f[alse]</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		Default is <emphasis role="underline">no</emphasis>. Controls
		whether 'unimportant' singlets are written to the result
		files.
	      </para>
	      <note>
		Note that a value larger 1 of the <arg>-AS:mrpc</arg>
		parameter will disable the function of this parameter.
	      </note>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>savetaggedsingletsinproject(stsip)=<replaceable>on|y[es]|t[rue],off|n[o]|f[alse]</replaceable></arg>
	    </term>
	    <listitem>
	      <para> Default
		is <emphasis role="underline">yes</emphasis>. Controls whether
		singlets which have certain tags (see below) are written to
		the result files, even if <arg>-OUT:sssip</arg> (see above) is
		set.
	      </para>
	      <para>
		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.
	      </para>
	      <note>
		Note that a value larger 1 of the <arg>-AS:mrpc</arg>
		parameter will disable the function of this parameter.
	      </note>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>remove_rollover_tmps(rrot)=<replaceable>on|y[es]|t[rue], off|n[o]|f[alse]</replaceable></arg>
	    </term>
	    <listitem>
	      <para> Default
	      is <emphasis role="underline">yes</emphasis>. Removes log and
	      temporary files once they should not be needed anymore during
	      the assembly process.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>remove_tmp_directory(rtd)=<replaceable>on|y[es]|t[rue], off|n[o]|f[alse]</replaceable></arg>
	    </term>
	    <listitem>
	      <para> Default
	      is <emphasis role="underline">no</emphasis>. 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.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>output_result_caf(orc)=<replaceable>on|y[es]|t[rue],
	      off|n[o]|f[alse]</replaceable></arg>
	    </term>
	    <listitem>
	      <para> Default is
	      <emphasis role="underline">yes</emphasis>.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>output_result_maf(orm)=<replaceable>on|y[es]|t[rue],
	      off|n[o]|f[alse]</replaceable></arg>
	    </term>
	    <listitem>
	      <para> Default is
	      <emphasis role="underline">yes</emphasis>.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>output_result_gap4da(org)=<replaceable>on|y[es]|t[rue], off|n[o]|f[alse]</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		Default is <emphasis role="underline">no</emphasis>.
	      </para>
	      <note>
		If set to <emphasis role="underline">yes</emphasis>, MIRA will
		automatically switch back
		to <emphasis role="underline">no</emphasis> (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.
	      </note>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>output_result_fasta(orf)=<replaceable>on|y[es]|t[rue], off|n[o]|f[alse]</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		Default is <emphasis role="underline">yes</emphasis>.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>output_result_ace(ora)=<replaceable>on|y[es]|t[rue],
	      off|n[o]|f[alse]</replaceable></arg>
	    </term>
	    <listitem>
	      <para> Default
	      is <emphasis role="underline">no</emphasis>.
	      </para>
	      <warning>
		ACE is the least suited file format for NGS data. Use it only
		when absolutely necessary.
	      </warning>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>output_result_txt(ort)=<replaceable>on|y[es]|t[rue], off|n[o]|f[alse]</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		Default is <emphasis role="underline">no</emphasis>.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>output_result_tcs(ors)=<replaceable>on|y[es]|t[rue], off|n[o]|f[alse]</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		Default is <emphasis role="underline">yes</emphasis>.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>output_result_html(orh)=<replaceable>on|y[es]|t[rue], off|n[o]|f[alse]</replaceable></arg>
	    </term>
	    <listitem>
	      <para> Default
	      is <emphasis role="underline">no</emphasis>.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>output_tmpresult_caf(otc)=<replaceable>on|y[es]|t[rue], off|n[o]|f[alse]</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		Default is <emphasis role="underline">no</emphasis>.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>output_tmpresult_maf(otm)=<replaceable>on|y[es]|t[rue], off|n[o]|f[alse]</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		Default is <emphasis role="underline">no</emphasis>.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>output_tmpresult_gap4da(otg)=<replaceable>on|y[es]|t[rue], off|n[o]|f[alse]</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		Default is <emphasis role="underline">no</emphasis>.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>output_tmpresult_fasta(otf)=<replaceable>on|y[es]|t[rue], off|n[o]|f[alse]</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		Default is <emphasis role="underline">no</emphasis>.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>output_tmpresult_ace(ota)=<replaceable>on|y[es]|t[rue], off|n[o]|f[alse]</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		Default is <emphasis role="underline">no</emphasis>.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>output_tmpresult_txt(ott)=<replaceable>on|y[es]|t[rue], off|n[o]|f[alse]</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		Default is <emphasis role="underline">no</emphasis>.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>output_result_tcs(ots)=<replaceable>on|y[es]|t[rue], off|n[o]|f[alse]</replaceable></arg>
	    </term>
	    <listitem>
	      <para> Default
	      is <emphasis role="underline">no</emphasis>.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>output_tmpresult_html(oth)=<replaceable>on|y[es]|t[rue], off|n[o]|f[alse]</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		Default is <emphasis role="underline">no</emphasis>.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>output_exttmpresult_caf(oetc)=<replaceable>on|y[es]|t[rue], off|n[o]|f[alse]</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		Default is <emphasis role="underline">no</emphasis>.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>output_exttmpresult_gap4da(oetg)=<replaceable>on|y[es]|t[rue], off|n[o]|f[alse]</replaceable></arg>
	    </term>
	    <listitem>
	      <para> Default is
	      <emphasis role="underline">no</emphasis>.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>output_exttmpresult_fasta(oetf)=<replaceable>on|y[es]|t[rue], off|n[o]|f[alse]</replaceable></arg>
	    </term>
	    <listitem>
	      <para> Default is
	      <emphasis role="underline">no</emphasis>.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>output_exttmpresult_ace(oeta)=<replaceable>on|y[es]|t[rue], off|n[o]|f[alse]</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		Default is <emphasis role="underline">no</emphasis>.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>output_exttmpresult_txt(oett)=<replaceable>on|y[es]|t[rue], off|n[o]|f[alse]</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		Default is <emphasis role="underline">no</emphasis>.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>output_exttmpresult_html(oeth)=<replaceable>on|y[es]|t[rue], off|n[o]|f[alse]</replaceable></arg>
	    </term>
	    <listitem>
	      <para>
		Default is <emphasis role="underline">no</emphasis>.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>text_chars_per_line(tcpl)=<replaceable>integer &gt; 0</replaceable></arg>
	    </term>
	    <listitem>
	      <para> Default is
	      <emphasis role="underline">60</emphasis>. When producing an output in text format
	      (<arg>-OUT:ort|ott|oett</arg>), this parameter defines how many bases
	      each line of an alignment should contain.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>html_chars_per_line(tcpl)=<replaceable>integer &gt; 0</replaceable></arg>
	    </term>
	    <listitem>
	      <para> Default is
	      <emphasis role="underline">60</emphasis>. When producing an output in HTML format,
	      (<arg>-OUT:orh|oth|oeth</arg>), this parameter defines how many bases
	      each line of an alignment should contain.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>text_endgap_fillchar(tegfc)=<replaceable>&lt;single character&gt;</replaceable></arg>
	    </term>
	    <listitem>
	      <para> Default
	      is <emphasis role="underline"> </emphasis> (a blank). When producing an output in text format
	      (<arg>-OUT:ort|ott|oett</arg>), endgaps are filled up with this
	      character.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <arg>html_endgap_fillchar(hegfc)=<replaceable>&lt;single character&gt;</replaceable></arg>
	    </term>
	    <listitem>
	      <para> Default
	      is <emphasis role="underline"> </emphasis> (a blank). When producing an output in HTML format
	      (<arg>-OUT:orh|oth|oeth</arg>), end-gaps are filled up with this
	      character.
	      </para>
	    </listitem>
	  </varlistentry>
	</variablelist>
	<para>
	</para>
      </sect3>
    </sect2>
  </sect1>
  <sect1 id="sect_ref_resuming_assemblies">
    <title>
      Resuming / restarting assemblies
    </title>
    <para>
      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.
    </para>
    <para>
      If this happens in de-novo assemblies, MIRA has
      a <emphasis>resume</emphasis> 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 <arg>-r</arg> on a command line like this:
    </para>
    <screen>
<prompt>$</prompt> <userinput>mira -r ...</userinput></screen>
    <para>
      where the ellipsis ("...") above stands for the rest of the command line you would have used to start a new assembly.
    </para>
  </sect1>
  <sect1 id="sect_ref_input_output">
    <title>
      Input / Output
    </title>
    <sect2 id="sect_ref_directories">
      <title>
	Directories
      </title>
      <para>
	Since version 3.0.0, MIRA now puts all files and directories it
	generates into one sub-directory which is named
	<filename><replaceable>projectname</replaceable>_assembly</filename>. This directory contains up to four
	sub-directories:
      </para>
      <itemizedlist>
	<listitem>
	  <para>
	    <filename><replaceable>projectname</replaceable>_d_results</filename>: this directory contains all the
	    output files of the assembly in different formats.
	  </para>
	</listitem>
	<listitem>
	  <para>
	    <filename><replaceable>projectname</replaceable>_d_info</filename>: this directory contains information
	    files of the final assembly. They provide statistics as well as, e.g.,
	    information (easily parsable by scripts) on which read is found in which
	    contig etc.
	  </para>
	</listitem>
	<listitem>
	  <para>
	    <filename><replaceable>projectname</replaceable>_d_tmp</filename>:
	    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.
	  </para>
	  <para>
	    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.
	  </para>
	</listitem>
	<listitem>
	  <para>
	    <filename><replaceable>projectname</replaceable>_d_chkpt</filename>: this directory
	    contains checkpoint files needed to resume assemblies that crashed
	    or were stopped.
	  </para>
	</listitem>
      </itemizedlist>
      <para>
      </para>
    </sect2>
    <sect2 id="sect_ref_filenames">
      <title>
	Filenames
      </title>
      <sect3 id="sect_ref_output">
	<title>
	  Output
	</title>
	<para>
	  These result output files and sub-directories are placed in in the
	  <replaceable>projectname</replaceable>_results directory after a run of MIRA.
	</para>
	<variablelist>
	  <varlistentry>
	    <term>
	      <filename><replaceable>projectname</replaceable>_out.&lt;type&gt;</filename>
	    </term>
	    <listitem>
	      <para> Assembled project written in type =
	      (<emphasis>maf</emphasis> / <emphasis>gap4da</emphasis> / <emphasis>caf</emphasis> /
	      <emphasis>ace</emphasis> / <emphasis>fasta</emphasis> /
	      <emphasis>html</emphasis> / <emphasis>tcs</emphasis> /
	      <emphasis>wig</emphasis> / <emphasis>text</emphasis>) format by
	      MIRA, final result.
	      </para>
	      <para>
		Type <emphasis>gap4da</emphasis> is a directory containing
		experiment files and a file of filenames (called 'fofn'), all
		other types are files. <emphasis>gap4da</emphasis>,
		<emphasis>caf</emphasis>, <emphasis>ace</emphasis> contain the
		complete assembly information suitable for import into
		different post-processing tools (gap4, consed and
		others). <emphasis>html</emphasis> and
		<emphasis>text</emphasis> contain visual representations of
		the assembly suited for viewing in browsers or as simple text
		file. <emphasis>tcs</emphasis> is a summary of a contig suited
		for "quick" analysis from command-line tools or even visual
		inspection. <emphasis>wig</emphasis> 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.
	      </para>
	      <para>
		<emphasis>fasta</emphasis> contains the contig consensus
		sequences (and .fasta.qual the consensus qualities). Please
		note that they come in two flavours:
		<emphasis role="underline">padded</emphasis>
		and <emphasis role="underline">unpadded</emphasis>. 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 <emphasis>.padded</emphasis>, while
		unpadded versions <emphasis>.unpadded</emphasis>.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <filename><replaceable>projectname</replaceable>_LargeContigs_out.&lt;type&gt;</filename>
	    </term>
	    <listitem>
	      These files are only written when MIRA runs in
	      <emphasis>de-novo</emphasis> mode. They usually contain a subset
	      of contigs deemed 'large' from the whole project. More details
	      are given in the chapter "working with results of MIRA."
	    </listitem>
	  </varlistentry>
	</variablelist>
      </sect3>
      <sect3 id="sect_ref_assembly_statistics_and_information_files">
	<title>
	  Assembly statistics and information files
	</title>
	<para>
	  These information files are placed in in the
	  <replaceable>projectname</replaceable>_info directory after a run of
	  MIRA.
	</para>
	<variablelist>
	  <varlistentry>
	    <term>
	      <filename><replaceable>projectname</replaceable>_info_assembly.txt</filename>
	    </term>
	    <listitem>
	      <para>
		This file contains basic information about the
		assembly. MIRA will split the information in two
		parts: information about <emphasis>large</emphasis>
		contigs and information about all contigs.
	      </para>
	      <para>
		For more information on how to interpret this file,
		please consult the chapter on "Results" of the MIRA
		documentation manual.
	      </para>
	      <note>
		In contrast to other information files, this file
		always appears in the "info" directory, even when just
		intermediate results are reported.
	      </note>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <filename><replaceable>projectname</replaceable>_info_contigreadlist.txt</filename>
	    </term>
	    <listitem>
	      <para> This file contains information which reads have been
	      assembled into which contigs (or singlets).
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <filename><replaceable>projectname</replaceable>_info_contigstats.txt</filename>
	    </term>
	    <listitem>
	      <para> 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.
	      </para>
	      <warning>
		For contigs containing digitally normalised reads, the coverage numbers may sometimes seem strange. E.g.: a contig may contain only one read, but have an average coverage of 3. This means that the read was a representative for 3 reads. The coverage numbers are computed as if all 3 reads had been assembled instead of the representative. In EST/RNASeq projects, these numbers thus represent the (more or less) true expression coverage.
	      </warning>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <filename><replaceable>projectname</replaceable>_info_consensustaglist.txt</filename>
	    </term>
	    <listitem>
	      <para> This file contains
	      information about the tags (and their position) that are present in the
	      consensus of a contig.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <filename><replaceable>projectname</replaceable>_info_largecontigs.txt</filename>
	    </term>
	    <listitem>
	      <para>For de-novo assemblies, this file contains the name of the
	      contigs which pass the (adaptable) 'large contig' criterion.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <filename><replaceable>projectname</replaceable>_info_readrepeats.lst</filename>
	    </term>
	    <listitem>
	      <para>
		Tab delimited file with three columns: read name, repeat level tag, sequence.
	      </para>
	      <para>
		This file permits a quick analysis of the repetitiveness of
		different parts of reads in a project. See
		<arg>-SK:rliif</arg> to control from which repetitive level on
		subsequences of reads are written to this file,
	      </para>
	      <note>
		Reads can have more than one entry in this file. E.g., with
		standard settings (<literal>-SK:rliif=6</literal>) 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.
	      </note>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <filename><replaceable>projectname</replaceable>_info_readstooshort</filename>
	    </term>
	    <listitem>
	      <para> 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.
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <filename><replaceable>projectname</replaceable>_info_readtaglist.txt</filename>
	    </term>
	    <listitem>
	      <para> 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).
	      </para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <filename><replaceable>projectname</replaceable>_info_WARNINGS_*.txt</filename>
	    </term>
	    <listitem>
	      <para>
		These files collect warning messages MIRA dumped out
		throughout the assembly process. These warnings cover a wide
		area of things monitored by MIRA and can - together with the
		output written to STDOUT - give an insight as to why an
		assembly does not behave as expected. There are three warning
		files representing different levels of
		criticality: <emphasis>critical</emphasis>, <emphasis>medium</emphasis>
		and <emphasis>minor</emphasis>. These files may be empty,
		meaning that no warning of the corresponding level was
		printed. It is strongly suggested to have a look at least at
		critical warnings during and after an assembly run.
	      </para>
	      <note>
		These files are quite new to MIRA and not all warning messages
		appear there yet. This will come over time.
	      </note>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term>
	      <filename><replaceable>projectname</replaceable>_error_reads_invalid</filename>
	    </term>
	    <listitem>
	      <para> A list of sequences that
	      have been found to be invalid due to various reasons (given in the output of
	      the assembler).
	      </para>
	    </listitem>
	  </varlistentry>
	</variablelist>
	<para>
	</para>
      </sect3>
    </sect2>
    <sect2 id="sect_ref_file_formats">
      <title>
	File formats
      </title>
      <para>
	MIRA can write almost all of the following formats and can read most
	of them.
      </para>
      <variablelist>
	<varlistentry>
	  <term>
	    <filename>ACE</filename>
	  </term>
	  <listitem>
	    <para> This old 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't have access to consed to verify my assumptions.
	    </para>
	    <para> 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 older
	    MIRA distributions (V4.9.5 and before), then all should be well.
	    </para>
	    <para> If you don't have consed, you might want to try clview
	    (<ulink url="http://www.tigr.org/tdb/tgi/software/"/>) from TIGR
	    to look at .ace files.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>
	    <filename>BAM</filename>
	  </term>
	  <listitem>
	    The binary cousin of the SAM format. MIRA neither reads nor writes
	    BAM, but BAMs can be created out of SAMs (which can be created via
	    <command>miraconvert</command>).
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>
	    <filename>CAF</filename>
	  </term>
	  <listitem>
	    <para> Common Assembly Format (CAF) developed by the Sanger
	    Centre. <ulink url="http://www.sanger.ac.uk/resources/software/caf.html"/> 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).
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>
	    <filename>EXP</filename>
	  </term>
	  <listitem>
	    <para> 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 <ulink
	    url="http://www.sourceforge.net/projects/staden/"/> for links to
	    online format description.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>
	    <filename>FASTA</filename>
	  </term>
	  <listitem>
	    <para> A simple format for sequence data, see
	    <ulink url="http://www.ncbi.nlm.nih.gov/BLAST/fasta.html"/>. 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.
	    </para>
	    <para>
	      MIRA writes two kinds of FASTA files for
	      results: <emphasis>padded</emphasis> and
	      <emphasis>unpadded</emphasis>. 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
	      <emphasis>unpadded</emphasis> version has the gaps removed.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>
	    <filename>GBF, GBK</filename>
	  </term>
	  <listitem>
	    <para> GenBank file format as used at the NCBI to describe
	    sequences. MIRA is able to read and write this format (but only
	    for viruses or bacteria) for using sequences as backbones in an
	    assembly. Features of the GenBank format are also transferred
	    automatically to Staden compatible tags.
	    </para>
	    <para>
	      If possible, use GFF3 instead (see below).
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>
	    <filename>GFF3</filename>
	  </term>
	  <listitem>
	    <para> General feature format used to describe sequences and
	    features on these sequences. MIRA is able to read and write this
	    format.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>
	    <filename>HTML</filename>
	  </term>
	  <listitem>
	    <para> 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).
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>
	    <filename>MAF</filename>
	  </term>
	  <listitem>
	    <para> MIRA Assembly Format (MAF). A faster and more compact form
	    than EXP, CAF or ACE. See documentation in separate file.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>
	    <filename>PHD</filename>
	  </term>
	  <listitem>
	    <para> 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.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>
	    <filename>SAM</filename>
	  </term>
	  <listitem>
	    <para> The Sequence Alignment/Map Format. MIRA does not write SAM
	    directly, but <command>miraconvert</command> can be used for
	    converting a MAF (or CAF) file to SAM.
	    </para>
	    <para>
	      MIRA cannot read SAM though.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>
	    <filename>SCF</filename>
	  </term>
	  <listitem>
	    <para> The Staden trace file format that has established itself as
	    compact standard replacement for the much bigger ABI files. See
	    <ulink url="http://www.sourceforge.net/projects/staden/"/> for
	    links to online format description.
	    </para>
	    <para>
	      The SCF files should be V2-8bit, V2-16bit, V3-8bit or V3-16bit
	      and can be packed with compress or gzip.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>
	    <filename>traceinfo.XML</filename>
	  </term>
	  <listitem>
	    <para> 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
	    <ulink url="http://www.ncbi.nlm.nih.gov/Traces/trace.cgi?cmd=show&amp;f=rfc&amp;m=main&amp;s=rfc"/> for a full description of all fields.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>
	    <filename>TCS</filename>
	  </term>
	  <listitem>
	    <para> 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" analysis from command line tools,
	    scripts, or even visual inspection in file viewers or spreadsheet
	    programs.
	    </para>
	    <para> 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:
	    </para>
	    <orderedlist>
	      <listitem>
		<para>
		  contig name (width 20)
		</para>
	      </listitem>
	      <listitem>
		<para>
		  padded position in contigs (width 3)
		</para>
	      </listitem>
	      <listitem>
		<para>
		  unpadded position in contigs (width 3)
		</para>
	      </listitem>
	      <listitem>
		<para>
		  separator (a vertical bar)
		</para>
	      </listitem>
	      <listitem>
		<para>
		  called consensus base
		</para>
	      </listitem>
	      <listitem>
		<para>
		  quality of called consensus base (0-100), but MIRA itself caps at 90.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  separator (a vertical bar)
		</para>
	      </listitem>
	      <listitem>
		<para>
		  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.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  coverage of reads having an "A"
		</para>
	      </listitem>
	      <listitem>
		<para>
		  coverage of reads having an "C"
		</para>
	      </listitem>
	      <listitem>
		<para>
		  coverage of reads having an "G"
		</para>
	      </listitem>
	      <listitem>
		<para>
		  coverage of reads having an "T"
		</para>
	      </listitem>
	      <listitem>
		<para>
		  coverage of reads having an "*" (a gap)
		</para>
	      </listitem>
	      <listitem>
		<para>
		  separator (a vertical bar)
		</para>
	      </listitem>
	      <listitem>
		<para>
		  quality of "A" or "--" if none
		</para>
	      </listitem>
	      <listitem>
		<para>
		  quality of "C" or "--" if none
		</para>
	      </listitem>
	      <listitem>
		<para>
		  quality of "G" or "--" if none
		</para>
	      </listitem>
	      <listitem>
		<para>
		  quality of "T" or "--" if none
		</para>
	      </listitem>
	      <listitem>
		<para>
		  quality of "*" (gap) or "--" if none
		</para>
	      </listitem>
	      <listitem>
		<para>
		  separator (a vertical bar)
		</para>
	      </listitem>
	      <listitem>
		<para>
		  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:
		</para>
		<itemizedlist>
		  <listitem>
		    <para>
		      everything OK: a colon (:)
		    </para>
		  </listitem>
		  <listitem>
		    <para>
		      unclear base calling (IUPAC base): a "!M"
		    </para>
		  </listitem>
		  <listitem>
		    <para>
		      potentially problematic base calling involving a gap or low quality: a "!m"
		    </para>
		  </listitem>
		  <listitem>
		    <para>
		      consensus tag(s) of MIRA that hint to problems: a "!$". Currently,
		      the following tags will lead to this marker: SRMc, WRMc, DGPc, UNSc,
		      IUPc.
		    </para>
		  </listitem>
		</itemizedlist>
	      </listitem>
	      <listitem>
		<para>
		  list of a consensus tags at that position, tags are delimited by a
		  space. E.g.: "DGPc H454"
		</para>
	      </listitem>
	    </orderedlist>
	  </listitem>
	</varlistentry>
      </variablelist>
    </sect2>
    <sect2 id="sect_ref_stdout_stderr">
      <title>
	STDOUT/STDERR
      </title>
      <para>
	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.
      </para>
      <para>
	Some debugging information might also be written to STDOUT if MIRA
	generates error messages.
      </para>
      <para>
	On errors, MIRA will dump these also to STDOUT. Basically, three error classes
	exist:
      </para>
      <orderedlist>
	<listitem>
	  <para>
	    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 <emphasis role="bold">DO</emphasis> want to check how
	    and why these errors came into those files in the first place.
	  </para>
	  <para>
	    Frequent cause for warnings include missing SCF files, SCF files
	    containing known quirks, EXP files containing known quirks etc.
	  </para>
	</listitem>
	<listitem>
	  <para>
	    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.
	  </para>
	  <para>
	    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.
	  </para>
	</listitem>
	<listitem>
	  <para>
	    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.
	  </para>
	</listitem>
      </orderedlist>
      <para>
      </para>
    </sect2>
    <sect2 id="sect_ref_ssaha2smalt">
      <title>
	SSAHA2 / SMALT ancillary data
      </title>
      <para>
	The <command>ssaha2</command> or <command>smalt</command> 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
	<command>ssaha2</command> or <command>smalt</command> run and
	interpret the results to tag the possible vector sequences at the ends
	of reads.
      </para>
      <para>
	Note that this also uses the parameters
	<arg>-CL:msvsgs:msvsmfg:msvsmeg</arg> (see below).
      </para>
      <para>
	ssaha2 must be called like this "<literal>ssaha2
	  &lt;ssaha2options&gt; vector.fasta sequences.fasta</literal>"
	to generate an output that can be parsed by MIRA. In the above
	example, replace <filename>vector.fasta</filename> by the name
	of the file with your vector sequences and
	<filename>sequences.fasta</filename> by the name of the file
	containing your sequencing data.
      </para>
      <para>
	smalt must be called like this: "<literal>smalt map -f ssaha
	  &lt;ssaha2options&gt; hash_index sequences.fasta</literal>"
      </para>
      <para>
	This makes you basically independent from any other commercial or
	license-requiring vector screening software. For Sanger reads, a
	combination of <command>lucy</command> and
	<command>ssaha2</command> or <command>smalt</command> together with
	this parameter should do the trick. For reads coming from 454
	pyro-sequencing, <command>ssaha2</command> or
	<command>smalt</command> and this parameter will also work very
	well. See the usage manual for a walkthrough example on how to use
	SSAHA2 / SMALT screening data.
      </para>
      <note>
	The output format of SSAHA2 must the native output format
	(<literal>-output ssaha2</literal>). For SMALT, the output
	option <literal>-f ssaha</literal> must be used. Other formats cannot
	be parsed by MIRA.
      </note>
      <note>
	I currently use the following SSAHA2 options:
	<literal>-kmer 8 -skip 1 -seeds 1 -score 12 -cmatch 9 -ckmer
	  6</literal>
      </note>
      <note>
	Anyone contributing SMALT parameters?
      </note>
      <note>
	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.
      </note>
    </sect2>
    <sect2 id="sect_ref_xml_traceinfo">
      <title>
	XML TRACEINFO ancillary data
      </title>
      <para>
	MIRA extracts the following data from the TRACEINFO files:
      </para>
      <itemizedlist>
	<listitem>
	  <para>
	    trace_name (required)
	  </para>
	</listitem>
	<listitem>
	  <para>
	    trace_file (recommended)
	  </para>
	</listitem>
	<listitem>
	  <para>
	    trace_type_code (recommended)
	  </para>
	</listitem>
	<listitem>
	  <para>
	    trace_end (recommended)
	  </para>
	</listitem>
	<listitem>
	  <para>
	    clip_quality_left (recommended)
	  </para>
	</listitem>
	<listitem>
	  <para>
	    clip_quality_right (recommended)
	  </para>
	</listitem>
	<listitem>
	  <para>
	    clip_vector_left (recommended)
	  </para>
	</listitem>
	<listitem>
	  <para>
	    clip_vector_right (recommended)
	  </para>
	</listitem>
	<listitem>
	  <para>
	    strain (recommended)
	  </para>
	</listitem>
	<listitem>
	  <para>
	    template_id (recommended for paired end)
	  </para>
	</listitem>
	<listitem>
	  <para>
	    insert_size (recommended for paired end)
	  </para>
	</listitem>
	<listitem>
	  <para>
	    insert_stdev (recommended for paired end)
	  </para>
	</listitem>
	<listitem>
	  <para>
	    machine_type (optional)
	  </para>
	</listitem>
	<listitem>
	  <para>
	    program_id (optional)
	  </para>
	</listitem>
      </itemizedlist>
      <para>
      </para>
      <para>
	Other data types are also read, but the info is not used.
      </para>
      <para>
	Here's the example for a TRACEINFO file with ancillary info:
      </para>
      <screen>
&lt;?xml version=&quot;1.0&quot;?&gt;
&lt;trace_volume&gt;
&lt;trace&gt;
  &lt;trace_name&gt;GCJAA15TF&lt;/trace_name&gt;
  &lt;program_id&gt;PHRED (0.990722.G) AND TTUNER (1.1)&lt;/program_id&gt;
  &lt;template_id&gt;GCJAA15&lt;/template_id&gt;
  &lt;trace_direction&gt;FORWARD&lt;/trace_direction&gt;
  &lt;trace_end&gt;F&lt;/trace_end&gt;
  &lt;clip_quality_left&gt;3&lt;/clip_quality_left&gt;
  &lt;clip_quality_right&gt;622&lt;/clip_quality_right&gt;
  &lt;clip_vector_left&gt;1&lt;/clip_vector_left&gt;
  &lt;clip_vector_right&gt;944&lt;/clip_vector_right&gt;
  &lt;insert_stdev&gt;600&lt;/insert_stdev&gt;
  &lt;insert_size&gt;2000&lt;/insert_size&gt;
&lt;/trace&gt;
&lt;trace&gt;
  ...
&lt;/trace&gt;
...
&lt;/trace_volume&gt;</screen>
      <para>
	See
	<ulink url="http://www.ncbi.nlm.nih.gov/Traces/trace.cgi?cmd=show&amp;f=rfc&amp;m=main&amp;s=rfc"/>
	for a full description of all fields and more info on the TRACEINFO XML format.
      </para>
    </sect2>
    <sect2 id="sect_ref_contig_naming">
      <title>
	Contig naming
      </title>
      <para>
	MIRA names contigs the following
	way: <emphasis>&lt;projectname&gt;_&lt;contigtype&gt;&lt;number&gt;</emphasis>. While <emphasis>&lt;projectname&gt;</emphasis>
	is dictated by the <arg>--project=</arg> parameter
	and <emphasis>&lt;number&gt;</emphasis> should be clear,
	the <emphasis>&lt;contigtype&gt;</emphasis> might need additional
	explaining. There are currently three contig types existing:
      </para>
      <orderedlist>
	<listitem>
	  <para>
	    _c: these are "normal" contigs
	  </para>
	</listitem>
	<listitem>
	  <para>
	    _rep_c: only for genome assembly mode. These are contigs
	    containing only repetitive areas. These contigs
	    had <emphasis>_lrc</emphasis> as type in previous version of MIRA,
	    this was changed to the <emphasis>_rep_c</emphasis> to make things
	    clearer.
	  </para>
	</listitem>
	<listitem>
	  <para>
	    _s: these are singlet-contigs. Technically: "contigs" with a
	    single read.
	  </para>
	</listitem>
	<listitem>
	  <para>
	    _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".
	  </para>
	  <para>
	    Reads covered only partly by the DGNr tag do not trigger the _dn
	    naming.
	  </para>
	  <note>
	    <title>Important side note</title> Due to the digital
	    normalisation step, the coverage numbers in the info file
	    regarding contig statistics will not represent 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.
	  </note>
	</listitem>
      </orderedlist>
      <para>
	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 <emphasis>_c</emphasis> 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
	<emphasis>_rep_c</emphasis> instead of <emphasis>_c</emphasis>. This
	is why "_rep_c" contigs occur late in a genome assembly.
      </para>
      <note>
	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.
      </note>
      <note>
	Depending on the settings of <arg>-AS:mrpc</arg>, your project may or
	may not contain <emphasis>_s</emphasis> singlet-contigs. Also note
	that reads landing in the debris file will not get assigned to
	singlet-contigs and hence not get <emphasis>_s</emphasis> names.
      </note>
    </sect2>
    <sect2 id="sect_ref_recovering_strain_specific_consensus">
      <title>
	Recovering strain specific consensus as FASTA
      </title>
      <para>
	In case you used strain information in an assembly, you can
	recover the consensus for just any given strain
	by using <command>miraconvert</command> 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.
      </para>
      <para>
	It will also create a blend of all strains encountered and
	conveniently add "AllStrains" to the name of these files. Note that
	this blend may or may not be something you need, but in some
	cases I found it to be useful.
      </para>
    </sect2>
  </sect1>
  <sect1 id="sect_ref_tags_used_in_the_assembly_by_mira_and_edit">
    <title>
      Tags used in the assembly by MIRA and EdIt
    </title>
    <para>
      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.
    </para>
    <sect2 id="sect_ref_tags_read_and_used">
      <title>
	Tags read (and used)
      </title>
      <para>
	This section lists "foreign" tags, i.e., tags that whose definition was made
	by other software packages than MIRA.
      </para>
      <itemizedlist>
	<listitem>
	  <para>
	    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.
	  </para>
	</listitem>
	<listitem>
	  <para>
	    Fpas: GenBank feature for a poly-A sequence. Used in EST, cDNA or
	    transcript assembly. Either read in the input files or set when using
	    <arg>-CL:cpat</arg>. This allows to keep the poly-A sequence in
	    the reads during assembly without them interfering as massive
	    repeats or as mismatches.
	  </para>
	</listitem>
	<listitem>
	  <para>
	    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.
	  </para>
	</listitem>
	<listitem>
	  <para>
	    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.
	  </para>
	</listitem>
      </itemizedlist>
      <para>
      </para>
    </sect2>
    <sect2 id="sect_ref_tags_set_and_used">
      <title>
	Tags set (and used)
      </title>
      <para>
	This section lists tags which MIRA sets (and reads of course), but that other
	software packages might not know about.
      </para>
      <itemizedlist>
	<listitem>
	  <para>
	    UNSr, UNSc: <emphasis role="bold">UNS</emphasis>ure
	    in <emphasis role="bold">R</emphasis>ead
	    respectively <emphasis role="bold">C</emphasis>ontig.  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.
	  </para>
	  <para>
	    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).
	  </para>
	</listitem>
	<listitem>
	  <para>
	    SRMr, WRMc: <emphasis role="bold">S</emphasis>trong <emphasis role="bold">R</emphasis>epeat <emphasis role="bold">M</emphasis>arker and
	    <emphasis role="bold">W</emphasis>eak <emphasis role="bold">R</emphasis>epeat <emphasis role="bold">M</emphasis>arker. These
	    tags are set in two flavours: as
	    SRM<emphasis role="bold">r</emphasis> and
	    WRM<emphasis role="bold">r</emphasis> when set in reads, and as
	    SRM<emphasis role="bold">c</emphasis> and
	    WRM<emphasis role="bold">c</emphasis> 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).
	  </para>
	  <para>
	    MIRA will automatically set these tags when it encounters repeats
	    and will tag exactly those bases that can be used to discern the
	    differences.
	  </para>
	  <para>
	    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.
	  </para>
	</listitem>
	<listitem>
	  <para>
	    DGPc: <emphasis role="bold">D</emphasis>ubious <emphasis role="bold">G</emphasis>ap <emphasis role="bold">P</emphasis>osition in
	    <emphasis role="bold">C</emphasis>onsensus. Set whenever the gap to base ratio in a column of 454
	    reads is between 40% and 60%.
	  </para>
	</listitem>
	<listitem>
	  <para>
	    SAO, SRO, SIO: <emphasis role="bold">S</emphasis>NP intr<emphasis role="bold">A</emphasis> <emphasis role="bold">O</emphasis>rganism,
	    <emphasis role="bold">S</emphasis>NP <emphasis role="bold">R</emphasis> <emphasis role="bold">O</emphasis>rganism, <emphasis role="bold">S</emphasis>NP <emphasis role="bold">I</emphasis>ntra
	    and inter <emphasis role="bold">O</emphasis>rganism. As for SRM
	    and WRM, these tags have a <emphasis role="bold">r</emphasis>
	    appended when set in reads and
	    a <emphasis role="bold">c</emphasis> appended when set in the
	    consensus. These tags denote SNP positions.
	  </para>
	  <para>
	    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).
	  </para>
	  <para>
	    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).
	  </para>
	</listitem>
	<listitem>
	  <para>
	    STMS: (only hybrid assemblies). The <emphasis role="bold">S</emphasis>equencing <emphasis role="bold">T</emphasis>ype
	    <emphasis role="bold">M</emphasis>ismatch <emphasis role="bold">S</emphasis>olved
	    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.
	  </para>
	  <para>
	    Sometimes this depicts real differences where possible explanation
	    might include: slightly different bugs were sequenced or a
	    mutation occurred during library preparation.
	  </para>
	</listitem>
	<listitem>
	  <para>
	    STMU: (only hybrid assemblies). The <emphasis role="bold">S</emphasis>equencing <emphasis role="bold">T</emphasis>ype
	    <emphasis role="bold">M</emphasis>ismatch <emphasis role="bold">U</emphasis>nresolved
	    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.
	  </para>
	  <para>
	    Sometimes this depicts real differences where possible explanation
	    might include: slightly different bugs were sequenced or a mutation
	    occurred during library preparation.
	  </para>
	</listitem>
	<listitem>
	  <para>
	    MCVc: The <emphasis role="bold">M</emphasis>issing <emphasis role="bold">C</emphasis>o{V}erage in <emphasis role="bold">C</emphasis>onsensus.
	    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.
	  </para>
	</listitem>
	<listitem>
	  <para>
	    MNRr: (only with <arg>-KS:mnr</arg> active). The <emphasis role="bold">M</emphasis>asked
	    <emphasis role="bold">N</emphasis>asty <emphasis role="bold">R</emphasis>epeat 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.
	  </para>
	</listitem>
	<listitem>
	  <para>
	    FpAS: See "Tags read (and used)" above.
	  </para>
	</listitem>
	<listitem>
	  <para>
	    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.
	  </para>
	</listitem>
	<listitem>
	  <para>
	    HAF2, HAF3, HAF4, HAF5, HAF6, HAF7. These
	    are <emphasis role="bold">HA</emphasis>sh <emphasis role="bold">F</emphasis>requency
	    tags which show the status of read parts in comparison to the
	    whole project. Only set if <arg>-AS:ard</arg> is active (default
	    for genome assemblies).
	  </para>
	  <para>
	    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.
	  </para>
	  <para>
	    HAF2 coverage below average ( standard setting at &lt; 0.5 times average)
	  </para>
	  <para>
	    HAF3 coverage is at average ( standard setting at &ge; 0.5 times average and &le; 1.5 times average)
	  </para>
	  <para>
	    HAF4 coverage above average ( standard setting at &gt; 1.5 times average and &lt; 2 times average)
	  </para>
	  <para>
	    HAF5 probably repeat ( standard setting at &ge; 2 times average and &lt; 5 times average)
	  </para>
	  <para>
	    HAF6 'heavy' repeat ( standard setting at &gt; 8 times average)
	  </para>
	  <para>
	    HAF7 'crazy' repeat ( standard setting at &gt; 20 times average)
	  </para>
	</listitem>
      </itemizedlist>
      <para>
      </para>
    </sect2>
  </sect1>
  <sect1 id="sect_ref_contigs_singlets_debris">
    <title>
      Where reads end up: contigs, singlets, debris
    </title>
    <para>
      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 <emphasis>_c</emphasis>.
    </para>
    <para>
      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
      <emphasis>debris</emphasis> file, then just as a name entry, or as singlet (a "contig"
      with just one read) in the regular results.
    </para>
    <orderedlist>
      <listitem>
	<para>
	  reads are too short and get filtered out (before or after the MIRA
	  clipping stages). These invariably land in the debris file.
	</para>
      </listitem>
      <listitem>
	<para>
	  reads are real singlets: they contain genuine sequence but have no
	  overlap with any other read. These get either caught by the
	  <arg>-CL:pec</arg> clipping filter or during the SKIM phase
	</para>
      </listitem>
      <listitem>
	<para>
	  reads contain mostly or completely junk.
	</para>
      </listitem>
      <listitem>
	<para>
	  reads contain chimeric sequence (therefore: they're also junk)
	</para>
      </listitem>
    </orderedlist>
    <para>
      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 dependent on why they do not align with other
      reads. Reads landing in the debris file will have the reason and stage
      attached to the decision.
    </para>
  </sect1>
  <sect1 id="sect_ref_snp_discovery">
    <title>
      Detection of bases distinguishing non-perfect repeats and SNP discovery
    </title>
    <para>
      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.
    </para>
    <para>
      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.
    </para>
    <para>
      All you need to do to enable this feature is to set
      <arg>-CO:mr=yes</arg> (which is standard in all
      <literal>--job=...</literal> incantations of <command>mira</command> and
      in some steps of <command>miraSearchESTSNPs</command>. Furthermore, you
      will need to provide <emphasis>strain information</emphasis>, either in
      the manifest file or in ancillary NCBI TRACEINFO XML files.
    </para>
    <para>
      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 <literal>A</literal> at a given position, the other
      three a <literal>C</literal>.
    </para>
    <screen>
R1   ......A......
R2   ......A......
R3   ......A......
R4   ......C......
R5   ......C......
R6   ......C......</screen>
    <note>
      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:
      <arg>-CO:mrpg:mnq:mgqrt:emea:amgb:amgbemc:amgbnbs</arg>
    </note>
    <para>
      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:
    </para>
    <screen>
Contig1:
R1   ......A......
R2   ......A......
R3   ......A......

Contig2:
R4   ......C......
R5   ......C......
R6   ......C......</screen>
    <para>
      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.
    </para>
    <para>
      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:
    </para>
    <screen>
R1 (hum)  ......<emphasis role="bold">A</emphasis>......
R2 (hum)  ......<emphasis role="bold">A</emphasis>......
R3 (hum)  ......<emphasis role="bold">A</emphasis>......
R4 (chi)  ......<emphasis role="bold">C</emphasis>......
R5 (chi)  ......<emphasis role="bold">C</emphasis>......
R6 (chi)  ......<emphasis role="bold">C</emphasis>......</screen>
    <para>
      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 (<emphasis
      role="bold">S</emphasis>NP inte<emphasis role="bold">R</emphasis>
      <emphasis role="bold">O</emphasis>rganisms) tell you: there's a SNP
      between those two (or multiple) strains/organisms/whatever.
    </para>
    <para>
      Changing the above example a little, assume you have this assembly early
      on during the MIRA process:
    </para>
    <screen>
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......</screen>
    <para>
      Because "chimp" has a SNP within itself (<literal>A</literal> versus
      <literal>C</literal>) and there's a SNP between "human" and "chimp"
      (also <literal>A</literal> versus <literal>C</literal>), MIRA will see a
      problem and set a tag, this time a SIOr tag: <emphasis
      role="bold">S</emphasis>NP <emphasis role="bold">I</emphasis>ntra- and
      inter <emphasis role="bold">O</emphasis>rganism.
      </para>
      <para>
	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:
    </para>
    <screen>
Contig1:
R1 (hum)  ......<emphasis role="bold">A</emphasis>......
R2 (hum)  ......<emphasis role="bold">A</emphasis>......
R3 (hum)  ......<emphasis role="bold">A</emphasis>......
R4 (chi)  ......<emphasis role="bold">A</emphasis>......
R5 (chi)  ......<emphasis role="bold">A</emphasis>......
R6 (chi)  ......<emphasis role="bold">A</emphasis>......

Contig2:
R7 (chi)  ......<emphasis role="bold">C</emphasis>......
R8 (chi)  ......<emphasis role="bold">C</emphasis>......
R9 (chi)  ......<emphasis role="bold">C</emphasis>......</screen>
    <para>
      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.
    </para>
    <para>
      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:
    </para>
    <screen>
R1 (hum)  ......A...T......
R2 (hum)  ......A...G......
R3 (hum)  ......A...T......
R4 (chi)  ......C...G......
R5 (chi)  ......C...T......
R6 (chi)  ......C...G......</screen>
    <para>
      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:
    </para>
    <screen>
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......</screen>
  </sect1>
  <sect1 id="sect_ref_data_reduction">
    <title>
      Data reduction: subsampling vs. lossless digital normalisation
    </title>
    <para>
      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).
    </para>
    <para>
      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.
    </para>
    <itemizedlist>
      <listitem>
	<para>
	  <emphasis>Subsampling</emphasis> is a process to create a smaller,
	  hopefully representative set from a larger data set.
	</para>
	<para>
	  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 <emphasis>n</emphasis> 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.
	</para>
	<para>
	  Subsampling must be done by the user prior to assembly with MIRA.
	</para>
	<para>
	  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 dependent 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
	  &ge; 100,000x or even a million x.
	</para>
	<para>
	  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.
	</para>
      </listitem>
      <listitem>
	<para>
	  <emphasis>Digital normalisation</emphasis> is a process to perform a
	  reduction of sequencing data redundancy. It was made known to a
	  wider audience by the paper <emphasis>"A Reference-Free Algorithm
	  for Computational Normalization of Shotgun Sequencing
	  Data"</emphasis> by Brown et al. (see
	  <ulink url="http://arxiv.org/abs/1203.4802"/>).
	</para>
	<para>
	  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.
	</para>
	<para>
	  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.
	</para>
	<para>
	  MIRA implements a variant of the algorithm: the <emphasis>lossless
	  digital normalisation</emphasis>. 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.
	</para>
	<para>
	  Digital normalisation should not be done prior to an assembly with
	  MIRA, rather the MIRA parameter to perform a digital normalisation
	  on the complete data set should be used.
	</para>
	<para>
	  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.
	</para>
	<note>
	  <para>
	    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.
	  </para>
	  <para>
	    Due to the digital
	    normalisation step, the coverage numbers in the info file
	    regarding contig statistics will not represent 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.
	</para>
	</note>
      </listitem>
    </itemizedlist>
  </sect1>
  <sect1 id="sect_ref_caveats">
    <title>
      Caveats
    </title>
    <sect2 id="sect_ref_using_artificial_reads">
      <title>
	Using data not from sequencing instruments: artificial / synthetic reads
      </title>
      <para>
	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.
      </para>
      <para>
	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
	insurance algorithms of MIRA might spot that they "look funny" and
	trim back these artificial reads ... sometimes even removing them
	completely.
      </para>
      <note>
	<title>Summary tips for creating artificial reads for MIRA assemblies</title>
	<para>
	  The following should lead to the least amount of surprises for most
	  assembly use cases when calling MIRA only with the most basic
	  switches <literal>--project=... --job=...</literal>
	</para>
	<orderedlist>
	  <listitem>
	    <emphasis role="bold">Length:</emphasis> between 50 and 20000 bp
	  </listitem>
	  <listitem>
	    <emphasis role="bold">Quality values:</emphasis> give your
	    artificial reads quality values. Using <emphasis>30</emphasis>
	    as quality value for your bases should be OK for most
	    applications.
	  </listitem>
	  <listitem>
	    <emphasis role="bold">Orientation:</emphasis> for every read you
	    create, create a read with the same data (bases and quality
	    values) in reverse complement direction.
	  </listitem>
	</orderedlist>
      </note>
      <para>
	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:
      </para>
      <itemizedlist>
	<listitem>
	  <para>
	    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).
	  </para>
	  <para>
	    The MIRA <emphasis>proposed end clipping</emphasis> algorithm
	    <arg>-CL:pec</arg> 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.
	  </para>
	  <para>
	    If you use only artificial reads in an assembly, then switch off
	    the <emphasis>proposed end clipping</emphasis>
	    <arg>-CL:pec=no</arg>.
	  </para>
	  <para>
	    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.
	  </para>
	</listitem>
	<listitem>
	  <para>
	    Sequencing type/technology: MIRA currently knows Sanger, 454, Ion
	    Torrent, Solexa, PacBioHQ/LQ and "Text" as sequencing
	    technologies, every read entered in an assembly must be one of
	    those.
	  </para>
	  <para>
	    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.
	  </para>
	</listitem>
	<listitem>
	  <para>
	    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 <arg>-CL:qc:bsqc</arg> as well as to
	    <arg>-CO:mrpg:mnq:mgqrt</arg>.
	  </para>
	</listitem>
	<listitem>
	  <para>
	    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.
	  </para>
	</listitem>
      </itemizedlist>
    </sect2>
    <sect2 id="sect_ref_ploidy_and_repeats">
      <title>
	Ploidy and repeats
      </title>
      <para>
	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.
      </para>
      <para>
	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.
      </para>
      <para>
	If someone has a good idea, I'll be happy to hear it.
      </para>
    </sect2>
    <sect2 id="sect_ref_handling_of_repeats">
      <title>
	Handling of repeats
      </title>
      <para>
      </para>
      <sect3 id="sect_ref_uniform_read_distribution">
	<title>
	  Uniform read distribution
	</title>
	<para>
	  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 over-compression of repeats during the
	  contig building phase and keeps reads in reserve for other copies of
	  that repeat.
	</para>
	<para>
	  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.
	</para>
	<para>
	  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
	</para>
	<para>
	  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:
	</para>
	<para>
	  (Note: <emphasis>p</emphasis> is the parameter <arg>-AS:urdsip</arg>)
	</para>
	<para>
	  Pass 1 to <emphasis>p-1</emphasis>: MIRA happily assembles everything together and calculates a
	  number of different things, amongst them an average coverage of ~8. At the
	  end of pass <emphasis>p-1</emphasis>, it will announce this average coverage as first estimate
	  to the assembly process.
	</para>
	<para>
	  Pass <emphasis>p</emphasis>: 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 <arg>-AS:ardct</arg> 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.
	</para>
	<para>
	  Pass <emphasis>p+1</emphasis> 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 over-stack by an average
	  coverage multiplied by a safety value (<arg>-AS:urdcm</arg>) 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.
	</para>
	<para>
	  Tough luck. I do have ideas on how to re-integrate 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.
	</para>
	<para>
	  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.
	</para>
      </sect3>
      <sect3 id="sect_ref_keeping_'long'_repetitive_contigs_separate">
	<title>
	  Keeping 'long' repetitive contigs separate
	</title>
	<para>
	  MIRA had since 2.9.36 a feature to keep long repeats in separate
	  contigs. Due to algorithm changes, this feature is now standard. The
	  effect of this is that contigs with non-repetitive sequence will
	  stop at a 'long repeat' border which cannot be crossed by a single
	  read or by paired reads, including only the first few bases of the
	  repeat. Long repeats will be kept as separate contigs.
	</para>
	<para>
	  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.
	</para>
	<para>
	  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. Basically -for shotgun assemblies - the mean
	  length of the reads that go into the assembly defines the minimum
	  length of 'long' repeats that have to be kept in separate contigs.
	</para>
	<para>
	  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 frequently integrated into 'normal' contigs as MIRA
	  can correctly place them most of the time.
	</para>
      </sect3>
      <sect3 id="sect_ref_helping_finishing_by_tagging_reads_with_haf_tags">
	<title>
	  Helping finishing by tagging reads with HAF tags
	</title>
	<para>
	  HAF tags (HAsh Frequency) are set by MIRA when the option to colour reads by
	  kmer frequency (<arg>-GE:crkf</arg>, on by default in most --job combinations)
	  is on. These tags show the status of k-mers (stretch of bases of given length
	  <emphasis>k</emphasis>) in read sequences: whether MIRA recognised them as being present in
	  sub-average, average, above average or repetitive numbers.
	</para>
	<para>
	  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.
	</para>
	<para>
	  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.
	</para>
	<itemizedlist>
	  <listitem>
	    <para>
	      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.
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      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).
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      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.
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      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.
	    </para>
	  </listitem>
	</itemizedlist>
	<para>
	</para>
	<para>
	  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.
	</para>
	<itemizedlist>
	  <listitem>
	    <para>
	      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.
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      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.
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      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 several other
	      contigs. If not, joining is probably the way to go. If potential
	      joins exist with several other contigs, then it's a repeat (see
	      below).
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      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.
	    </para>
	  </listitem>
	</itemizedlist>
	<para>
	</para>
      </sect3>
    </sect2>
    <sect2 id="sect_ref_consensus_in_finishing_programs_gap4_consed_">
      <title>
	Consensus in finishing programs (gap4, consed, ...)
      </title>
      <para>
	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.
      </para>
      <para>
	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.
      </para>
      <para>
	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
	miraconvert (from the MIRA package ) with the "-r" option to
	recalculate the optimal consensus of your finished project.
      </para>
      <para>
	E.g., assuming you have just finished editing the gap4 database
	<filename>DEMO.3</filename>, do the following. First, export the gap4 database back to
	CAF:
      </para>
      <screen>
<prompt>$</prompt> <userinput>gap2caf -project DEMO -version 3 &gt;demo3.caf</userinput></screen>
      <para>
      </para>
      <para>
	Then, use<command>miraconvert</command> <emphasis>with</emphasis> <emphasis>option</emphasis> <emphasis>'-r'</emphasis> to
	convert it into any other format that you need. Example for converting to a
	CAF and a FASTA format with correct consensus:
      </para>
      <screen>
<prompt>$</prompt> <userinput>miraconvert -t caf -t fasta -r c demo3.caf final_result</userinput></screen>
      <para>
      </para>
    </sect2>
    <sect2 id="sect_ref_some_other_things_to_consider">
      <title>
	Some other things to consider
      </title>
      <para>
      </para>
      <itemizedlist>
	<listitem>
	  <para>
	    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 <arg>-caf</arg> option to load.
	  </para>
	</listitem>
	<listitem>
	  <para>
	    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 <arg>-CL:pvc</arg> and <arg>-CO:emea</arg> to address
	    problem with incomplete clipping of sequencing vectors. Also having the
	    assembler work with less strict parameters may help out of this.
	  </para>
	</listitem>
	<listitem>
	  <para>
	    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:
	  </para>
	  <orderedlist>
	    <listitem>
	      <para>
		Problems which might arise with 'unnatural' long sequence
		reads: 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 95 MiB, two reads with 50000 bases will need 9.5 GiB.
	      </para>
	      <para>
		This problem has become acute now with PacBio, I'm working on
		it. In the mean time, current usable sequence length of PacBio
		are more in the 3 to 4 kilobase range, with only a few reads
		attaining or surpassing 20 kb. So Todays' machines should
		still be able to handle the problem more or less effortlessly.
	      </para>
	    </listitem>
	    <listitem>
	      <para>
		32 bit versions of MIRA are not supported anymore.
	      </para>
	    </listitem>
	    <listitem>
	      <para>
		to reduce memory overhead, the following assumptions have been made:
	      </para>
	    </listitem>
	    <listitem>
	      <para>
		MIRA is not fully multi-threaded (yet), though most
		bottlenecks are now in code areas which cannot be
		multi-threaded by algorithm design.
	      </para>
	    </listitem>
	  </orderedlist>
	</listitem>
	<listitem>
	  <para>
	    a project does not contain sequences from more than 255 different:
	  </para>
	  <itemizedlist>
	    <listitem>
	      <para>
		sequencing machine types
	      </para>
	    </listitem>
	    <listitem>
	      <para>
		primers
	      </para>
	    </listitem>
	    <listitem>
	      <para>
		strains (in mapping mode: 7)
	      </para>
	    </listitem>
	    <listitem>
	      <para>
		base callers
	      </para>
	    </listitem>
	    <listitem>
	      <para>
		dyes
	      </para>
	    </listitem>
	    <listitem>
	      <para>
		process status
	      </para>
	    </listitem>
	  </itemizedlist>
	</listitem>
	<listitem>
	  <para>
	    a project does not contain sequences from more than 65535 different
	  </para>
	  <itemizedlist>
	    <listitem>
	      <para>
		clone vectors
	      </para>
	    </listitem>
	    <listitem>
	      <para>
		sequencing vectors
	      </para>
	    </listitem>
	  </itemizedlist>
	</listitem>
      </itemizedlist>
    </sect2>
  </sect1>
  <sect1 id="sect_ref_things_you_should_not_do">
    <title>
      Things you should not do
    </title>
    <para>
    </para>
    <sect2 id="sect_ref_never_on_nfs">
      <title>
	Do not run MIRA on NFS mounted directories without redirecting the tmp directory
      </title>
      <para>
	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 <arg>-NW:cnfs=warn</arg>
	(<arg>-NW:cnfs=no</arg>), but you have been warned.
      </para>
      <para>
	In case you want to keep input and output files on NFS, you can use
	<arg>-DI:trt</arg> to redirect the tmp directory to a local
	filesystem. Then MIRA will run at almost full speed.
      </para>
    </sect2>
    <sect2 id="sect_ref_never_without_quality_values">
      <title>
	Do not assemble without quality values
      </title>
      <para>
	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 <emphasis>might</emphasis> get down safely, but
	experience tells the result will rather be a bloody mess.
      </para>
      <para>
	Well, assembling without quality values is a bit like above, but
	bloodier. And the worst: you (or the people using the results of such
	an assembly) will notice the gore only until it is way too late and
	money has been sunk in follow-up experiments based on wrong data.
      </para>
      <para>
	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.
      </para>
      <para>
	Now, there are <emphasis role="bold">very rare occasions</emphasis>
	where getting quality values is not possible. If you absolutely cannot
	get them, and I mean only in this case, use the following
	switch:<literal>--noqualities[=SEQUENCINGTECHNOLOGY]</literal> and
	additionally give a default quality for reads of a readgroup. E.g.:
      </para>
      <screen>parameters= --noqualities=454

readgroup
technology=454
data=...
default_qual=30</screen>
      <para>
	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.
      </para>
      <warning>
	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 <arg>-CO:mrpg=4</arg> or higher. You also may want to
	tune the default quality parameter together with <arg>-CO:mnq</arg>
	and <arg>-CO:mgqrt</arg> in cases where you mix sequences with and
	without quality values.
      </warning>
    </sect2>
  </sect1>
  <sect1 id="sect_ref_useful_third_party_programs">
    <title>
      Useful third party programs
    </title>
    <para>
      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:
    </para>
    <variablelist>
      <varlistentry>
	<term>
	  HTML browser
	</term>
	<listitem>
	  <para> 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.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  Assembly viewer / finishing / preprocessing
	</term>
	<listitem>
	  <para>
	    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.).
	  </para>
	  <para>
	    See <ulink url="http://www.sourceforge.net/projects/staden/"/> for
	    further information and also a possibility to download precompiled
	    binaries for different platforms.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  Vector screening
	</term>
	<listitem>
	  <para>
	    Reading result files from <command>ssaha2</command> or
	    <command>smalt</command> 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
	    <command>lucy</command> (see below), <command>ssaha2</command> or
	    <command>smalt</command> together with the MIRA parameters for
	    SSAHA2 / SMALT support (see all <arg>-CL:msvs*</arg> parameters) and quality clipping
	    (<arg>-CL:qc</arg>) should do the trick. For reads coming from 454
	    pyro-sequencing, <command>ssaha2</command> or
	    <command>smalt</command> and the SSAHA2 / SMALT support also work
	    pretty well.
	  </para>
	  <para>
	    See
	    <ulink url="http://www.sanger.ac.uk/resources/software/ssaha2/"/>
	    and / or <ulink
	    url="http://www.sanger.ac.uk/resources/software/smalt/"/> for
	    further information and also a possibility to download the source
	    or precompiled binaries for different platforms.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  Preprocessing
	</term>
	<listitem>
	  <para> <command>lucy</command> 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.
	  </para>
	  <para>
	    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).
	  </para>
	  <para>
	    See <ulink url="ftp://ftp.tigr.org/pub/software/Lucy/"/> to download the source code
	    of lucy.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  Assembly viewer
	</term>
	<listitem>
	  <para> Viewing <filename>.ace</filename> file output without consed
	  can be done with clview from TIGR. See
	  <ulink url="http://www.tigr.org/tdb/tgi/software/"/>.
	  </para>
	  <para>
	    A better alternative is Tablet <ulink
	    url="http://bioinf.scri.ac.uk/tablet/"/> which also reads SAM
	    format.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  Assembly coverage analysis
	</term>
	<listitem>
	  <para>
	    The Integrated Genome Browser (IGB) of the GenoViz project at
	    SourceForge (<ulink
	    url="http://sourceforge.net/projects/genoviz/"/>) is just perfect
	    for loading a genome and looking at mapping coverage (provided by
	    the wiggle result files of MIRA).
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  Preprocessing (base calling)
	</term>
	<listitem>
	  <para>
	    TraceTuner (<ulink
	    url="http://sourceforge.net/projects/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.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  Preprocessing / viewing
	</term>
	<listitem>
	  <para> 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).
	  </para>
	  <para>
	    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.
	  </para>
	  <para>
	    See <ulink url="http://www.phrap.org/"/> for further information.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  text viewer
	</term>
	<listitem>
	  <para> A text viewer for the different textual output files.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>
    <para>
      As always, most of the time a combination of several different packages
      is possible. My currently preferred combo for genome projects is
      <command>ssaha2</command> or <command>smalt</command> and or
      <command>lucy</command> (vector screening), MIRA (assembly, of course)
      and gap4 (assembly viewing and finishing).
    </para>
    <para>
      For re-assembling projects that were edited in gap4, one will also need
      the gap2caf converter. The source for this is available at
      <ulink url="http://www.sanger.ac.uk/resources/software/caf.html"/>.
    </para>
  </sect1>
  <sect1 id="sect_ref_speed_and_memory_considerations">
    <title>
      Speed and memory considerations
    </title>
    <sect2 id="sect_ref_memory">
      <title>
	Estimating needed memory for an assembly project
      </title>
      <para>
	Since the V2.9.24x3 version of MIRA, there is <command>miramem</command> 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.
      </para>
      <para>
	Here's the transcript of a session with miramem:
      </para>
      <screen>
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 SourceForge ticketing
system at:
        http://sourceforge.net/p/mira-assembler/tickets/
This ensures that requests do not 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] <userinput>9.8m</userinput>
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] <userinput>y</userinput>
y
Number of 454 GS20 reads? [0]
0
Number of 454 FLX reads? [0]
0
Number of 454 Titanium reads? [0] <userinput>750k</userinput>
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:mkim, -SK:mchr (both runtime); -SK:mhpr (accuracy)
*************************************************************</screen>
      <para>
	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.
      </para>
    </sect2>
    <sect2 id="sect_ref_speed">
      <title>
	Some numbers on speed
      </title>
      <para>
	To be rewritten for MIRA4.
      </para>
    </sect2>
  </sect1>
  <sect1 id="sect_ref_known_problems_bugs">
    <title>
      Known Problems / Bugs
    </title>
    <para>
      File Input / Output:
    </para>
    <orderedlist>
      <listitem>
	<para>
	  MIRA can only read unedited EXP files.
	</para>
      </listitem>
      <listitem>
	<para>
	  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.
	</para>
      </listitem>
    </orderedlist>
    <para>
    </para>
    <para>
      Assembly process:
    </para>
    <orderedlist>
      <listitem>
	<para>
	  The routines for determining <emphasis>Repeat Marker
	  Bases</emphasis> (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
	  <arg>-CO:mrc:nrz:mgqrt:mgqwpc</arg>. Also look at <arg>-CL:pvc</arg> and
	  <arg>-CO:emea</arg> if you have a lot of sequencing vector relics at the
	  end of the sequences.
	</para>
      </listitem>
    </orderedlist>
    <para>
    </para>
  </sect1>
  <sect1 id="sect_ref_todos">
    <title>
      TODOs
    </title>
    <para>
      These are some of the topics on my TODO list for the next revisions to
      come:
    </para>
    <orderedlist>
      <listitem>
	<para>
	  Making Smith-Waterman parts of the process multi-threaded or use SIMD
	  (currently stopped due to other priorities like PacBio etc.)
	</para>
      </listitem>
    </orderedlist>
    <para>
    </para>
  </sect1>
  <sect1 id="sect_ref_working_principles">
    <title>
      Working principles
    </title>
    <para>
      Note: description is old and needs to be adapted to the current 4.x line
      of MIRA.
    </para>
    <para>
      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.
    </para>
    <para>
      This assembly approach relies on some of the automatic editing
      functionality provided by the EdIt package which has been integrated in
      parts within MIRA.
    </para>
    <para>
      This is an approximate overview on the steps that are executed while
      assembling:
    </para>
    <orderedlist>
      <listitem>
	<para>
	  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.
	</para>
      </listitem>
      <listitem>
	<para>
	  the ends of the reads are cleaned ensure they have a minimum stretch
	  of bases without sequencing errors
	</para>
      </listitem>
      <listitem>
	<para>
	  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).
	</para>
      </listitem>
      <listitem>
	<para>
	  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.
	</para>
      </listitem>
      <listitem>
	<para>
	  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.
	</para>
      </listitem>
      <listitem>
	<para>
	  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.
	</para>
      </listitem>
      <listitem>
	<para>
	  Optional: the contig can be analysed and corrected by the automatic
	  editor ("EdIt" for Sanger reads, or the new MIRA editor for 454
	  reads).
	</para>
      </listitem>
      <listitem>
	<para>
	  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).
	</para>
      </listitem>
      <listitem>
	<para>
	  Go back to step 5 if there are reads present that have not been
	  assembled into contigs.
	</para>
      </listitem>
      <listitem>
	<para>
	  Optional: Detection of spoiler reads that prevent joining of
	  contigs. Remedy by shortening them.
	</para>
      </listitem>
      <listitem>
	<para>
	  Optional: Write out a checkpoint assembly file and go back to step 2.
	</para>
      </listitem>
      <listitem>
	<para>
	  The resulting project is written out to different output files and
	  directories.
	</para>
      </listitem>
    </orderedlist>
    <para>
    </para>
  </sect1>
  <sect1 id="sect_ref_see_also">
    <title>
      See Also
    </title>
    <para>
      The other MIRA manuals and walkthroughs as well as
      <command>EdIt</command>, <command>gap4</command>,
      <command>pregap4</command>, <command>gap5</command>,
      <command>clview</command>, <command>caf2gap</command>,
      <command>gap2caf</command>, <command>ssaha2</command>,
      <command>smalt</command>, <command>compress</command> and
      <command>gzip</command>, <command>cap3</command>,
      <command>ttuner</command>, <command>phred</command>,
      <command>phrap</command>, <command>cross_match</command>,
      <command>consed</command>.
    </para>
  </sect1>
</chapter>
