metabintools 0.2.0__py3-none-any.whl

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"}
+    ]

metabintools/binstatistics.py

@@ -0,0 +1,68 @@
+from metabintools.dataclasses.contig import Contig
+
+
+class CalculateBinStatistics:
+    @staticmethod
+    def bin_size(contig_dict: dict[str, Contig]) -> int:
+        """Calculate the total size of the bin."""
+        return sum(contig.sequence_length for contig in contig_dict.values())
+
+    @staticmethod
+    def bin_n50(contig_dict: dict[str, Contig]) -> int:
+        """Calculate the N50 of the bin."""
+        lengths = [contig.sequence_length for contig in contig_dict.values()]
+        lengths.sort(reverse=True)
+        total = sum(lengths)
+        half = total // 2
+        for length in lengths:
+            if total >= half:
+                return length
+            total -= length
+        return 0
+
+    @staticmethod
+    def bin_longest_contig(contig_dict: dict[str, Contig]) -> int:
+        """Calculate the length of the longest contig in the bin."""
+        return max(contig.sequence_length for contig in contig_dict.values())
+
+    @staticmethod
+    def bin_n_circular(contig_dict: dict[str, Contig]) -> int:
+        """Calculate the number of circular contigs in the bin."""
+        return sum(
+            1 for contig in contig_dict.values() if contig.topology == "circular"
+        )
+
+    @staticmethod
+    def bin_n_unique_trnas(contig_dict: dict[str, Contig]) -> int:
+        """Extract unique tRNA products from the bin."""
+        trnas = [
+            trna for contig in contig_dict.values() for trna in (contig.trnas or [])
+        ]
+        return len(list(set(trnas)))
+
+    @staticmethod
+    def bin_has_5s(contig_dict: dict[str, Contig]) -> bool:
+        """Check if the bin contains 5S rRNA."""
+        return any(contig.has_5s for contig in contig_dict.values())
+
+    @staticmethod
+    def bin_has_16s(contig_dict: dict[str, Contig]) -> bool:
+        """Check if the bin contains 16S rRNA."""
+        return any(contig.has_16s for contig in contig_dict.values())
+
+    @staticmethod
+    def bin_has_23s(contig_dict: dict[str, Contig]) -> bool:
+        """Check if the bin contains 23S rRNA."""
+        return any(contig.has_23s for contig in contig_dict.values())
+
+    @staticmethod
+    def bin_coverage(contig_dict: dict[str, Contig]) -> float | None:
+        """Calculate the average coverage of the bin."""
+        coverages = [
+            contig.coverage
+            for contig in contig_dict.values()
+            if contig.coverage is not None
+        ]
+        if len(coverages) == len(contig_dict):
+            return sum(coverages) / len(coverages)
+        return None

metabintools/cli/cli.py

@@ -0,0 +1,40 @@
+import sys
+
+import click
+from loguru import logger
+
+from metabintools.cli.commands.export import export_group
+from metabintools.cli.commands.import_data import import_group
+from metabintools.cli.commands.merge import merge
+from metabintools.cli.commands.rename import rename_bins
+from metabintools.cli.commands.summarise import summarise_group
+from metabintools.cli.commands.trim import trim
+from metabintools.cli.commands.view import view_bins
+
+
+@click.group(context_settings={"max_content_width": 200})
+@click.version_option()
+@click.option(
+    "--log-level",
+    default="INFO",
+    help="Set the log level (DEBUG, INFO, WARNING, ERROR, CRITICAL)",
+)
+def cli(log_level):
+    logger.remove()
+    logger.add(
+        sys.stderr,
+        format="[{time:HH:mm:ss}] | metabintools | {level} - {message}",
+        level=log_level,
+    )
+
+
+cli.add_command(import_group, name="import")
+cli.add_command(export_group, name="export")
+cli.add_command(summarise_group, name="summarise")
+cli.add_command(view_bins, name="view")
+cli.add_command(merge, name="merge")
+cli.add_command(trim, name="trim")
+cli.add_command(rename_bins, name="rename")
+
+if __name__ == "__main__":
+    cli()

metabintools/cli/commands/export/__init__.py

@@ -0,0 +1,17 @@
+import click
+
+from metabintools.cli.commands.export.contig2bin import contig2bin
+from metabintools.cli.commands.export.fasta import fasta
+from metabintools.cli.commands.export.gff import gff
+
+
+@click.group()
+def export_group():
+    """
+    Tools for exporting data from a BINS file.
+    """
+
+
+export_group.add_command(contig2bin)
+export_group.add_command(fasta)
+export_group.add_command(gff)

metabintools/cli/commands/export/contig2bin.py

@@ -0,0 +1,61 @@
+from pathlib import Path
+from typing import IO
+
+import click
+from loguru import logger
+
+from metabintools.dataclasses.binset import BinSet
+from metabintools.export.binset_exporter import BinSetExporter
+
+
+@click.command("contig2bin")
+@click.option(
+    "--output",
+    "-o",
+    type=click.Path(dir_okay=False, file_okay=True, exists=False),
+    required=True,
+    default=".",
+    help="Output file path for the contig2bin mapping",
+)
+@click.option(
+    "-g",
+    "--group",
+    type=str,
+    help="Write bins from a specific group (if not specified, all bins are included)",
+)
+@click.argument(
+    "binfile",
+    type=click.File("rb"),
+    nargs=1,
+    required=True,
+    default="-",
+    help="Input binfile to export (use '-' for stdin)",
+)
+def contig2bin(
+    binfile: IO,
+    output: str,
+    group: str | None = None,
+):
+    """Write stored bin annotations to a set of GFF files.
+
+    BINFILE: Path to the binfile to write GFFs for.
+    """
+    try:
+        logger.info(f"Reading binfile from {binfile.name}...")
+        binset = BinSet.read_binfile(binfile)
+
+        output_path = Path(output)
+        logger.info(f"Writing contig2bin mapping to {output_path}")
+
+        BinSetExporter(binset).export_contig2bin(
+            path=output_path,
+            group=group,
+        )
+
+        logger.info("Contig2bin export completed successfully.")
+
+    except click.ClickException:
+        raise
+    except OSError as e:
+        logger.error(f"File I/O error: {e}")
+        raise click.ClickException(f"File I/O error: {e}")

metabintools/cli/commands/export/fasta.py

@@ -0,0 +1,88 @@
+from pathlib import Path
+from typing import IO
+
+import click
+from loguru import logger
+
+from metabintools.dataclasses.binset import BinSet
+from metabintools.export.binset_exporter import BinSetExporter
+
+
+@click.command("fasta")
+@click.option(
+    "--compress",
+    "-z",
+    "compress",
+    is_flag=True,
+    help="(optional) Compress the output using zstd.",
+)
+@click.option(
+    "--outdir",
+    "-o",
+    type=click.Path(dir_okay=True, file_okay=False),
+    required=True,
+    default=".",
+    help="Output directory for FASTA files",
+)
+@click.option(
+    "--preserve-headers",
+    "-h",
+    is_flag=True,
+    help="(optional) Preserve headers in the output FASTA file.",
+)
+@click.option(
+    "--group-fasta",
+    "-g",
+    is_flag=True,
+    help="(optional) Write each FASTA in a subdirectory named after the bin's group.",
+)
+@click.argument(
+    "binfile",
+    type=click.File("rb"),
+    nargs=1,
+    required=True,
+    default="-",
+    help="Input binfile to export (use '-' for stdin)",
+)
+def fasta(
+    binfile: IO,
+    outdir: str,
+    compress: bool = False,
+    preserve_headers: bool = False,
+    group_fasta: bool = False,
+):
+    """Export a BINS file to FASTA.
+
+    BINFILE: Path to the binfile to export FASTA for.
+    """
+    try:
+        logger.info(f"Reading binfile from {binfile.name}...")
+        binset = BinSet.read_binfile(binfile)
+
+        outdir_path = Path(outdir)
+        if not outdir_path.exists():
+            logger.info(f"Creating output directory: {outdir_path}")
+            try:
+                outdir_path.mkdir(parents=True, exist_ok=True)
+            except OSError as e:
+                logger.error(f"Failed to create output directory: {e}")
+                raise click.ClickException(
+                    f"Failed to create output directory {outdir}: {e}"
+                )
+
+        logger.info(
+            f"Exporting {len(binset.bins) if binset.bins else 0} bin(s) to FASTA..."
+        )
+        BinSetExporter(binset).export_fasta(
+            outdir=outdir_path,
+            compress=compress,
+            preserve_headers=preserve_headers,
+            group_fasta=group_fasta,
+        )
+        logger.info("FASTA export completed successfully.")
+
+    except click.ClickException:
+        raise
+    except OSError as e:
+        logger.error(f"File I/O error: {e}")
+        raise click.ClickException(f"File I/O error: {e}")

metabintools/cli/commands/export/gff.py

@@ -0,0 +1,71 @@
+from pathlib import Path
+from typing import IO
+
+import click
+from loguru import logger
+
+from metabintools.dataclasses.binset import BinSet
+from metabintools.export.binset_exporter import BinSetExporter
+
+
+@click.command("gff")
+@click.option(
+    "--outdir",
+    "-o",
+    type=click.Path(dir_okay=True, file_okay=False),
+    required=True,
+    default=".",
+    help="Output directory for GFF files",
+)
+@click.option(
+    "-g",
+    "--group-gff",
+    is_flag=True,
+    help="(optional) Write each FASTA in a subdirectory named after the bin's group.",
+)
+@click.argument(
+    "binfile",
+    type=click.File("rb"),
+    nargs=1,
+    required=True,
+    default="-",
+    help="Input binfile to export (use '-' for stdin)",
+)
+def gff(
+    binfile: IO,
+    outdir: str,
+    group_gff: bool = False,
+):
+    """Write stored bin annotations to a set of GFF files.
+
+    BINFILE: Path to the binfile to write GFFs for.
+    """
+    try:
+        logger.info(f"Reading binfile from {binfile.name}...")
+        binset = BinSet.read_binfile(binfile)
+
+        outdir_path = Path(outdir)
+        if not outdir_path.exists():
+            logger.info(f"Creating output directory: {outdir_path}")
+            try:
+                outdir_path.mkdir(parents=True, exist_ok=True)
+            except OSError as e:
+                logger.error(f"Failed to create output directory: {e}")
+                raise click.ClickException(
+                    f"Failed to create output directory {outdir}: {e}"
+                )
+
+        logger.info(
+            f"Exporting {len(binset.bins) if binset.bins else 0} bin(s) to GFF..."
+        )
+        BinSetExporter(binset).export_gff(
+            outdir=outdir_path,
+            group_gff=group_gff,
+        )
+        logger.info("GFF export completed successfully.")
+
+    except click.ClickException:
+        raise
+    except OSError as e:
+        logger.error(f"File I/O error: {e}")
+        raise click.ClickException(f"File I/O error: {e}")

metabintools/cli/commands/import_data/__init__.py

@@ -0,0 +1,25 @@
+import click
+
+from metabintools.cli.commands.import_data.import_annotation import import_annotation
+from metabintools.cli.commands.import_data.import_asm import import_assembly
+from metabintools.cli.commands.import_data.import_bins import import_binset
+from metabintools.cli.commands.import_data.import_coverage import import_coverage
+from metabintools.cli.commands.import_data.import_quality import import_quality
+from metabintools.cli.commands.import_data.import_taxonomy import import_taxonomy
+
+
+@click.group()
+def import_group():
+    """
+    Tools for importing data, both contig- and bin-level, into a BINS file.
+
+    All BINS files begin by importing an assembly via `metabintools import asm`.
+    """
+
+
+import_group.add_command(import_assembly)
+import_group.add_command(import_binset)
+import_group.add_command(import_annotation)
+import_group.add_command(import_coverage)
+import_group.add_command(import_taxonomy)
+import_group.add_command(import_quality)

metabintools/cli/commands/import_data/import_annotation.py

@@ -0,0 +1,65 @@
+import sys
+from pathlib import Path
+from typing import IO
+
+import click
+from loguru import logger
+
+from metabintools.dataclasses.binset import BinSet
+from metabintools.export.binset_exporter import BinSetExporter
+
+
+@click.command("annotation")
+@click.option(
+    "--compress",
+    "-z",
+    "compress",
+    is_flag=True,
+    help="(optional) Compress the output using zstd.",
+)
+@click.option(
+    "--overwrite",
+    type=bool,
+    help="Overwrite existing annotations if they already exist",
+    required=False,
+)
+@click.option("--output", "-o", type=click.File("wb"), default="-", required=False)
+@click.argument("binfile", type=click.File("rb"), required=True, default="-")
+@click.argument(
+    "gff",
+    type=click.Path(exists=True, dir_okay=False, file_okay=True),
+    help="The GFF file to add the annotations from.",
+    required=True,
+)
+def import_annotation(
+    binfile: IO, gff: str, output: IO, compress: bool = False, overwrite: bool = False
+):
+    """Add annotations from a GFF file to a BINS file
+
+    BINFILE: a BINS file to add the annotations to.
+    """
+    try:
+        logger.info("Reading binfile...")
+        binset = BinSet.read_binfile(binfile)
+
+        logger.info(f"Adding annotations from {Path(gff).name}...")
+        try:
+            annotated_binset = binset.add_contig_annotations(
+                Path(gff), overwrite=overwrite
+            )
+        except (ValueError, KeyError) as e:
+            logger.error(f"Failed to add annotations: {e}")
+            raise click.ClickException(f"Failed to add annotations: {e}")
+
+        logger.info("Updating statistics...")
+        annotated_binset = annotated_binset.update_statistics()
+
+        logger.info("Writing binfile...")
+        BinSetExporter(annotated_binset).write_binfile(output, compress=compress)
+        logger.info("Annotation import completed successfully.")
+
+    except click.ClickException:
+        raise
+    except OSError as e:
+        logger.error(f"File I/O error: {e}")
+        raise click.ClickException(f"File I/O error: {e}")

metabintools/cli/commands/import_data/import_asm.py

@@ -0,0 +1,65 @@
+from pathlib import Path
+from typing import IO
+
+import click
+from loguru import logger
+
+from metabintools.dataclasses.binset import BinSet
+from metabintools.enums import Assembler
+from metabintools.export.binset_exporter import BinSetExporter
+from metabintools.import_data.assembly import parse_assembly_fasta
+
+
+@click.command("asm")
+@click.option(
+    "--compress",
+    "-z",
+    "compress",
+    is_flag=True,
+    help="(optional) Compress the output using zstd.",
+)
+@click.option(
+    "--assembler",
+    type=click.Choice(Assembler),
+    help="Name of the assembler used to produce the assembly (optional)",
+    required=False,
+)
+@click.option("--output", "-o", type=click.File("wb"), default="-", required=False)
+@click.argument(
+    "assembly", type=click.Path(exists=True, dir_okay=False, file_okay=True)
+)
+def import_assembly(
+    assembly: str, assembler: Assembler | None, output: IO, compress: bool = False
+):
+    """Import a metagenome assembly to initialise a BINS file.
+
+    ASSEMBLY: an (optionally gzip compressed) FASTA file containing the assembly.
+    """
+    try:
+        assembly_path = Path(assembly)
+        logger.info(f"Parsing assembly: {assembly_path.name}")
+
+        try:
+            parsed_assembly = parse_assembly_fasta(
+                assembly_path,
+                assembler,
+            )
+        except RuntimeError as e:
+            logger.error(f"Failed to parse assembly: {e}")
+            raise click.ClickException(f"Failed to parse assembly: {e}")
+
+        logger.info(
+            f"Successfully parsed assembly with {len(parsed_assembly) if parsed_assembly else 0} contig(s)"
+        )
+
+        binset = BinSet(contigs=parsed_assembly, bins=None)
+
+        logger.info("Writing binfile...")
+        BinSetExporter(binset).write_binfile(output, compress=compress)
+        logger.info("Assembly import completed successfully.")
+
+    except click.ClickException:
+        raise
+    except OSError as e:
+        logger.error(f"File I/O error: {e}")
+        raise click.ClickException(f"File I/O error: {e}")

metabintools/cli/commands/import_data/import_bins.py

@@ -0,0 +1,92 @@
+from pathlib import Path
+from typing import IO
+
+import click
+from loguru import logger
+
+from metabintools.bin_utils import find_binfiles
+from metabintools.dataclasses.binset import BinSet
+from metabintools.export.binset_exporter import BinSetExporter
+
+
+@click.command("binset")
+@click.option(
+    "--compress",
+    "-z",
+    "compress",
+    is_flag=True,
+    help="(optional) Compress the output using zstd.",
+)
+@click.option(
+    "--group",
+    type=str,
+    help="Name to assign to the group of bins",
+    required=True,
+)
+@click.option(
+    "--binsplit-separator",
+    type=str,
+    help="Separator character to recover original contig names if bins were generated by SemiBin2, VAMB, or another binsplitting binner (optional)",
+    required=False,
+)
+@click.option("--output", "-o", type=click.File("wb"), default="-", required=False)
+@click.argument("binfile", type=click.File("rb"), required=True, default="-")
+@click.argument(
+    "fasta",
+    type=click.Path(exists=True, dir_okay=True, file_okay=True),
+    nargs=-1,
+    required=True,
+    help="Bin FASTA files, or directories containing bin FASTA files",
+)
+def import_binset(
+    binfile: IO,
+    fasta: list[str],
+    group: str,
+    output: IO,
+    compress: bool = False,
+    binsplit_separator: str | None = None,
+):
+    """Add a set of bins to a BINS file.
+
+    BINFILE: a BINS file to add the bins to
+    FASTA: a list of bin FASTA files, or alternatively a directories containing bin FASTA files
+    """
+    try:
+        logger.info("Reading binfile...")
+        binset = BinSet.read_binfile(binfile)
+
+        logger.info(f"Locating bin files from {len(fasta)} input(s)...")
+        bin_directories_files = [
+            find_binfiles(Path(dir)) for dir in fasta if Path(dir).is_dir()
+        ]
+        bins_direct_files = [Path(file) for file in fasta if Path(file).is_file()]
+        bin_files = [
+            item for sublist in bin_directories_files for item in sublist
+        ] + bins_direct_files
+
+        if not bin_files:
+            logger.error("No bin FASTA files found in the provided paths")
+            raise click.ClickException("No bin FASTA files found in the provided paths")
+
+        logger.info(f"Found {len(bin_files)} bin file(s) to import")
+
+        logger.info(f"Adding {len(bin_files)} bin(s) to binset with group '{group}'...")
+        try:
+            out_binset = binset.add_bins_from_fasta(
+                bin_files,
+                group=group,
+                binsplit_separator=binsplit_separator,
+            )
+        except RuntimeError as e:
+            logger.error(f"Failed to add bins: {e}")
+            raise click.ClickException(f"Failed to add bins: {e}")
+
+        logger.info("Writing binfile...")
+        BinSetExporter(out_binset).write_binfile(output, compress=compress)
+        logger.info("Binset import completed successfully.")
+
+    except click.ClickException:
+        raise
+    except OSError as e:
+        logger.error(f"File I/O error: {e}")
+        raise click.ClickException(f"File I/O error: {e}")