Merge pull request #881 from d4straub/add-MetaBinner

d4straub · web-flow · commit 5c4f4b852ef5 · 2025-11-04T19:29:07.000+01:00
add MetaBinner
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,6 +7,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### `Added`
 
+- [#881](https://github.com/nf-core/mag/pull/881) - Add binner MetaBinner (by @d4straub, insprired by @HeshamAlmessady & @AlphaSquad)
+
 ### `Changed`
 
 ### `Fixed`
@@ -18,9 +20,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### `Dependencies`
 
-| Tool | Previous version | New version |
-| ---- | ---------------- | ----------- |
-|      |                  |             |
+| Tool       | Previous version | New version |
+| ---------- | ---------------- | ----------- |
+| MetaBinner |                  | 1.4.4-0     |
 
 ### `Deprecated`
 
diff --git a/CITATIONS.md b/CITATIONS.md
@@ -52,6 +52,10 @@
 
   > Alneberg, J., Bjarnason, B. S., de Bruijn, I., Schirmer, M., Quick, J., Ijaz, U. Z., Lahti, L., Loman, N. J., Andersson, A. F., & Quince, C. (2014). Binning metagenomic contigs by coverage and composition. Nature Methods, 11(11), 1144–1146. doi: 10.1038/nmeth.3103
 
+- [MetaBinner](https://doi.org/10.1186/s13059-022-02832-6)
+
+  > Wang Z, Huang P, You R, Sun F, Zhu S. MetaBinner: a high-performance and stand-alone ensemble binning method to recover individual genomes from complex microbial communities. Genome Biol. 2023 Jan 6;24(1):1. doi: 10.1186/s13059-022-02832-6. PMID: 36609515; PMCID: PMC9817263.
+
 - [DAS Tool](https://doi.org/10.1038/s41564-018-0171-1)
 
   > Sieber, C. M. K., et al. 2018. "Recovery of Genomes from Metagenomes via a Dereplication, Aggregation and Scoring Strategy." Nature Microbiology 3 (7): 836-43. doi: 10.1038/s41564-018-0171-1
diff --git a/README.md b/README.md
@@ -47,7 +47,7 @@ The pipeline then:
 - performs assembly using [MEGAHIT](https://github.com/voutcn/megahit) and [SPAdes](http://cab.spbu.ru/software/spades/), and checks their quality using [Quast](http://quast.sourceforge.net/quast)
 - (optionally) performs ancient DNA assembly validation using [PyDamage](https://github.com/maxibor/pydamage) and contig consensus sequence recalling with [Freebayes](https://github.com/freebayes/freebayes) and [BCFtools](http://samtools.github.io/bcftools/bcftools.html)
 - predicts protein-coding genes for the assemblies using [Prodigal](https://github.com/hyattpd/Prodigal), and bins with [Prokka](https://github.com/tseemann/prokka) and optionally [MetaEuk](https://www.google.com/search?channel=fs&client=ubuntu-sn&q=MetaEuk)
-- performs metagenome binning using [MetaBAT2](https://bitbucket.org/berkeleylab/metabat/src/master/), [MaxBin2](https://sourceforge.net/projects/maxbin2/), [CONCOCT](https://github.com/BinPro/CONCOCT), and/or [COMEBin](https://github.com/ziyewang/COMEBin)
+- performs metagenome binning using [MetaBAT2](https://bitbucket.org/berkeleylab/metabat/src/master/), [MaxBin2](https://sourceforge.net/projects/maxbin2/), [CONCOCT](https://github.com/BinPro/CONCOCT), [COMEBin](https://github.com/ziyewang/COMEBin), and/or [MetaBinner](https://github.com/ziyewang/MetaBinner)
 - checks the quality of the genome bins using [Busco](https://busco.ezlab.org/), [CheckM](https://ecogenomics.github.io/CheckM/), or [CheckM2](https://github.com/chklovski/CheckM2) and optionally [GUNC](https://grp-bork.embl-community.io/gunc/)
 - Performs ancient DNA validation and repair with [pyDamage](https://github.com/maxibor/pydamage) and [freebayes](https://github.com/freebayes/freebayes)
 - optionally refines bins with [DAS Tool](https://github.com/cmks/DAS_Tool)
diff --git a/bin/create_metabinner_bins.py b/bin/create_metabinner_bins.py
@@ -0,0 +1,45 @@
+#!/usr/bin/env python
+
+## Originally written by Hesham Almessady (@HeshamAlmessady) and Adrian Fritz (@AlphaSquad) in https://github.com/hzi-bifo/mag and released under the MIT license.
+## See git repository (https://github.com/nf-core/mag) for full license text.
+
+import sys
+import os
+from Bio import SeqIO
+
+def main():
+    # Argument parsing
+    if len(sys.argv) != 6:
+        print("Usage: python create_metabinner_bins.py <binning_file> <fasta_file> <output_path> <prefix> <length_threshold>")
+        sys.exit(1)
+
+    binning = sys.argv[1]
+    fasta = sys.argv[2]
+    path = sys.argv[3]
+    prefix = sys.argv[4]
+    length = int(sys.argv[5])
+
+    # Create output directory if it doesn't exist
+    os.makedirs(path, exist_ok=True)
+
+    # Load binning data into a dictionary
+    Metabinner_bins = {}
+    with open(binning, 'r') as b:
+        for line in b:
+            contig, bin = line.strip().split('\t')
+            Metabinner_bins[contig] = bin
+
+    # Process the input fasta file
+    with open(fasta) as handle:
+        for record in SeqIO.parse(handle, "fasta"):
+            if len(record) < length:
+                f = prefix + ".tooShort.fa"
+            elif record.id not in Metabinner_bins:
+                f = prefix + ".unbinned.fa"
+            else:
+                f = prefix + "." + Metabinner_bins[record.id] + ".fa"
+            with open(os.path.join(path, f), 'a') as out:
+                SeqIO.write(record, out, "fasta")
+
+if __name__ == "__main__":
+    main()
diff --git a/conf/base.config b/conf/base.config
@@ -169,6 +169,9 @@ process {
     withName: COMEBIN_RUNCOMEBIN {
         errorStrategy = { task.exitStatus in [1, 255] ? 'ignore' : 'retry' }
     }
+    withName: METABINNER_METABINNER {
+        errorStrategy = { task.exitStatus in [1, 255] ? 'ignore' : 'retry' }
+    }
     withName: DASTOOL_DASTOOL {
         errorStrategy = { task.exitStatus in ((130..145) + 104 + 175) ? 'retry' : task.exitStatus == 1 ? 'ignore' : 'finish' }
     }
diff --git a/conf/modules.config b/conf/modules.config
@@ -824,6 +824,52 @@ process {
         ext.prefix = { "${meta.assembler}-COMEBin-${meta.id}" }
     }
 
+    withName: METABINNER_KMER {
+        ext.prefix = { "${meta.assembler}-MetaBinner-${meta.id}" }
+    }
+
+    withName: METABINNER_TOOSHORT {
+        ext.prefix = { "${meta.assembler}-MetaBinner-${meta.id}" }
+    }
+
+    withName: METABINNER_METABINNER {
+        publishDir = [
+            [
+                path: { "${params.outdir}/GenomeBinning/MetaBinner/stats"},
+                mode: params.publish_dir_mode,
+                pattern: '*.{log,log.gz,tsv.gz}'
+            ]
+        ]
+        ext.prefix = { "${meta.assembler}-MetaBinner-${meta.id}" }
+        ext.args = { "-s ${params.bin_metabinner_scale}" }
+    }
+
+    withName: METABINNER_BINS {
+        publishDir = [
+            [
+                path: { "${params.outdir}/GenomeBinning/MetaBinner/"},
+                mode: params.publish_dir_mode,
+                pattern: 'bins/*.fa.gz'
+            ],
+            [
+                path: { "${params.outdir}/GenomeBinning/MetaBinner/discarded" },
+                mode: params.publish_dir_mode,
+                pattern: '*tooShort.fa.gz'
+            ],
+            [
+                path: { "${params.outdir}/GenomeBinning/MetaBinner/discarded" },
+                mode: params.publish_dir_mode,
+                pattern: '*lowDepth.fa.gz'
+            ],
+            [
+                path: { "${params.outdir}/GenomeBinning/MetaBinner/unbinned" },
+                mode: params.publish_dir_mode,
+                pattern: '*unbinned.fa.gz'
+            ]
+        ]
+        ext.prefix = { "${meta.assembler}-MetaBinner-${meta.id}" }
+    }
+
     withName: SEQKIT_STATS {
         ext.args   = ""
         publishDir = [enabled: false]
diff --git a/conf/test.config b/conf/test.config
@@ -29,6 +29,7 @@ params {
     // Including (even length filtered) CONOCT bins adds another 5 minutes, so we skip it in the default test (testing in assemblyinput)
     skip_concoct                = true
     skip_comebin                = true
+    skip_metabinner             = true
     busco_db                    = params.pipelines_testdata_base_path + 'mag/databases/busco/bacteria_odb10.2024-01-08.tar.gz'
     busco_db_lineage            = 'bacteria_odb10'
     busco_clean                 = true
diff --git a/conf/test_alternatives.config b/conf/test_alternatives.config
@@ -40,6 +40,7 @@ params {
     skip_maxbin2               = true
     skip_concoct               = true
     skip_comebin               = true
+    skip_metabinner            = true
     skip_metaeuk               = true
     megahit_fix_cpu_1          = true
 }
diff --git a/conf/test_assembly_input.config b/conf/test_assembly_input.config
@@ -44,6 +44,7 @@ params {
     gtdbtk_skip_aniscreen           = true
     skip_concoct                    = false
     skip_comebin                    = true
+    skip_metabinner                 = true
 
     refine_bins_dastool             = true
     refine_bins_dastool_threshold   = 0.0
diff --git a/conf/test_hybrid.config b/conf/test_hybrid.config
@@ -40,6 +40,7 @@ params {
     gtdbtk_skip_aniscreen         = true
     skip_concoct                  = true
     skip_comebin                  = true
+    skip_metabinner               = true
 
     spadeshybrid_fix_cpus         = 2
 }
diff --git a/conf/test_longreadonly.config b/conf/test_longreadonly.config
@@ -39,4 +39,5 @@ params {
     gtdbtk_skip_aniscreen      = true
     skip_concoct               = true
     skip_comebin               = true
+    skip_metabinner            = true
 }
diff --git a/conf/test_longreadonly_alternatives.config b/conf/test_longreadonly_alternatives.config
@@ -39,5 +39,6 @@ params {
     gtdbtk_skip_aniscreen         = true
     skip_concoct                  = true
     skip_comebin                  = true
+    skip_metabinner               = true
     skip_metaeuk                  = true
 }
diff --git a/conf/test_minimal.config b/conf/test_minimal.config
@@ -41,6 +41,7 @@ params {
     skip_maxbin2                  = true
     skip_concoct                  = true
     skip_comebin                  = true
+    skip_metabinner               = true
     skip_prokka                   = true
     skip_binqc                    = true
     run_busco                     = false
diff --git a/conf/test_single_end.config b/conf/test_single_end.config
@@ -40,6 +40,7 @@ params {
     bcftools_view_medium_variant_quality = 0
     bcftools_view_minimal_allelesupport  = 3
     skip_comebin                         = true
+    skip_metabinner                      = true
     min_length_unbinned_contigs          = 1000000
     max_unbinned_contigs                 = 2
     run_busco                            = false
diff --git a/docs/output.md b/docs/output.md
@@ -437,7 +437,8 @@ Files in these two folders contain all contigs of an assembly.
   - `stats/[assembler]-[binner]-[sample/group]_*.tsv`: Coverage statistics of each sub-contig cut up by CONCOCT prior in an intermediate step prior to binning. Likely not useful in most cases.
   - `stats/[assembler]-[binner]-[sample/group].log.txt`: CONCOCT execution log file.
   - `stats/[assembler]-[binner]-[sample/group]_*.args`: List of arguments used in CONCOCT execution.
-  - </details>
+
+</details>
 
 All the files and contigs in these folders will be assessed by QUAST and BUSCO, if the parameter `--postbinning_input` is not set to `refined_bins_only`.
 
@@ -456,12 +457,31 @@ Note that CONCOCT does not output what it considers 'unbinned' contigs, therefor
   - `stats/[assembler]-[binner]-[sample/group]/comebin_res.tsv`: TSV mapping the output clusters to contigs.
   - `stats/[assembler]-[binner]-[sample/group]/covembeddings.tsv`: TSV describing the embeddings of the contigs.
   - `stats/[assembler]-[binner]-[sample/group]/embeddings.tsv`: TSV describing the embeddings of the contigs.
-  - </details>
+
+</details>
 
 All the files and contigs in these folders will be assessed by QUAST and BUSCO, if the parameter `--postbinning_input` is not set to `refined_bins_only`.
 
 Note that COMEBin does not output what it considers 'unbinned' contigs, therefore no 'discarded' contigs are produced here. You may still need to do your own manual curation of the resulting bins.
 
+### MetaBinner
+
+[MetaBinner](https://github.com/ziyewang/MetaBinner) is described as a high-performance and stand-alone ensemble binning method to recover individual genomes from complex microbial communities.
+
+<details markdown="1">
+<summary>Output files</summary>
+
+- `GenomeBinning/MetaBinner/`
+  - `bins/[assembler]-[binner]-[sample/group].*.fa.gz`: Genome bins retrieved from input assembly.
+  - `discarded/[assembler]-[binner]-[sample/group].tooShort.fa.gz`: Contigs that were not considered for binning because of length.
+  - `unbinned/[assembler]-[binner]-[sample/group].unbinned.fa.gz`: Contigs that were not binned despite having suitable length.
+  - `stats/[assembler]-[binner]-[sample/group].metabinner.log.gz`: Log file.
+  - `stats/[assembler]-[binner]-[sample/group].tsv.gz`: TSV mapping the contigs to output clusters.
+
+</details>
+
+All the files and contigs in these folders will be assessed by QUAST and binning QC tools, if the parameter `--postbinning_input` is not set to `refined_bins_only`.
+
 ### DAS Tool
 
 [DAS Tool](https://github.com/cmks/DAS_Tool) is an automated binning refinement method that integrates the results of a flexible number of binning algorithms to calculate an optimized, non-redundant set of bins from a single assembly. nf-core/mag uses this tool to attempt to further improve bins based on combining the MetaBAT2 and MaxBin2 binning output, assuming sufficient quality is met for those bins.
diff --git a/modules/local/metabinner_bins/environment.yml b/modules/local/metabinner_bins/environment.yml
@@ -0,0 +1,7 @@
+---
+# yaml-language-server: $schema=https://raw.githubusercontent.com/nf-core/modules/master/modules/environment-schema.json
+channels:
+  - conda-forge
+  - bioconda
+dependencies:
+  - bioconda::metabinner=1.4.4-0
diff --git a/modules/local/metabinner_bins/main.nf b/modules/local/metabinner_bins/main.nf
@@ -0,0 +1,44 @@
+process METABINNER_BINS {
+    tag "$meta.id"
+    label 'process_low'
+
+    conda "${moduleDir}/environment.yml"
+    container "${ workflow.containerEngine == 'singularity' && !task.ext.singularity_pull_docker_container ?
+        'https://depot.galaxyproject.org/singularity/metabinner:1.4.4--hdfd78af_0' :
+        'quay.io/biocontainers/metabinner:1.4.4--hdfd78af_0' }"
+
+    input:
+    tuple val(meta), path(fasta), path(membership)
+    val val_min_contig_size
+
+    output:
+    tuple val(meta), path("*.tooShort.fa.gz")         , emit: tooshort
+    tuple val(meta), path("*.unbinned.fa.gz")         , emit: unbinned
+    tuple val(meta), path("bins/*.fa.gz")             , emit: bins
+    path "versions.yml"                               , emit: versions
+
+    script:
+    def prefix = task.ext.prefix ?: "${meta.id}"
+    def min_contig_size = val_min_contig_size ?: "1000"
+    """
+    # unzip membership file
+    zcat ${membership} > membership.tsv
+
+    # collect bins & un-binned fractions
+    create_metabinner_bins.py \\
+        membership.tsv \\
+        ${fasta} \\
+        ./bins \\
+        ${prefix} \\
+        ${min_contig_size}
+    find ./bins/ -name "*.fa" -type f | xargs -t -n 1 bgzip -@ ${task.cpus}
+
+    # zip contig fractions
+    find ./bins/ -name "*[tooShort,unbinned].fa.gz" -type f -exec mv {} . \\;
+
+    cat <<-END_VERSIONS > versions.yml
+    "${task.process}":
+        python: \$(python --version 2>&1 | sed 's/Python //g')
+    END_VERSIONS
+    """
+}
diff --git a/modules/local/metabinner_kmer/environment.yml b/modules/local/metabinner_kmer/environment.yml
@@ -0,0 +1,7 @@
+---
+# yaml-language-server: $schema=https://raw.githubusercontent.com/nf-core/modules/master/modules/environment-schema.json
+channels:
+  - conda-forge
+  - bioconda
+dependencies:
+  - bioconda::metabinner=1.4.4-0
diff --git a/modules/local/metabinner_kmer/main.nf b/modules/local/metabinner_kmer/main.nf
@@ -0,0 +1,36 @@
+process METABINNER_KMER {
+    tag "$meta.id"
+    label 'process_low'
+
+    conda "${moduleDir}/environment.yml"
+    container "${ workflow.containerEngine == 'singularity' && !task.ext.singularity_pull_docker_container ?
+        'https://depot.galaxyproject.org/singularity/metabinner:1.4.4--hdfd78af_0' :
+        'quay.io/biocontainers/metabinner:1.4.4--hdfd78af_0' }"
+
+    input:
+    tuple val(meta), path(fasta)
+    val val_min_contig_size
+
+    output:
+    tuple val(meta), path("*_kmer_4_f${min_contig_size}.csv.gz"), emit: composition_profile
+    path "versions.yml"                                         , emit: versions
+
+    script:
+    def prefix = task.ext.prefix ?: "${meta.id}"
+    min_contig_size = val_min_contig_size ?: "1000"
+    def VERSION = '1.4.4-0' // WARN: Version information not provided by tool on CLI. Please update this string when bumping container versions.
+    """
+    metabinner_path=\$(dirname \$(which run_metabinner.sh))
+
+    # create composition profile (contigs > ${min_contig_size} p (default 1000), k = 4)
+    python \${metabinner_path}/scripts/gen_kmer.py ${fasta} ${min_contig_size} 4
+
+    gzip -cn ${fasta.baseName}_kmer_4_f${min_contig_size}.csv > ${prefix}_kmer_4_f${min_contig_size}.csv.gz
+
+    cat <<-END_VERSIONS > versions.yml
+    "${task.process}":
+        MetaBinner: $VERSION
+        python: \$(python --version 2>&1 | sed 's/Python //g')
+    END_VERSIONS
+    """
+}
diff --git a/modules/local/metabinner_metabinner/environment.yml b/modules/local/metabinner_metabinner/environment.yml
@@ -0,0 +1,7 @@
+---
+# yaml-language-server: $schema=https://raw.githubusercontent.com/nf-core/modules/master/modules/environment-schema.json
+channels:
+  - conda-forge
+  - bioconda
+dependencies:
+  - bioconda::metabinner=1.4.4-0
diff --git a/modules/local/metabinner_metabinner/main.nf b/modules/local/metabinner_metabinner/main.nf
diff --git a/modules/local/metabinner_tooshort/environment.yml b/modules/local/metabinner_tooshort/environment.yml
diff --git a/modules/local/metabinner_tooshort/main.nf b/modules/local/metabinner_tooshort/main.nf
diff --git a/nextflow.config b/nextflow.config
diff --git a/nextflow_schema.json b/nextflow_schema.json
diff --git a/ro-crate-metadata.json b/ro-crate-metadata.json
diff --git a/subworkflows/local/binning/main.nf b/subworkflows/local/binning/main.nf
diff --git a/subworkflows/local/binning_metabinner/main.nf b/subworkflows/local/binning_metabinner/main.nf

Original file line number	Diff line number	Diff line change
`@@ -169,6 +169,9 @@ process {`
`169`	`169`	`withName: COMEBIN_RUNCOMEBIN {`
`170`	`170`	`errorStrategy = { task.exitStatus in [1, 255] ? 'ignore' : 'retry' }`
`171`	`171`	`}`
	`172`	`+ withName: METABINNER_METABINNER {`
	`173`	`+ errorStrategy = { task.exitStatus in [1, 255] ? 'ignore' : 'retry' }`
	`174`	`+ }`
`172`	`175`	`withName: DASTOOL_DASTOOL {`
`173`	`176`	`errorStrategy = { task.exitStatus in ((130..145) + 104 + 175) ? 'retry' : task.exitStatus == 1 ? 'ignore' : 'finish' }`
`174`	`177`	`}`
Original file line number	Diff line number	Diff line change
`@@ -40,6 +40,7 @@ params {`
`40`	`40`	`skip_maxbin2 = true`
`41`	`41`	`skip_concoct = true`
`42`	`42`	`skip_comebin = true`
	`43`	`+ skip_metabinner = true`
`43`	`44`	`skip_metaeuk = true`
`44`	`45`	`megahit_fix_cpu_1 = true`
`45`	`46`	`}`