BinSPreader: early access version

Description

BinSPreader is a novel tool that attempts to refine metagenome-assembled genomes (MAGs) obtained from existing tools. BinSPreader exploits the assembly graph topology and other connectivity information, such as paired-end and Hi-C reads, to refine the existing binning, correct binning errors, propagate binning from longer contigs to shorter contigs and infer contigs belonging to multiple bins.

Availability

BinSPreader is implemented on top of SPAdes and will be available soon as a part of SPAdes package.
For more instructions on BinSPreader usage please go to README.md in the downloaded zip archive and consult the main SPAdes page for system requirements and build instructions.

Alternatively, one can install BinSPreader via bioconda.

Input

The tool requires initial binning to refine, as well as assembly graph as a source of information for refining. Optionally, BinSPreader can be provided with multiple Hi-C and/or paired-end libraries.

Required positional arguments:

• Assembly graph file in GFA 1.0 format, with scaffolds included as path lines. Alternatively, scaffold paths can be provided separately using --path option in the .paths format accepted by Bandage (see Bandage wiki) for details).
• Binning output from an existing tool (in .tsv format). Every line should contain <contig_id>\t<bin_id>, where <contig_id> corresponds to one of the scaffolds from the input assembly graph. The example is given below.

Synopsis: bin-refine <graph (in GFA)> <binning (in .tsv)> <output directory> [OPTION...]

Let GFA file with the input assembly graph consist of the following lines:

S  edge_1  <sequence_1>
S  edge_2  <sequence_2>
S  edge_3  <sequence_3>
S  edge_4  <sequence_4>
S  edge_5  <sequence_5>
L  edge_1  +  edge_5  +  55M
L  edge_3  +  edge_5  +  55M
L  edge_5  +  edge_2  +  55M
L  edge_5  +  edge_4  +  55M
P  contig_1  edge_1+,edge_5+,edge_2+  *
P  contig_2  edge_3+  *
P  contig_3  edge_4+  *

Then this would be an acceptable initial binning file:

> contig_1  bin_1
> contig_2  bin_2
> contig_3  bin_2

Paired-end\Hi-C libraries

BinSPreader currently supports multiple paired-end or Hi-C libraries described in a YAML file. YAML file can be provided using –dataset option. For example, if you have one paired-end library split into two sets of files

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

and one Hi-C library

    lib_hic1_left.fastq
    lib_hic1_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: "fr",
      type: "paired-end",
      right reads: [
        "/FULL_PATH_TO_DATASET/lib_hic1_right.fastq" 
      ],
      left reads: [
        "/FULL_PATH_TO_DATASET/lib_hic1_left.fastq"
      ]
    }
  ]

BinSPreader output

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

• <output_dir>/binning.tsv contains refined binning in .tsv format
• <output_dir>/bin_stats.tsv contains various per-bin statistics
• <output_dir>/bin_weights.tsv contains soft bin weights per contig
• <output_dir>/edge_weights.tsv contains soft bin weights per edge

In addition

• <output_dir>/bin_dist.tsv contains refined bin distance matrix (if --bin-dist was used)
• <output_dir>/bin_label_1.fastq, <output_dir>/bin_label_2.fastq read set for bin labeled by bin_label (if --reads was used)
• <output_dir>/pe_links.tsv list of paired-end links between assembly graph edges with weights (if --debug was used)
• <output_dir>/graph_links.tsv list of graph links between assembly graph edges with weights (if --debug was used)

BinSPreader modes

Correction/Propagation modes

BinSPreader can either propagate input binning to unbinned edges of the assembly graph, leaving the initially binned edges unchanged (propagation mode), or correct initial binning (aggressiveness of the correction depends on the -la option). Propagation and correction modes are toggled by mutual exclusive options -Rprop and -Rcorr, respectively.

Multiple binning mode

To output BinSPreader results in multiple assignment mode, where several bin labels may be assigned to a single contig, please use -m option.

Sparse mode

BinSPreader uses a special working mode of the binning refining algorithm for sparse binnings, where the
total length of initially binned contigs is significantly lower than the total assembly length. In this mode, binning propagation from initially binned edges is limited by constant graph distance threshold. Please use --sparse-propagation option to toggle sparse mode.

Contact

In case of any questions, suggestions, bug reports, please write to spades.support@cab.spbu.ru or directly to Anton Korobeynikov.

Support

If you have a problem running BinSPreader you can look for a similar issue on our GitHub repository, create a new one or write us via e-mail: spades.support@cab.spbu.ru.