SemiBin: Metagenomic Binning with Siamese Neural Networks

At the end of a binning run, SemiBin logs a summary of the results to both the console and SemiBinRun.log. The summary includes:

• Number of bins produced.
• Number of contigs and basepairs binned.
• Amount of unbinned data (split into contigs that passed the length filter but were not binned, and contigs too short to be considered).
• Mean and median bin size.
• Contigs-per-bin.

Warning: These bins are not quality-controlled. Users should perform further QC using tools like CheckM2 and GUNC before treating them as MAGs.

Before running SemiBin2, ensure your input files meet these requirements:

• FASTA (Contigs): Must have unique contig names. Contigs must be above a minimum length (auto-detected as 1000 or 2500 bp, or manually set via -m/--min-len).
• BAM/CRAM (Reads): Must be mapped to the exact same FASTA file used for contigs. Files must be sorted (samtools sort) and indexed (samtools index, providing a .bai or .crai file).
• Multi-sample FASTA: If using a concatenated FASTA, contig headers must follow the <sample><separator><contig> format (default separator is :). Use SemiBin2 concatenate_fasta to generate these correctly.
• Abundance Files: If using -a/--abundance (strobealign-aemb TSVs) instead of BAMs, you must provide data for at least 5 samples.

SemiBin2 uses a spawn multiprocessing context. When implementing parallel tasks, use the following pattern to manage a worker pool.

Note: The Pool object is typically defined at the module level in main.py as Pool = mp.get_context('spawn').Pool.

with Pool(min(args.num_process, len(items))) as pool:
    results = [
        pool.apply_async(
            worker_function,
            args=(item, args.output, logger)
        )
        for item in items
    ]
    for r in results:
        result = r.get()  # blocks; raises exception if worker failed
        logger.info(f'Processed: {result}')

SemiBin utilizes two distinct types of machine learning models depending on your binning task:

1. Single-sample models: Designed for binning individual samples independently. While they are typically trained on a specific sample, they can be trained on a subset of multiple similar samples (e.g., from the same habitat) and then reused across different samples to minimize computational costs.
2. Multi-sample models: Designed specifically for multi-sample binning tasks. Unlike single-sample models, multi-sample models must be learned specifically for each individual multi-sample binning task and cannot be reused across different tasks.

Key takeaway: A model is defined as 'single-sample' by how it is applied (independently to each sample), not by how it was trained (it can be trained using data from multiple samples).

SemiBin2 requires explicit subcommands for training. The default training mode is self-supervised. To specify a mode, use one of the following subcommands:

• train_semi: For semi-supervised training.
• train_self: For self-supervised training.

Note: The generic train subcommand is no longer available.

# Example of semi-supervised training
SemiBin2 train_semi [options]

# Example of self-supervised training
SemiBin2 train_self [options]

The SemiBin agent skill provides the following capabilities to coding agents:

• Binning Mode Selection: Choosing between single-sample, co-assembly, and multi-sample binning.
• Command Construction: Building correct command lines, including workflows for long-reads and pre-trained models.
• Input Validation: Checking for sorted/indexed BAM files, uniquely named contigs, and the multi-sample separator.
• Output Location: Identifying where final bins and summary tables are written.
• Error Resolution: Providing fixes for the most common error messages.

When training SemiBin models, you can choose between two learning paradigms:

• Self-supervised learning (Preferred): This is the recommended approach for SemiBin (supported since version 1.3). It is described in the SemiBin2 manuscript and is generally more efficient for the current architecture.
• Semi-supervised learning (Not recommended): This approach involves annotating contigs taxonomically and using those labels to learn the model. While still supported, it is considered legacy and is expected to be removed in future versions.

If you are starting a new training workflow, use the self-supervised approach.

If using strobealign-aemb for abundance estimation instead of BAM files, follow this workflow:

1. Split contigs: Generate must-link constraints. SemiBin2 split_contigs -i contig.fa -o output
2. Map reads: Use strobealign --aemb to generate abundance text files for each sample.
3. Generate features: Use the generate_sequence_features_* commands.
4. Run binning: Use single_easy_bin or multi_easy_bin with the -a (abundance) flag.

# 1. Split
SemiBin2 split_contigs -i contig.fa -o output

# 2. Map (example for one sample)
strobealign --aemb output/split_contigs.fna.gz read1_1.fq read1_2.fq -R 6 > sample1.txt

# 3. Generate features and bin
SemiBin2 generate_sequence_features_single -i contig.fa -a *.txt -o output
SemiBin2 single_easy_bin -i contig.fa -a *.txt -o output

SemiBin's system requirements have evolved across recent versions:

• Current (Unreleased/v2.5.0+): Requires pandas>=3 and Python 3.11 or higher. Support for Python 3.10 has been dropped.
• v2.4.0: Minimum supported Python version is 3.10 (dropped 3.8 and 3.9).
• v2.3.0: Supported Python versions are 3.8–3.14.

Note that check_install is a soft check for samtools; it is only required if you are using CRAM input.