SPAdes 2.5.0 Manual

1. About SPAdes
    1.1. Supported data types
    1.2. SPAdes pipeline
    1.3. SPAdes performance
2. Installation
    2.1. Downloading SPAdes Linux binaries
    2.2. Downloading SPAdes binaries for Mac
    2.3. Downloading and compiling SPAdes source code
    2.4. Verifying your installation
3. Running SPAdes
    3.1. SPAdes input
    3.2. SPAdes command line options
    3.3. Assembling long Illumina paired reads (2x150 and 2x250)
    3.4. SPAdes output
    3.5. Assembly evaluation
4. Citation
5. Feedback and bug reports

1. About SPAdes

SPAdes – St. Petersburg genome assembler – is intended for both standard isolates and single-cell MDA bacteria assemblies. This manual will help you to install and run SPAdes. SPAdes version 2.5.0 was released under GPLv2 on July 4, 2013 and can be downloaded from http://bioinf.spbau.ru/spades.

1.1 Supported data types

The current version of SPAdes works only with Illumina reads. Support for other technologies (e.g. Roche 454, IonTorrent, PacBio) is currently in progress and will probably be included in one of the next releases.

Version 2.5.0 of SPAdes supports paired-end reads, mate-pairs and unpaired reads. SPAdes can take as input several paired-end and mate-pair libraries simultaneously.

Also note, that SPAdes was initially designed for single-cell and standard bacterial data sets and is not intended for larger genomes (e.g. mammalian size genomes) and metagenomic projects. For such purposes you can use it at your own risk.

1.2 SPAdes pipeline

SPAdes comes in three separate modules:

We recommend to run SPAdes with BayesHammer to obtain high-quality assemblies. However, if you use your own read correction tool, it is possible to turn BayesHammer off. It is also possible to use only the read error correction stage, if you wish to use another assembler. See the SPAdes options section.

1.3 SPAdes' performance

In this section we give approximate data about SPAdes' performance on two data sets:

We ran SPAdes with default parameters using 16 threads on a server with Intel Xeon 2.27GHz processors. BayesHammer runs in approximately 1 hour and takes up to 15Gb of RAM to perform read error correction on each data set. Assembly takes 35 minutes and 4Gb of RAM for the E. coli isolate data set. The E. coli single-cell data set takes 55 minutes and 6Gb of RAM. MismatchCorrector runs for about an hour on standard E. coli, about 2 hours on the single-cell data set, and requires 8Gb of RAM. All modules also require additional disk space for temporary files. See the table below for more precise values.

Data set   E. coli isolate E. coli single-cell
Stage   Time (min)     Peak RAM  
  usage (Gb)  
  Additional  
  disk space (Gb)  
  Time (min)     Peak RAM  
  usage (Gb)  
  Additional  
  disk space (Gb)  
BayesHammer 75 14 13 75 15 13
SPAdes 35 4 8 55 6 8
MismatchCorrector 60 8 24 120 8 24

Notes:

2. Installation

SPAdes requires a 64-bit Linux system or Mac OS and Python 2.4 or higher (but not 3) to be pre-installed on it. To obtain SPAdes you can either download binaries or download source code and compile it yourself.

2.1 Downloading SPAdes Linux binaries

To download SPAdes Linux binaries and extract them, go to the directory in which you wish SPAdes to be installed and run:


    wget http://spades.bioinf.spbau.ru/release2.5.0/SPAdes-2.5.0-Linux.tar.gz
    tar -xzf SPAdes-2.5.0-Linux.tar.gz
    cd SPAdes-2.5.0-Linux/bin/

In this case you do not need to run any installation scripts – SPAdes is ready to use. The following files will be placed in the bin directory:

We also suggest adding SPAdes installation directory to the PATH variable.

2.2 Downloading SPAdes binaries for Mac

To obtain SPAdes binaries for Mac, go to the directory in which you wish SPAdes to be installed and run:


    curl http://spades.bioinf.spbau.ru/release2.5.0/SPAdes-2.5.0-Darwin.tar.gz -o SPAdes-2.5.0-Darwin.tar.gz
    tar -zxvf SPAdes-2.5.0-Darwin.tar.gz
    cd SPAdes-2.5.0-Darwin/bin/

Just as in Linux, SPAdes is ready to use and no further installation steps are required. You will get the same files in the bin directory:

We also suggest adding SPAdes installation directory to the PATH variable.

2.3 Downloading and compiling SPAdes source code

If you wish to compile SPAdes by yourself you will need the following libraries to be pre-installed:

If you meet these requirements, you can download the SPAdes source code:


    wget http://spades.bioinf.spbau.ru/release2.5.0/SPAdes-2.5.0.tar.gz
    tar -xzf SPAdes-2.5.0.tar.gz
    cd SPAdes-2.5.0

and build it with the following script:


    ./spades_compile.sh

SPAdes will be built in the directory ./bin. If you wish to install SPAdes into another directory, you can specify full path of destination folder by running the following command in bash or sh:


    PREFIX=<destination_dir> ./spades_compile.sh

for example:


    PREFIX=/usr/local ./spades_compile.sh

which will install SPAdes into /usr/local/bin.

After installation you will get the same files in ./bin (or <destination_dir>/bin if you specified PREFIX) directory:

We also suggest adding SPAdes installation directory to the PATH variable.

2.4 Verifying your installation

For testing purposes, SPAdes comes with a toy data set (reads that align to first 1000 bp of E. coli). To try SPAdes on this data set, run:


    <spades installation dir>/spades.py --test

If you added SPAdes installation directory to the PATH variable, you can run:


    spades.py --test

For the simplicity we further assume that SPAdes installation directory is added to the PATH variable.

If the installation is successful, you will find the following information at the end of the log:


 * Corrected reads are in spades_test/corrected/
 * Assembled contigs are in spades_test/contigs.fasta
 * Assembled scaffolds are in spades_test/scaffolds.fasta

Thank you for using SPAdes!

======= SPAdes pipeline finished. Log can be found here: spades_test/spades.log

3. Running SPAdes

3.1 SPAdes input

SPAdes takes as input paired-end reads, mate-pairs and single (unpaired) reads in FASTA or FASTQ format. However, in order to run read error correction, reads should be in FASTQ format.

By using command line interface, you can specify up to five different paired-end libraries and also up to five different mate-pair ones. If you wish to use more, you can use YAML data set file. The number of unpaired libraries is unlimited. SPAdes 2.5 should not be used if only mate-pair libraries are available. We further refer to paired-end and mate-pair libraries simply as to read-pair libraries.

By default, SPAdes assumes that paired-end reads have forward-reverse (fr) orientation and mate-pairs have reverse-forward (rf) orientation. However, different orientations can be set for any library by using SPAdes options.

To distinguish reads in pairs we refer to them as left and right reads. For forward-reverse orientation, the forward reads correspond to the left reads and the reverse reads, to the right. Similarly, in reverse-forward orientation left and right reads correspond to reverse and forward reads, respectively, etc.

Each read-pair library can be stored in several files or several pairs of files. Paired reads can be organized in two different ways:

For example, Illumina produces paired-end reads in two files: s_1_1_sequence.txt and s_1_2_sequence.txt. If you choose to store reads in file pairs make sure that for every read from s_1_1_sequence.txt the corresponding paired read from s_1_2_sequence.txt is placed in the respective paired file on the same line number. If you choose to use merged files, every read from s_1_1_sequence.txt should be followed by the corresponding paired read from s_1_2_sequence.txt.

Note that SPAdes also accepts gzip-compressed files.

3.2 SPAdes command line options

To run SPAdes from the command line, type


    spades.py [options] -o <output_dir>

Note that we assume that SPAdes installation directory is added to the PATH variable (provide full path to SPAdes executable otherwise: <spades installation dir>/spades.py).

Basic options

-o <output_dir>
    Specify the output directory. Required option.

--sc
    This flag is required for MDA (single-cell) data.

--test
    Runs SPAdes on the toy data set; see section 2.3.

-h (or --help)
    Prints help.

Pipeline options

--only-error-correction
    Performs read error correction only.

--only-assembler
    Runs assembly module only.

--careful
    Tries to reduce the number of mismatches and short indels. Also runs MismatchCorrector – a post processing tool, which uses
BWA tool (comes with SPAdes). This option is recommended.

--disable-gzip-output
    Forces read error correction module not to compress the corrected reads. If this options is not set, corrected reads will be in *.fastq.gz format.

--rectangles
    Uses the rectangle graph algorithm for repeat resolution stage instead of the usual SPAdes repeat resolution module (experimental).

Input data

  Specifying one library (previously used format)

--12 <file_name>
    File with interlaced forward and reverse paired-end reads.

-1 <file_name>
    File with forward reads.

-2 <file_name>
    File with reverse reads.

-s <file_name>
    File with unpaired reads.

  Specifying multiple libraries (new format)

--pe<#>-12 <file_name>
    File with interlaced reads for paired-end library number <#> (<#> = 1,2,3,4,5). For example, for the first paired-end library the option is: --pe1-12 <file_name>

--pe<#>-1 <file_name>
    File with left reads for paired-end library number <#> (<#> = 1,2,3,4,5).

--pe<#>-2 <file_name>
    File with right reads for paired-end library number <#> (<#> = 1,2,3,4,5).

--pe<#>-s <file_name>
    File with unpaired reads from paired-end library number <#> (<#> = 1,2,3,4,5)
    For example, paired reads can become unpaired during the error correction procedure.

--pe<#>-<or> <file_name>
    Orientation of reads for paired-end library number <#> (<#> = 1,2,3,4,5; <or> = "fr","rf","ff").
    The default orientation for paired-end libraries is forward-reverse. For example, to specify reverse-forward orientation for the second paired-end library, you should use the flag: --pe2-rf

--mp<#>-12 <file_name>
    File with interlaced reads for mate-pair library number <#> (<#> = 1,2,3,4,5).

--mp<#>-1 <file_name>
    File with left reads for mate-pair library number <#> (<#> = 1,2,3,4,5).

--mp<#>-2 <file_name>
    File with right reads for mate-pair library number <#> (<#> = 1,2,3,4,5).

--mp<#>-<or> <file_name>
    Orientation of reads for mate-pair library number <#> (<#> = 1,2,3,4,5; <or> = "fr","rf","ff").
    The default orientation for mate-pair libraries is reverse-forward. For example, to specify forward-forward orientation for the first mate-pair library, you should use the flag: --mp1-ff

  Specifying input data with YAML data set file (advanced)

An alternative way to specify an input data set for SPAdes is to create a YAML data set file. By using a YAML file you can provide an unlimited number of paired-end, mate-pair and unpaired libraries. Basically, YAML data set file is a text file, in which input libraries are provided as a comma-separated list in square brackets. Each library is provided in braces as a comma-separated list of attributes. The following attributes are available:

To properly specify a library you should provide its type and at least one file with reads. Orientation is an optional attribute. Its default value is "fr" (forward-reverse) for paired-end libraries and "rf" (reverse-forward) for mate-pair libraries.

The value for each attribute is given after a colon. Comma-separated lists of files should be given in square brackets. For each file you should provide its full path in double quotes. Make sure that files with right reads are given in the same order as corresponding files with left reads.

For example, if you have one paired-end library splitted into two pairs of files:


    lib_pe1_left_1.fastq
    lib_pe1_right_1.fastq
    lib_pe1_left_2.fastq
    lib_pe1_right_2.fastq

and one mate-pair library:

    lib_mp1_left.fastq
    lib_mp1_right.fastq

YAML file should look like this:

    [
      {
        orientation: "fr",
        type: "paired-end",
        right reads: [
          "/FULL_PATH_TO_DATASET/lib_pe1_right_1.fastq",
          "/FULL_PATH_TO_DATASET/lib_pe1_right_2.fastq" 
        ],
        left reads: [
          "/FULL_PATH_TO_DATASET/lib_pe1_left_1.fastq",
          "/FULL_PATH_TO_DATASET/lib_pe1_left_2.fastq" 
        ]
      },
      {
        orientation: "rf",
        type: "mate-pairs",
        right reads: [
          "/FULL_PATH_TO_DATASET/lib_mp1_right.fastq" 
        ],
        left reads: [
          "/FULL_PATH_TO_DATASET/lib_mp1_left.fastq"
        ]
      }
    ]

Once you have created a YAML file save it with .yaml extension (e.g. as my_data_set.yaml) and run SPAdes using the --dataset option:
--dataset <your YAML file>

Note that the --dataset option cannot be used with any other options for specifying input data.

Advanced options

-t <int> (or --threads <int>)
    Number of threads. The default value is 16.

-m <int> (or --memory <int>)
    Set memory limit in Gb. SPAdes terminates if it reaches this limit. The default value is 250 Gb. Actual amount of consumed RAM will be below this limit.

--tmp-dir <dir_name>
    Set directory for temporary files from read error correction. The default value is <output_dir>/corrected/tmp

-k <int,int,...>
    Comma-separated list of k-mer sizes to be used (all values must be odd, less than 128 and listed in ascending order). The default value is 21,33,55.

--phred-offset <33 or 64>
    PHRED quality offset for the input reads, can be either 33 or 64. It will be auto-detected if it is not specified.

--debug
    Runs SPAdes in debug mode, keeping intermediate results.

Examples

To test the toy data set, you can also run the following command from the SPAdes bin directory:


    spades.py --pe1-1 ../share/spades/test_dataset/ecoli_1K_1.fq.gz \
    --pe1-2 ../share/spades/test_dataset/ecoli_1K_2.fq.gz -o spades_test

If you have your library separated into several pairs of files, for example:


    lib1_forward_1.fastq
    lib1_reverse_1.fastq
    lib1_forward_2.fastq
    lib1_reverse_2.fastq

make sure that corresponding files are given in the same order:


    spades.py --pe1-1 lib1_forward_1.fastq --pe1-2 lib1_reverse_1.fastq \
    --pe1-1 lib1_forward_2.fastq --pe1-2 lib1_reverse_2.fastq \
    -o spades_output

Files with interlacing paired-end reads or files with unpaired reads can be specified in any order with one file per option, for example:


    spades.py --pe1-12 lib1_1.fastq --pe1-12 lib1_2.fastq \
    --pe1-s lib1_unpaired_1.fastq --pe1-s lib1_unpaired_2.fastq \
    -o spades_output    

If you have several paired-end and mate-pair reads, for example:

  • paired-end library 1
    
        lib_pe1_left.fastq
        lib_pe1_right.fastq
    
    

  • mate-pair library 1
    
        lib_mp1_left.fastq
        lib_mp1_right.fastq
    
    

  • mate-pair library 2
    
        lib_mp2_left.fastq
        lib_mp2_right.fastq
    
    

    make sure that files corresponding to each library are grouped together:

    
        spades.py --pe1-1 lib_pe1_left.fastq --pe1-2 lib_pe1_right.fastq \
        --mp1-1 lib_mp1_left.fastq --mp1-2 lib_mp1_right.fastq \
        --mp2-1 lib_mp2_left.fastq --mp2-2 lib_mp2_right.fastq \
        -o spades_output
    
    

    All options for specifying input data can be mixed if needed, but make sure that files for each library are grouped and files with left and right paired reads are listed in the same order.

    3.3 Assembling long Illumina paired reads (2x150 and 2x250)

    Recent advances in DNA sequencing technology have led to a rapid increase in read length. Nowadays, it is a common situation to have a data set consisting of 2x150 or 2x250 paired-end reads produced by Illumina MiSeq or HiSeq2500. However, the use of longer reads alone will not automatically improve assembly quality. An assembler that can properly take advantage of them is needed.

    SPAdes' use of iterative k-mer lengths allows benefiting from the full potential of the long paired-end reads. Currently one has to set the assembler options up manually, but we plan to incorporate automatic calculation of necessary options soon.

    Please note that in addition to the read length, the insert length also matters a lot. It is suboptimal to sequence a 300bp fragment into a pair of 250bp reads. We suggest using 350-500 bp fragments with 2x150 reads and 550-700 bp fragments with 2x250 reads.

    Multi-cell data set with read length 2x150

    Make sure your reads are corrected prior to assembly with Quake (recommended), or BayesHammer (integrated into SPAdes pipeline).

    The default selection of k-mer lengths is 21, 33, 55 and might work well. If you have enough coverage (50x+), then you may want to try to set k-mer lengths of 21, 33, 55, 77.

    Make sure you run assembler with the --careful option to minimize number of mismatches in the final contigs.

    We recommend that you check the SPAdes log file at the end of the each iteration to control the average coverage of the contigs.

    For reads corrected prior to running the assembler:

    
        spades.py -k 21,33,55,77 --careful --only-assembler <your reads> -o spades_output
    
    

    To correct and assemble the reads:

    
        spades.py -k 21,33,55,77 --careful r <your reads> -o spades_output
    
    

    Multi-cell data set with read lengths 2 x 250

    Make sure your reads are corrected prior to assembly with Quake (recommended), or BayesHammer (integrated into SPAdes pipeline).

    By default we suggest to increase k-mer lengths in increments of 22 until the k-mer length reaches 127. The exact length of the k-mer depends on the coverage: k-mer length of 127 corresponds to 50x k-mer coverage and higher.

    Make sure you run assembler with --careful option to minimize number of mismatches in the final contigs.

    We recommend you to check the SPAdes log file at the end of the each iteration to control the average coverage of the contigs.

    For reads corrected prior to running the assembler:

    
        spades.py -k 21,33,55,77,99,127 --careful --only-assembler <your reads> -o spades_output
    
    

    To correct and assemble the reads:

    
        spades.py -k 21,33,55,77,99,127 --careful r <your reads> -o spades_output
    
    

    Single-cell data set with read lengths 2 x 150 or 2 x 250

    The default options are recommended.

    However, it might be tricky to fully utilize the advantages of long reads you have. Consider contacting us for more information and to discuss assembly strategy.

    3.4 SPAdes output

    SPAdes stores all output files in <output_dir> , which is set by the user.

    Notes:

    The full list of <output_dir> content is presented below:

        contigs.fastaresulting contigs
        scaffolds.fastaresulting scaffolds (will not be produced if input reads are unpaired)
    
        corrected/files from read error correction
            configs/configuration files for read error correction
            dataset.infointernal configuration file
            Output files with corrected reads
    
        params.txtinformation about SPAdes parameters in this run
        spades.logSPAdes log
        dataset.infointernal configuration file
        input_dataset.yamlinternal YAML data set file
        K<##>/directory containing files from the run with K=<##> (K21, K33 and K55 are created by default)
    

    SPAdes will overwrite these files and directories if they exist in the specified <output_dir>.

    3.5 Assembly evaluation

    QUAST may be used to generate summary statistics (N50, maximum contig length, GC %, # genes found in a reference list or with built-in gene finding tools, etc.) for a single assembly. It may also be used to compare statistics for multiple assemblies of the same data set (e.g., SPAdes run with different parameters, or several different assemblers).

    4. Citation

    If you use SPAdes in your research, please include Bankevich, Nurk et al., 2012 in your reference list.

    In addition, we would like to list your publications that use our software on our website. Please email the reference, the name of your lab, department and institution to spades.support@bioinf.spbau.ru.

    5. Feedback and bug reports

    Your comments, bug reports, and suggestions are very welcomed. They will help us to further improve SPAdes.

    If you have trouble running SPAdes, please provide us with the files params.txt and spades.log from the directory <output_dir>.

    Address for communications: spades.support@bioinf.spbau.ru.