conda config --add envs_dirs /zfs/omics/projects/bioinformatics/software/miniconda3/envs/SemiBin2
Introduction
SemiBin2 is a binning tool that uses a self-supervised deep learning model (trained directly on your own data, without needing reference genomes) to combine sequence composition and coverage/abundance information (from mapping reads back to the assembly) to group contigs from a metagenome assembly into genome bins (Pan, Zhao, and Coelho 2023).
For metagenomic binning pipelines, it is recommended to use SemiBin2 alongside other binners (i.e. MetaBAT2, COMEbin, VAMB, …), and then consolidate the results using either DAS Tool or Binette to get the best results.
Installation
Installed on Crunchomics: yes, SemiBin v2.4.1 is installed via conda (env name semibin_2.4.1).
If you have access to Crunchomics and have not yet access to the bioinformatics share you can send an email with your UvA netID to Nina Dombrowski. Afterwards, you can add the bioinformatics share as follows (if you have already done this in the past, you don’t need to run this command):
If you want to install it yourself, the command below installs the version verified on Crunchomics. Before running it, check the tool’s GitHub releases page for a newer version and swap the version number if one is available.
mamba create -n semibin_2.4.1 -c bioconda -c conda-forge semibin=2.4.1Usage
SemiBin2 has several subcommands for different scenarios; the full, current list can be seen with SemiBin2 -h and is also documented on the SemiBin ReadTheDocs page. The two most relevant ones for most users are:
single_easy_bin: bins one assembly in one command. This covers two cases that SemiBin treats the same way at the command level:- Single-sample binning: the assembly was built from one sample’s reads only. You can still pass multiple BAM files (reads from several samples mapped back to that one assembly) to get differential-coverage information — this does not turn it into co-assembly binning.
- Co-assembly binning: the assembly itself was built by pooling reads from multiple samples and assembling them together as if they were one sample.
multi_easy_bin: for samples that were each assembled separately. It concatenates the per-sample contigs into one combined fasta (contigs renamed<sample_name>:<original_contig_name>via theconcatenate_fastasubcommand) and maps each sample’s reads to that combined fasta — an all-vs-all, cross-sample approach.
Whether a single_easy_bin run is “single-sample” or “co-assembly” binning depends entirely on how the assembly itself was built upstream (by your assembler), not on how many BAM files you pass to -b. If your assembly comes from one sample only and you don’t want to deal with multi_easy_bin‘s contig-renaming step (which can complicate keeping contig names consistent across binners when consolidating results later with DAS Tool/Binette), you can stick with single_easy_bin and simply pass multiple samples’ BAM files for differential-coverage binning against the single-sample assembly, as in the example below.
The other subcommands (generate_sequence_features_single, generate_sequence_features_multi, train_self, bin/bin_short, bin_long, …) let you run the sequence-feature-generation, model-training, and binning steps separately instead of via the “easy” wrapper commands — useful if you want more control over the workflow (e.g. reusing a trained model across runs). See the SemiBin docs for details.
Input file format:
- Contigs [-i/–input-fasta]: The metagenome assembly in fasta format.
- BAM files [-b/–input-bam]: One or more sorted, indexed BAM files from mapping reads back to the assembly (one BAM per sample if you have multiple samples for differential coverage binning).
conda activate semibin_2.4.1
SemiBin2 single_easy_bin \
-i my_assembly.fasta \
-b mappings/*.sorted.bam \
-o semibin_out \
-t 10After running this, you will find the resulting bins as separate fasta files in the output_bins/ subfolder of the specified output directory ($outdir above).
options:
-h, --help show this help message and exit
--write-pre-reclustering-bins, --no-write-pre-reclustering-bins
Write pre-reclustering bins to disk.
--tag-output OUTPUT_TAG
Tag to add to output file names
--compression OUTPUT_COMPRESSION
Compression type for the output files (accepted values: gz [default]/xz/bz2/none).
--orf-finder ORF_FINDER
ORF finder used to estimate the number of bins (fast-naive/prodigal/fraggenescan)
--prodigal-output-faa PRODIGAL_OUTPUT_FAA
[deprecated] Bypasses ORF calling and uses the provided .faa file instead (must be in
same format as prodigal output).
--depth-metabat2 DEPTH_METABAT2
depth file generated by metabat2 (only used with single-sample binning)
--tmpdir TMPDIR option to set temporary directory
-p, --processes, -t, --threads
Number of CPUs used (pass the value 0 to use all CPUs, default: 0)
--environment, --habitat, --biome ENVIRONMENT
Environment for the built-in model (available choices: human_gut/dog_gut/ocean/soil/cat_
gut/human_oral/mouse_gut/pig_gut/built_environment/wastewater/chicken_caecum/global).
-m, --min-len MIN_LEN
Minimal length for contigs in binning. If you use SemiBin with multi steps and you use
this parameter, please use this parameter consistently with all subcommands. (Default:
SemiBin chooses 1000bp or 2500bp according the ratio of the number of base pairs of
contigs between 1000-2500bp).
--ratio RATIO If the ratio of the number of base pairs of contigs between 1000-2500 bp smaller than
this value, the minimal length will be set as 1000bp, otherwise 2500bp. Note that
setting `--min-length/-m` overrules this parameter. If you use SemiBin with multi steps
and you use this parameter, please use this parameter consistently with all subcommands.
(Default: 0.05)
-b, --input-bam [BAMS ...]
Path to the input BAM(.bam)/CRAM(.cram) file(s). If using multiple samples, you can
input multiple files.If just computing k-mer features, a BAM file is not needed.
-a, --abundance [ABUNDANCES ...]
Path to the abundance file from strobealign-aemb. This can only be used when samples
used in binning above or equal 5.
--verbose Verbose output
--quiet, -q Quiet output
-r, --reference-db-data-dir, --reference-db
GTDB reference storage path. (Default: $HOME/.cache/SemiBin/mmseqs2-GTDB).If not set
--reference-db and SemiBin cannot find GTDB in $HOME/.cache/SemiBin/mmseqs2-GTDB,
SemiBin will download GTDB (Note that >100GB of disk space are required).
--cannot-name Name for the cannot-link file (default: cannot).
--taxonomy-annotation-table [TAXONOMY_TSV ...]
Pre-computed mmseqs2 format taxonomy TSV file to bypass mmseqs2 GTDB annotation
[advanced]. When running with multi-sample binning, please make sure that the order of
the taxonomy TSV file and the contig file (used for the combined fasta) is same.
--epochs, --epoches EPOCHS
Number of epochs used in the training process (Default: 15).
--batch-size BATCHSIZE
Batch size used in the training process (Default: 2048).
--minfasta-kbs minimum bin size in Kbps (Default: 200).
--random-seed RANDOM_SEED
Random seed. Set it to a fixed value to reproduce results across runs. The default is
that the seed is set by the system and results may vary between runs.
--ml-threshold ML_THRESHOLD
Length threshold for generating must-link constraints. (By default, the threshold is
calculated from the contig, and the default minimum value is 4,000 bp)
--engine ENGINE device used to train the model (auto/gpu/cpu, auto means if SemiBin detects the gpu,
SemiBin will use GPU)
--semi-supervised Train the model with semi-supervised learning.
--self-supervised Train the model with self-supervised learning.
--sequencing-type SEQUENCING_TYPE
sequencing type in [short_read/long_read/hybrid], Default: short_read. Note: hybrid is
treated as long_read.
Mandatory arguments:
-i, --input-fasta CONTIG_FASTA
Path to the input fasta file.
-o, --output OUTPUT Output directory (will be created if non-existent)
Binning options (advanced use):
--max-edges MAX_EDGES
The maximum number of edges that can be connected to one contig (Default: 200).
--max-node MAX_NODE Fraction of contigs that considered to be binned (should be between 0 and 1; default:
1).
--no-recluster Do not recluster bins.References
Pan, Shaojun, Xing-Ming Zhao, and Luis Pedro Coelho. 2023. “SemiBin2: Self-Supervised Contrastive Learning Leads to Better MAGs for Short- and Long-Read Sequencing.” Bioinformatics 39 (Supplement_1): i21–29. https://doi.org/10.1093/bioinformatics/btad209.