metabintools 0.2.0__tar.gz

metabintools-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Genome Research Ltd.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

metabintools-0.2.0/PKG-INFO

@@ -0,0 +1,276 @@
+Metadata-Version: 2.4
+Name: metabintools
+Version: 0.2.0
+Summary: A toolkit for collating and manipulating metagenome bins.
+Author: Jim Downie
+Author-email: Jim Downie <jd42@sanger.ac.uk>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Dist: click>=8.5.0
+Requires-Dist: loguru>=0.7.3
+Requires-Dist: pydantic>=2.13.5
+Requires-Dist: pyfastx>=2.3.1
+Requires-Dist: requests>=2.34.2
+Requires-Dist: zstandard>=0.25.0
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+# metabintools
+
+**metabintools** is a toolkit for managing and manipulating metagenomic binning outputs. It consolidates all bin data, including sequences, annotations, quality metrics, and taxonomy, into a single unified file format for streamlined analysis workflows. This file can be queried, filtered, bins can be renamed using their metadata, and separate files can easily be merged to consolidate bins into a single file.
+
+## Overview
+
+Metagenomic binning produces scattered outputs: bin FASTA files, quality assessments, taxonomic classifications, and annotations in separate formats. **metabintools** unifies these into a single `.bins` file (optionally compressed as `.bins.zstd`), enabling easy filtering, merging, and export via composable command-line operations.
+
+## Key Features
+
+- **Unified file format**: Store bins, contigs, annotations, quality scores, and taxonomy in one `.bins` file
+- **Composable operations**: Chain commands via Unix pipes for flexible workflows
+- **Powerful filtering**: Query bins by any property (completeness, contamination, taxonomy, etc.)
+- **Compression support**: Optional zstd compression for efficient storage
+- **Multiple input sources**: Import bin metadata from many metagenomics tools (CheckM, GTDB-Tk, etc.)
+
+## Installation
+
+```bash
+pip install metabintools
+```
+
+## Quick Start
+
+### 1. Create a binfile from your assembly
+
+```bash
+metabintools import asm assembly.fasta -o binset.bins
+```
+
+### 2. Add annotations to your binfile
+
+```bash
+metabintools import annotations binset.bins annotations.gff -o binset.bins
+```
+
+### 3. Add bins from your binner
+
+```bash
+metabintools import binset binset.bins bins/ --group "myBinner" -o binset.bins
+```
+
+### 4. Add quality scores
+
+```bash
+metabintools import quality binset.bins checkm_results.tsv --tool checkm -o binset.bins
+```
+
+### 5. Add taxonomy
+
+```bash
+metabintools import taxonomy binset.bins gtdbtk.tsv --tool gtdbtk -o binset.bins
+```
+
+### 6. Filter high-quality bins
+
+```bash
+metabintools view binset.bins 'completeness >= 0.9 and contamination <= 0.05' -o hq.bins
+```
+
+or, if the required data for MiMAG calls is present (completeness, contamination, tRNAs, rRNAs):
+
+```bash
+metabintools view binset.bins 'mimag == "high"' -o hq.bins
+```
+
+### 7. Export to FASTA
+
+```bash
+metabintools export fasta hq.bins -o output_directory/
+```
+
+## Composable Workflows
+
+The real power of metabintools is composability via piping:
+
+```bash
+# Filter and export in one pipeline
+metabintools view binset.bins 'group == "metabat" and completeness >= 0.8' -z | \
+  metabintools export fasta -o filtered_bins/
+
+# Merge multiple binsets and filter
+metabintools merge set1.bins.zstd set2.bins.zstd -z | \
+  metabintools view - 'contamination <= 0.1' -o merged_hq.bins.zstd
+
+# Extract high-quality archaeal bins
+metabintools view binset.bins 'tax_kingdom == "Archaea" and completeness >= 0.85' -o archaea_hq.bins
+```
+
+## Filter Query Guide
+
+The `view` command uses simple Python-like syntax:
+
+```bash
+# Basic comparisons
+metabintools view input.bins 'completeness >= 0.9' -o output.bins
+metabintools view input.bins 'length > 1000000' -o output.bins
+
+# Logical operators
+metabintools view input.bins 'completeness >= 0.9 and contamination <= 0.05' -o output.bins
+metabintools view input.bins 'group == "vamb" or group == "metabat"' -o output.bins
+
+# Taxonomy filtering
+metabintools view input.bins 'tax_phylum == "Bacteroidetes"' -o output.bins
+
+# Complex queries
+metabintools view input.bins 'group == "archaea" and completeness >= 0.8 and contamination <= 0.1' -o output.bins
+```
+
+### Available Filter Fields
+
+List all available fields:
+
+```bash
+metabintools view --list-fields
+```
+
+## Commands
+
+### import
+
+Import data into a binfile with validation and error handling:
+
+- **`metabintools import asm`** - Initialize from assembly FASTA
+  - Can detect circular contigs from metaMDBG and myloasm
+
+- **`metabintools import binset`** - Add contig clusters from binning
+  - Optional binsplit separator recovery (SemiBin2, VAMB compatibility)
+
+- **`metabintools import annotation`** - Add GFF annotations to contigs
+
+- **`metabintools import coverage`** - Add coverage data to contigs
+  - Supports multiple coverage tools (e.g., CoverM, custom formats)
+
+- **`metabintools import taxonomy`** - Add taxonomic classifications to bins
+  - Supports multiple taxonomy tools (GTDB-Tk, gtdb_to_ncbi_majority_vote.py, manual)
+
+- **`metabintools import quality`** - Add quality scores (CheckM, CheckM2, BUSCO) to bins
+  - Supports multiple quality assessment tools
+
+### view
+
+Decompress a bins file, or filter bins by query expression with comprehensive validation:
+
+```bash
+metabintools view input.bins.zstd -o input.bins  # decompress
+```
+
+or
+
+```bash
+metabintools view input.bins 'completeness >= 0.9' -o output.bins
+metabintools view input.bins 'completeness >= 0.9' -z -o output.bins.zstd  # compressed
+metabintools view --list-fields  # Show all available filter fields
+```
+
+### export
+
+Export data from a binfile:
+
+- **`metabintools export fasta`** - Export each bin to a FASTA file
+- **`metabintools export gff`** - Export each bin's annotations to a GFF file
+- **`metabintools export contig2bin`** - Export a set of bins to a contig-to-bin mapping (DAS_Tool format)
+
+### merge
+
+Combine multiple binfiles with progress tracking and validation:
+
+```bash
+metabintools merge set1.bins set2.bins set3.bins -o merged.bins
+```
+
+### trim
+
+Remove unused contigs from a binfile:
+
+```bash
+metabintools trim input.bins -o trimmed.bins
+```
+
+### rename
+
+Rename bins in a binfile with template support. Field options can be listed with `--list-fields`.
+
+```bash
+metabintools rename input.bins -n "bin_{tax_phylum}" -o output.bins
+# bin1, bin2 > bin_Pseudomonadota_1, bin_Pseudomonadota_2
+```
+
+### summarise
+
+Generate summary reports:
+
+- **`metabintools summarise bins`** - Export bin summary to TSV
+- **`metabintools summarise groups`** - Export an aggregated summary of bin groups, showing counts of bins at each MiMAG level, to TSV
+- **`metabintools summarise contigs`** - Export contig summary to TSV
+
+## File Format
+
+A `.bins` file is a zstd-compressed (or uncompressed) JSON document containing:
+
+```json
+{
+  "contigs": {
+    "contig_id": {
+      "id": "contig_id",
+      "sequence": "ACGTACGT...",
+      "sequence_length": 1234,
+      "annotations": [...],
+      "coverage": 15.5,
+      "topology": "circular"
+    }
+  },
+  "bins": [
+    {
+      "id": "bin.1",
+      "group": "metabat",
+      "contigs": ["contig_1", "contig_2"],
+      "statistics": {
+        "completeness": 0.95,
+        "contamination": 0.02,
+        "length": 2500000
+      },
+      "taxonomy": {
+        "classification": "k__Bacteria;p__Proteobacteria;..."
+      }
+    }
+  ]
+}
+```
+
+## Examples
+
+### Workflow: Filter and Export High-Quality Bins
+
+```bash
+# Start with assembly
+metabintools import asm metagenome.fasta -o project.bins
+
+# Add binning results
+metabintools import binset project.bins bins/ --group "metabat" -o project.bins
+
+# Add quality scores
+metabintools import quality project.bins checkm_results.tsv --tool checkm -o project.bins
+
+# Add taxonomy
+metabintools import taxonomy project.bins gtdbtk.tsv --tool gtdbtk -o project.bins
+
+# Filter to high-quality bins
+metabintools view project.bins 'completeness >= 0.9 and contamination <= 0.05' \
+  -o high_quality.bins
+
+# Export to FASTA
+metabintools export fasta high_quality.bins -o bins_fasta/
+```
+
+## License
+
+MIT © 2026 Genome Research Ltd

metabintools-0.2.0/README.md

@@ -0,0 +1,259 @@
+# metabintools
+
+**metabintools** is a toolkit for managing and manipulating metagenomic binning outputs. It consolidates all bin data, including sequences, annotations, quality metrics, and taxonomy, into a single unified file format for streamlined analysis workflows. This file can be queried, filtered, bins can be renamed using their metadata, and separate files can easily be merged to consolidate bins into a single file.
+
+## Overview
+
+Metagenomic binning produces scattered outputs: bin FASTA files, quality assessments, taxonomic classifications, and annotations in separate formats. **metabintools** unifies these into a single `.bins` file (optionally compressed as `.bins.zstd`), enabling easy filtering, merging, and export via composable command-line operations.
+
+## Key Features
+
+- **Unified file format**: Store bins, contigs, annotations, quality scores, and taxonomy in one `.bins` file
+- **Composable operations**: Chain commands via Unix pipes for flexible workflows
+- **Powerful filtering**: Query bins by any property (completeness, contamination, taxonomy, etc.)
+- **Compression support**: Optional zstd compression for efficient storage
+- **Multiple input sources**: Import bin metadata from many metagenomics tools (CheckM, GTDB-Tk, etc.)
+
+## Installation
+
+```bash
+pip install metabintools
+```
+
+## Quick Start
+
+### 1. Create a binfile from your assembly
+
+```bash
+metabintools import asm assembly.fasta -o binset.bins
+```
+
+### 2. Add annotations to your binfile
+
+```bash
+metabintools import annotations binset.bins annotations.gff -o binset.bins
+```
+
+### 3. Add bins from your binner
+
+```bash
+metabintools import binset binset.bins bins/ --group "myBinner" -o binset.bins
+```
+
+### 4. Add quality scores
+
+```bash
+metabintools import quality binset.bins checkm_results.tsv --tool checkm -o binset.bins
+```
+
+### 5. Add taxonomy
+
+```bash
+metabintools import taxonomy binset.bins gtdbtk.tsv --tool gtdbtk -o binset.bins
+```
+
+### 6. Filter high-quality bins
+
+```bash
+metabintools view binset.bins 'completeness >= 0.9 and contamination <= 0.05' -o hq.bins
+```
+
+or, if the required data for MiMAG calls is present (completeness, contamination, tRNAs, rRNAs):
+
+```bash
+metabintools view binset.bins 'mimag == "high"' -o hq.bins
+```
+
+### 7. Export to FASTA
+
+```bash
+metabintools export fasta hq.bins -o output_directory/
+```
+
+## Composable Workflows
+
+The real power of metabintools is composability via piping:
+
+```bash
+# Filter and export in one pipeline
+metabintools view binset.bins 'group == "metabat" and completeness >= 0.8' -z | \
+  metabintools export fasta -o filtered_bins/
+
+# Merge multiple binsets and filter
+metabintools merge set1.bins.zstd set2.bins.zstd -z | \
+  metabintools view - 'contamination <= 0.1' -o merged_hq.bins.zstd
+
+# Extract high-quality archaeal bins
+metabintools view binset.bins 'tax_kingdom == "Archaea" and completeness >= 0.85' -o archaea_hq.bins
+```
+
+## Filter Query Guide
+
+The `view` command uses simple Python-like syntax:
+
+```bash
+# Basic comparisons
+metabintools view input.bins 'completeness >= 0.9' -o output.bins
+metabintools view input.bins 'length > 1000000' -o output.bins
+
+# Logical operators
+metabintools view input.bins 'completeness >= 0.9 and contamination <= 0.05' -o output.bins
+metabintools view input.bins 'group == "vamb" or group == "metabat"' -o output.bins
+
+# Taxonomy filtering
+metabintools view input.bins 'tax_phylum == "Bacteroidetes"' -o output.bins
+
+# Complex queries
+metabintools view input.bins 'group == "archaea" and completeness >= 0.8 and contamination <= 0.1' -o output.bins
+```
+
+### Available Filter Fields
+
+List all available fields:
+
+```bash
+metabintools view --list-fields
+```
+
+## Commands
+
+### import
+
+Import data into a binfile with validation and error handling:
+
+- **`metabintools import asm`** - Initialize from assembly FASTA
+  - Can detect circular contigs from metaMDBG and myloasm
+
+- **`metabintools import binset`** - Add contig clusters from binning
+  - Optional binsplit separator recovery (SemiBin2, VAMB compatibility)
+
+- **`metabintools import annotation`** - Add GFF annotations to contigs
+
+- **`metabintools import coverage`** - Add coverage data to contigs
+  - Supports multiple coverage tools (e.g., CoverM, custom formats)
+
+- **`metabintools import taxonomy`** - Add taxonomic classifications to bins
+  - Supports multiple taxonomy tools (GTDB-Tk, gtdb_to_ncbi_majority_vote.py, manual)
+
+- **`metabintools import quality`** - Add quality scores (CheckM, CheckM2, BUSCO) to bins
+  - Supports multiple quality assessment tools
+
+### view
+
+Decompress a bins file, or filter bins by query expression with comprehensive validation:
+
+```bash
+metabintools view input.bins.zstd -o input.bins  # decompress
+```
+
+or
+
+```bash
+metabintools view input.bins 'completeness >= 0.9' -o output.bins
+metabintools view input.bins 'completeness >= 0.9' -z -o output.bins.zstd  # compressed
+metabintools view --list-fields  # Show all available filter fields
+```
+
+### export
+
+Export data from a binfile:
+
+- **`metabintools export fasta`** - Export each bin to a FASTA file
+- **`metabintools export gff`** - Export each bin's annotations to a GFF file
+- **`metabintools export contig2bin`** - Export a set of bins to a contig-to-bin mapping (DAS_Tool format)
+
+### merge
+
+Combine multiple binfiles with progress tracking and validation:
+
+```bash
+metabintools merge set1.bins set2.bins set3.bins -o merged.bins
+```
+
+### trim
+
+Remove unused contigs from a binfile:
+
+```bash
+metabintools trim input.bins -o trimmed.bins
+```
+
+### rename
+
+Rename bins in a binfile with template support. Field options can be listed with `--list-fields`.
+
+```bash
+metabintools rename input.bins -n "bin_{tax_phylum}" -o output.bins
+# bin1, bin2 > bin_Pseudomonadota_1, bin_Pseudomonadota_2
+```
+
+### summarise
+
+Generate summary reports:
+
+- **`metabintools summarise bins`** - Export bin summary to TSV
+- **`metabintools summarise groups`** - Export an aggregated summary of bin groups, showing counts of bins at each MiMAG level, to TSV
+- **`metabintools summarise contigs`** - Export contig summary to TSV
+
+## File Format
+
+A `.bins` file is a zstd-compressed (or uncompressed) JSON document containing:
+
+```json
+{
+  "contigs": {
+    "contig_id": {
+      "id": "contig_id",
+      "sequence": "ACGTACGT...",
+      "sequence_length": 1234,
+      "annotations": [...],
+      "coverage": 15.5,
+      "topology": "circular"
+    }
+  },
+  "bins": [
+    {
+      "id": "bin.1",
+      "group": "metabat",
+      "contigs": ["contig_1", "contig_2"],
+      "statistics": {
+        "completeness": 0.95,
+        "contamination": 0.02,
+        "length": 2500000
+      },
+      "taxonomy": {
+        "classification": "k__Bacteria;p__Proteobacteria;..."
+      }
+    }
+  ]
+}
+```
+
+## Examples
+
+### Workflow: Filter and Export High-Quality Bins
+
+```bash
+# Start with assembly
+metabintools import asm metagenome.fasta -o project.bins
+
+# Add binning results
+metabintools import binset project.bins bins/ --group "metabat" -o project.bins
+
+# Add quality scores
+metabintools import quality project.bins checkm_results.tsv --tool checkm -o project.bins
+
+# Add taxonomy
+metabintools import taxonomy project.bins gtdbtk.tsv --tool gtdbtk -o project.bins
+
+# Filter to high-quality bins
+metabintools view project.bins 'completeness >= 0.9 and contamination <= 0.05' \
+  -o high_quality.bins
+
+# Export to FASTA
+metabintools export fasta high_quality.bins -o bins_fasta/
+```
+
+## License
+
+MIT © 2026 Genome Research Ltd

metabintools-0.2.0/pyproject.toml

@@ -0,0 +1,36 @@
+[project]
+name = "metabintools"
+version = "0.2.0"
+description = "A toolkit for collating and manipulating metagenome bins."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICEN[CS]E*"]
+requires-python = ">=3.13"
+dependencies = [
+    "click>=8.5.0",
+    "loguru>=0.7.3",
+    "pydantic>=2.13.5",
+    "pyfastx>=2.3.1",
+    "requests>=2.34.2",
+    "zstandard>=0.25.0",
+]
+
+[[project.authors]]
+name = "Jim Downie"
+email = "jd42@sanger.ac.uk"
+
+[project.scripts]
+bintools = "metabintools.cli.cli:cli"
+metabintools = "metabintools.cli.cli:cli"
+
+[build-system]
+requires = ["uv_build>=0.12.14,<0.13.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.1.1",
+    "sphinx>=9.1.0",
+    "sphinx-click>=6.2.0",
+    "sphinx-rtd-theme>=3.1.0",
+]

metabintools-0.2.0/pyproject.toml.orig

@@ -0,0 +1,35 @@
+[project]
+name = "metabintools"
+version = "0.2.0"
+description = "A toolkit for collating and manipulating metagenome bins."
+readme = "README.md"
+authors = [
+    { name = "Jim Downie", email = "jd42@sanger.ac.uk" }
+]
+license = "MIT"
+license-files = ["LICEN[CS]E*"]
+requires-python = ">=3.13"
+dependencies = [
+    "click>=8.5.0",
+    "loguru>=0.7.3",
+    "pydantic>=2.13.5",
+    "pyfastx>=2.3.1",
+    "requests>=2.34.2",
+    "zstandard>=0.25.0",
+]
+
+[project.scripts]
+bintools = "metabintools.cli.cli:cli"
+metabintools = "metabintools.cli.cli:cli"
+
+[build-system]
+requires = ["uv_build>=0.12.14,<0.13.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.1.1",
+    "sphinx>=9.1.0",
+    "sphinx-click>=6.2.0",
+    "sphinx-rtd-theme>=3.1.0",
+]

metabintools-0.2.0/src/metabintools/bin_utils.py

@@ -0,0 +1,26 @@
+from pathlib import Path
+
+
+def get_extension(file: Path) -> str:
+    if file.suffix == ".gz":
+        return "".join(file.suffixes[-2:])
+    return file.suffix
+
+
+def get_basename(file: Path | str) -> str:
+    if isinstance(file, str):
+        file = Path(file)
+
+    if file.suffix == ".gz":
+        return file.name.rsplit(".", 2)[0]
+    else:
+        return file.name.rsplit(".", 1)[0]
+
+
+def find_binfiles(directory: Path) -> list[Path]:
+    return [
+        p
+        for p in directory.glob("*")
+        if get_extension(p)
+        in {".fa", ".fna", ".fasta", ".fa.gz", ".fna.gz", ".fasta.gz"}
+    ]