Metadata-Version: 2.4
Name: binferno
Version: 0.1.0
Summary: Metagenomic binner using SimCLR and Barlow Twins training, with taxonomic embeddings by Corgi to improve microbial genome binning.
License: GPL-3.0
License-File: LICENSE.txt
Keywords: metagenomics,binning,neural networks,contrastive learning,bioinformatics
Author: Andy Tong
Author-email: tyuhao037@gmail.com
Requires-Python: >=3.10,<3.13
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Provides-Extra: esmc
Requires-Dist: atomicwrites (>=1.4.1,<2.0.0)
Requires-Dist: bio-corgi (>=0.5.1,<0.6.0)
Requires-Dist: biopython (>=1.80)
Requires-Dist: checkm-genome (>=1.1.3,<=1.2.4)
Requires-Dist: click (>=8.3.1,<9.0.0)
Requires-Dist: esm (>=3.2.1,<3.3) ; extra == "esmc"
Requires-Dist: hnswlib (>=0.8.0,<0.9.0)
Requires-Dist: igraph (>=1.0.0,<2.0.0)
Requires-Dist: leidenalg (>=0.11.0,<0.12.0)
Requires-Dist: loguru (>=0.7.3,<0.8.0)
Requires-Dist: matplotlib (>=3.10.7,<4.0.0)
Requires-Dist: matplotlib-inline (>=0.2.1,<0.3.0)
Requires-Dist: networkx (==3.4.0)
Requires-Dist: numba (>=0.62.1,<0.63.0)
Requires-Dist: numpy (>=1.6.0,<3.0.0)
Requires-Dist: pandas (>=2.3.3,<3.0.0)
Requires-Dist: pydantic (>=2.13.3,<3.0.0)
Requires-Dist: pyfastx (==2.3.0)
Requires-Dist: pyhmmer (>=0.10.15,<=0.12.0)
Requires-Dist: pyrodigal (>=3.6.3,<=3.7.1)
Requires-Dist: pysam (>=0.20,<=0.23)
Requires-Dist: python-dateutil (>=2.9.0.post0,<3.0.0)
Requires-Dist: scikit-learn (>=1.7.2,<2.0.0)
Requires-Dist: scipy (>=1.15.0,<2.0.0)
Requires-Dist: seaborn (>=0.13.2,<0.14.0)
Requires-Dist: setuptools (>=79.0.0,<81.0)
Requires-Dist: tensorboard (>=2.20.0,<3.0.0)
Requires-Dist: torch (>=2.5.1,<=2.6.0)
Requires-Dist: tyro (>=1.0.13,<2.0.0)
Description-Content-Type: text/x-rst


======================================================
Binferno: Contrastive Barlow-Twins metagenomic binning
======================================================

.. start-badges

|testing badge| |docs badge|

.. |testing badge| image:: https://github.com/Andyargueasae/binferno/actions/workflows/testing.yml/badge.svg
    :target: https://github.com/Andyargueasae/binferno/actions

.. |docs badge| image:: https://github.com/Andyargueasae/binferno/actions/workflows/docs.yml/badge.svg
    :target: https://Andyargueasae.github.io/binferno

.. end-badges

.. image:: https://raw.githubusercontent.com/Andyargueasae/binferno/main/docs/source/_static/images/binferno-banner.jpg
    :alt: Binferno logo


Binferno is a python-based metagenomic binner that handles metagenomic contigs for both prokaryotic genomes and eukaryotic plastid genomes.

Installation
============

Binferno is installable via pip. But before installing it, build the conda environment using the conda_env.yaml provided.

.. code-block:: bash

    mamba env create -n Binferno_env -c conda-forge -c bioconda -c defaults python=3.10
    # mamba env create -n Binferno_env -f conda_env.yaml
    conda activate Binferno_env

Then, install Binferno via pip:

.. code-block:: bash

    pip install binferno

Check the installation by running:

.. code-block:: bash

    binferno --help

Input features
================

Like most other metagenomic binners, Binferno uses two types of features: sequence composition and coverage. The sequence composition is represented by tetranucleotide frequencies (TNF), while the coverage is represented by the average depth of coverage across the contig.

For improved training, we also offer an option to use the projected kmer features: by multiplying original composition features with the kernel matrix obtained from VAMB.

Corgi encoding is also supported, which is a more compact representation of the sequence composition features with hidden taxonomic information encoded in the latent space.

Because running Binferno requires checkm to evaluate the quality of the bins, please specify the path to the checkm database in the command line when running Binferno.

For prokaryote binning: ``checkm_data.tar.gz`` from the official checkm repository can work. For plastid binning, we curated one database with plastid protein HMMs, which can be downloaded from figshare: ...

Usage
=====

A simple usage of Binferno is as follows:

.. code-block:: bash

    binferno --contig-file contigs.fasta --bam-dir path/to/bam/files \
        --output-dir path/to/output/dir --checkm-db path/to/checkm/db \
        --contig-length 1000

Such command will run Binferno with most default parameters: encode contigs by canonical 136-dimension kmer features and coverage mean and standard deviation.

For plastid binning, run with the flag ``--plastid``:

.. code-block:: bash

    binferno --contig-file contigs.fasta --bam-dir path/to/bam/files \
        --output-dir path/to/output/dir --checkm-db path/to/plastid/checkm/db \
        --contig-length 1000 --plastid

The output bins will be stored in the output directory specified by ``--output-dir``. The final bins will be stored in the subdirectory ``res_bins``.

Besides, other steps, like augmentations, training, and clustering outputs will also be stored as intermediate results in the output directory as ``augmentations``, ``training`` and ``cluster_res`` subdirectories, respectively.

For more details, please refer to the documentation: https://andyargueasae.github.io/binferno/Binferno.html.

Credits
========

.. start-credits

Binferno is developed by:

- `PhD candidate Yuhao Tong <https://www.linkedin.com/in/yuhao-tong-2a015825b/>`_
- `A/Prof Heroen Verbruggen <https://hverbruggen.codeberg.page>`_
- `Dr Vanessa R. Marcelino <https://hologenomics.org/people.html>`_
- `Dr Robert Turnbull <https://robturnbull.com>`_

.. end-credits

Contact:
    - Yuhao Tong:
        - Email: tyuhao037@gmail.com

