viralunity 1.2.0__tar.gz

viralunity-1.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021-2026 filiperomero2
+
+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.

viralunity-1.2.0/MANIFEST.in

@@ -0,0 +1,4 @@
+recursive-include viralunity/scripts *.yaml
+recursive-include viralunity/scripts *.smk
+recursive-exclude viralunity/scripts __pycache__
+recursive-exclude viralunity/scripts *.pyc

viralunity-1.2.0/PKG-INFO

@@ -0,0 +1,121 @@
+Metadata-Version: 2.4
+Name: viralunity
+Version: 1.2.0
+Summary: A pipeline for viral metagenomics analysis.
+Author: Felippe Nacif
+Author-email: Filipe Moreira <filiperomero2@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2021-2026 filiperomero2
+        
+        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.
+        
+Project-URL: Homepage, https://github.com/InstitutoTodosPelaSaude/ViralUnity
+Project-URL: Documentation, https://viralunity.readthedocs.io/en/latest/
+Project-URL: Changelog, https://github.com/InstitutoTodosPelaSaude/ViralUnity/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/InstitutoTodosPelaSaude/ViralUnity/issues
+Keywords: metagenomics,viral,high-throughput sequencing,bioinformatics,viral genome assembly
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: <3.12,>=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: click>=8.0
+Requires-Dist: biopython>=1.81
+Requires-Dist: snakemake<8,>=7.32
+Requires-Dist: pandas>=1.5
+Requires-Dist: pulp<2.8
+Provides-Extra: dev
+Requires-Dist: black<27,>=26; extra == "dev"
+Requires-Dist: pytest>=9.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Dynamic: license-file
+
+# ViralUnity
+
+ViralUnity is a tool for analysing viral high-throughput sequencing data. It is a Python package that orchestrates Snakemake workflows for data quality control, taxonomic assignment, and reference genome assembly. ViralUnity runs on *nix systems and can process entire sequencing runs in minimal time on a regular computer.
+
+> **Full documentation:** <https://viralunity.readthedocs.io/en/latest/>
+
+## Installation
+
+Install the ViralUnity CLI from PyPI:
+
+```bash
+pip install viralunity
+```
+
+> **conda/mamba is still required at runtime.** ViralUnity orchestrates Snakemake, which
+> builds the per-rule tool environments (aligners, classifiers, assemblers) via
+> `--use-conda` on first run. Make sure conda or mamba is installed and on your `PATH`;
+> you can pre-build those environments up front with `viralunity setup --pipelines all`.
+
+To install from source for development instead:
+
+```bash
+git clone https://github.com/InstitutoTodosPelaSaude/ViralUnity.git
+cd ViralUnity
+conda env create -n viralunity -f environment.yml
+conda activate viralunity
+pip install -e .
+```
+
+Per-rule conda environments under `viralunity/scripts/envs/` are managed automatically by Snakemake; the top-level `environment.yml` only installs ViralUnity itself and its core runtime dependencies.
+
+## Quick start
+
+Six top-level subcommands are exposed via the `viralunity` CLI:
+
+```bash
+viralunity create-samplesheet --input <runs-dir> --output samples.csv
+viralunity get-databases all --output databases/
+viralunity setup --pipelines all                # pre-build per-rule conda envs
+viralunity consensus illumina --sample-sheet samples.csv --reference ref.fasta --output run/
+viralunity meta      illumina --sample-sheet samples.csv --kraken2-database <db> --output run/
+viralunity build-deacon-index --input host.fasta --output host.dcn
+```
+
+Global options: `--log-level {DEBUG,INFO,WARNING,ERROR}` and `--json-logs`
+(e.g. `viralunity --log-level DEBUG meta ...`).
+
+Each subcommand has its own `--help`; the same information is exhaustively documented in the `docs/` Sphinx site (rendered on ReadTheDocs at the link above).
+
+## Tests
+
+```bash
+make test
+```
+
+This installs the package in editable mode (if not already installed) and runs the `unittest` suite under `test/`. Snakemake dry-run tests live in `test/viralunity_dryrun_test.py` and use `pytest`.
+
+## Citation
+
+A scientific publication describing this pipeline is being prepared. Meanwhile, please cite this repository. Primary references for upstream tools (fastp, MultiQC, Minimap2, Samtools, BCFtools, BEDtools, gofasta, MEGAHIT, Racon, BLAST, Kraken2, Krona, DIAMOND, Clair3, Medaka, Deacon) are listed in the ReadTheDocs site.
+
+## License
+
+MIT — see `LICENSE`.

viralunity-1.2.0/README.md

@@ -0,0 +1,64 @@
+# ViralUnity
+
+ViralUnity is a tool for analysing viral high-throughput sequencing data. It is a Python package that orchestrates Snakemake workflows for data quality control, taxonomic assignment, and reference genome assembly. ViralUnity runs on *nix systems and can process entire sequencing runs in minimal time on a regular computer.
+
+> **Full documentation:** <https://viralunity.readthedocs.io/en/latest/>
+
+## Installation
+
+Install the ViralUnity CLI from PyPI:
+
+```bash
+pip install viralunity
+```
+
+> **conda/mamba is still required at runtime.** ViralUnity orchestrates Snakemake, which
+> builds the per-rule tool environments (aligners, classifiers, assemblers) via
+> `--use-conda` on first run. Make sure conda or mamba is installed and on your `PATH`;
+> you can pre-build those environments up front with `viralunity setup --pipelines all`.
+
+To install from source for development instead:
+
+```bash
+git clone https://github.com/InstitutoTodosPelaSaude/ViralUnity.git
+cd ViralUnity
+conda env create -n viralunity -f environment.yml
+conda activate viralunity
+pip install -e .
+```
+
+Per-rule conda environments under `viralunity/scripts/envs/` are managed automatically by Snakemake; the top-level `environment.yml` only installs ViralUnity itself and its core runtime dependencies.
+
+## Quick start
+
+Six top-level subcommands are exposed via the `viralunity` CLI:
+
+```bash
+viralunity create-samplesheet --input <runs-dir> --output samples.csv
+viralunity get-databases all --output databases/
+viralunity setup --pipelines all                # pre-build per-rule conda envs
+viralunity consensus illumina --sample-sheet samples.csv --reference ref.fasta --output run/
+viralunity meta      illumina --sample-sheet samples.csv --kraken2-database <db> --output run/
+viralunity build-deacon-index --input host.fasta --output host.dcn
+```
+
+Global options: `--log-level {DEBUG,INFO,WARNING,ERROR}` and `--json-logs`
+(e.g. `viralunity --log-level DEBUG meta ...`).
+
+Each subcommand has its own `--help`; the same information is exhaustively documented in the `docs/` Sphinx site (rendered on ReadTheDocs at the link above).
+
+## Tests
+
+```bash
+make test
+```
+
+This installs the package in editable mode (if not already installed) and runs the `unittest` suite under `test/`. Snakemake dry-run tests live in `test/viralunity_dryrun_test.py` and use `pytest`.
+
+## Citation
+
+A scientific publication describing this pipeline is being prepared. Meanwhile, please cite this repository. Primary references for upstream tools (fastp, MultiQC, Minimap2, Samtools, BCFtools, BEDtools, gofasta, MEGAHIT, Racon, BLAST, Kraken2, Krona, DIAMOND, Clair3, Medaka, Deacon) are listed in the ReadTheDocs site.
+
+## License
+
+MIT — see `LICENSE`.

viralunity-1.2.0/pyproject.toml

@@ -0,0 +1,108 @@
+[build-system]
+requires = ["setuptools>=64", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "viralunity"
+dynamic = ["version"]
+description = "A pipeline for viral metagenomics analysis."
+readme = "README.md"
+authors = [
+    { name = "Filipe Moreira", email = "filiperomero2@gmail.com" },
+    { name = "Felippe Nacif" },
+]
+license = { file = "LICENSE" }
+requires-python = ">=3.10,<3.12"
+keywords = [
+    "metagenomics",
+    "viral",
+    "high-throughput sequencing",
+    "bioinformatics",
+    "viral genome assembly",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: POSIX",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Scientific/Engineering :: Bio-Informatics",
+]
+dependencies = [
+    "pyyaml>=6.0",
+    "click>=8.0",
+    "biopython>=1.81",
+    "snakemake>=7.32,<8",
+    "pandas>=1.5",
+    # Snakemake 7.32 calls pulp.list_solvers(), which was removed in pulp 2.8.
+    "pulp<2.8",
+]
+
+[project.optional-dependencies]
+dev = [
+    "black>=26,<27",
+    "pytest>=9.0",
+    "pytest-cov>=5.0",
+    "mypy>=1.0",
+    "ruff>=0.5",
+]
+
+[project.urls]
+Homepage = "https://github.com/InstitutoTodosPelaSaude/ViralUnity"
+Documentation = "https://viralunity.readthedocs.io/en/latest/"
+Changelog = "https://github.com/InstitutoTodosPelaSaude/ViralUnity/blob/main/CHANGELOG.md"
+Issues = "https://github.com/InstitutoTodosPelaSaude/ViralUnity/issues"
+
+[project.scripts]
+viralunity = "viralunity.viralunity_cli:main"
+
+[tool.setuptools.dynamic]
+version = { attr = "viralunity.__version__" }
+
+[tool.setuptools.packages.find]
+include = ["viralunity*"]
+exclude = ["test*", "docs*", "docs-pt*"]
+
+[tool.setuptools.package-data]
+"viralunity.scripts" = ["*.smk", "**/*.smk", "envs/*.yaml"]
+
+[tool.black]
+line-length = 100
+target-version = ["py310", "py311"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+# Conservative starting set; can expand later.
+select = ["E", "F", "W", "I"]
+ignore = [
+    "E501",  # line length is handled by black where it cares; do not double-flag
+]
+
+[tool.ruff.lint.per-file-ignores]
+# Snakemake injects a `snakemake` global into `script:` files at runtime.
+# Ruff cannot see this, so silence F821 for those files.
+"viralunity/scripts/python/*.py" = ["F821"]
+
+[tool.mypy]
+python_version = "3.10"
+ignore_missing_imports = true
+warn_unused_ignores = true
+
+[[tool.mypy.overrides]]
+# Snakemake injects a `snakemake` global into `script:` files at runtime.
+module = "viralunity.scripts.python.*"
+ignore_errors = true
+
+[tool.pytest.ini_options]
+testpaths = ["test"]
+python_files = ["*_test.py"]
+python_classes = ["Test_*", "Test*"]
+python_functions = ["test_*"]
+addopts = "-m 'not empirical'"
+markers = [
+    "empirical: end-to-end tests that download real data and run full pipelines (slow, opt-in)",
+]

viralunity-1.2.0/setup.cfg

@@ -0,0 +1,9 @@
+[coverage:run]
+omit = 
+	*/test/*
+	setup.py
+
+[egg_info]
+tag_build = 
+tag_date = 0
+

viralunity-1.2.0/viralunity/__init__.py

@@ -0,0 +1,4 @@
+__program__ = "viralunity"
+_description = "A pipeline for viral metagenomics analysis."
+
+__version__ = "1.2.0"

viralunity-1.2.0/viralunity/_orchestrator.py

@@ -0,0 +1,135 @@
+"""Shared pipeline-orchestration helpers used by ``viralunity_consensus`` and
+``viralunity_meta``.
+
+Each pipeline still owns its own ``validate_args``, ``generate_config_file``,
+``run_snakemake_workflow``, and ``main`` so that existing test patches at
+those module-level names continue to work; the helpers in this module are
+called from inside those functions to remove what would otherwise be
+duplicated boilerplate.
+"""
+
+import logging
+import os
+from typing import Any, Callable, Dict, Optional
+
+from snakemake import snakemake
+
+from viralunity.config_generator import ConfigGenerator
+from viralunity.exceptions import ValidationError, ViralUnityError
+from viralunity.provenance import write_run_manifest
+
+logger = logging.getLogger(__name__)
+
+
+def start_config(args: Dict[str, Any], samples: Dict[str, list]) -> ConfigGenerator:
+    """Instantiate a ``ConfigGenerator`` and add the keys both pipelines
+    always set: samples, output, threads.
+
+    The caller is responsible for adding pipeline-specific keys (consensus
+    or metagenomics settings), per-rule resource settings, and calling
+    ``generator.save()``.
+    """
+    logger.info("Generating configuration file")
+    generator = ConfigGenerator(args["config_file"])
+    generator.add_samples(samples, args["data_type"])
+    generator.add_output(args["output"], args["run_name"])
+    generator.add_threads(args["threads"])
+    return generator
+
+
+def run_workflow(workflow_path: str, args: Dict[str, Any]) -> bool:
+    """Run a Snakemake workflow with the kwargs both pipelines share.
+
+    Args:
+        workflow_path: Absolute path to the ``.smk`` file to execute.
+        args: Pipeline argument dict. Must contain ``config_file`` and
+            ``threads_total``.
+
+    Raises:
+        ValidationError: If ``workflow_path`` does not exist.
+    """
+    logger.info("Starting Snakemake workflow")
+
+    if not os.path.isfile(workflow_path):
+        raise ValidationError(f"Workflow file not found: {workflow_path}")
+
+    successful = snakemake(
+        workflow_path,
+        configfiles=[args["config_file"]],
+        cores=args["threads_total"],
+        use_conda=True,
+        conda_prefix=args.get("conda_prefix"),
+        targets=["all"],
+    )
+
+    if successful:
+        logger.info("Snakemake workflow completed successfully")
+    else:
+        logger.error("Snakemake workflow failed")
+
+    return successful
+
+
+def run_pipeline(
+    args: Dict[str, Any],
+    *,
+    resolve_paths: Callable[[Dict[str, Any]], None],
+    validate: Callable[[Dict[str, Any]], Optional[Dict[str, list]]],
+    generate_config: Callable[[Dict[str, list], Dict[str, Any]], None],
+    run_workflow_fn: Callable[[Dict[str, Any]], bool],
+    skip_when_no_samples: bool = False,
+) -> int:
+    """The try/except ``main`` skeleton shared by both pipelines.
+
+    Args:
+        args: Pipeline argument dict.
+        resolve_paths: Called first to convert relative path args to
+            absolute paths.
+        validate: Called to validate args and return the samples dict.
+        generate_config: Called to write the Snakemake config file.
+        run_workflow_fn: Called to execute the Snakemake workflow. The
+            pipeline-specific module passes its own
+            ``run_snakemake_workflow`` so test patches at that name
+            keep working.
+        skip_when_no_samples: If ``True``, return 0 (success) when the
+            validated samples dict is empty. ``viralunity_meta`` opts in;
+            ``viralunity_consensus`` does not.
+
+    Returns:
+        Exit code (0 for success, 1 for failure).
+    """
+    try:
+        resolve_paths(args)
+        samples = validate(args)
+
+        if skip_when_no_samples and (samples is None or len(samples) == 0):
+            logger.warning("No samples were provided.")
+            return 0
+
+        generate_config(samples, args)
+
+        if args.get("create_config_only", False):
+            logger.info("Config file created. Exiting without running workflow.")
+            return 0
+
+        # Provenance: record version, config, and input checksums for the run.
+        # Best-effort — a manifest failure must never abort an analysis.
+        try:
+            manifest_path = write_run_manifest(args, samples)
+            logger.info(f"Wrote run manifest: {manifest_path}")
+        except Exception as e:
+            logger.warning(f"Could not write run manifest: {e}")
+
+        successful = run_workflow_fn(args)
+        return 0 if successful else 1
+
+    except ViralUnityError as e:
+        # Expected, user-facing failures (bad inputs, missing files/DBs, config
+        # errors). Log a clean message with the machine-readable error code so a
+        # caller/service can key off it; no stack trace for these.
+        logger.error(f"[{e.code}] {e}")
+        return 1
+    except Exception as e:
+        # Genuinely unexpected: keep the traceback for debugging.
+        logger.exception(f"Unexpected error: {e}")
+        return 1

viralunity-1.2.0/viralunity/_subprocess.py

@@ -0,0 +1,52 @@
+"""Shared subprocess helper for ViralUnity CLI commands.
+
+Internal module — not part of the public API. Used by the `get-databases`
+and `build-deacon-index` subcommands to invoke external tools (`wget`,
+`tar`, `diamond`, `deacon`, `datasets`, ...) with consistent echoing and
+error handling.
+"""
+
+from __future__ import annotations
+
+import subprocess
+from typing import Optional, Sequence
+
+import click
+
+#: Default wall-clock ceiling for a single external command (seconds). Long
+#: enough for large downloads/DB builds, but bounded so a hung tool cannot block
+#: a run (or a service worker) indefinitely. Override per-call via ``timeout``.
+DEFAULT_TIMEOUT = 6 * 60 * 60  # 6 hours
+
+
+def run_command(
+    cmd: Sequence[object],
+    cwd: Optional[str] = None,
+    timeout: Optional[float] = DEFAULT_TIMEOUT,
+) -> None:
+    """Run a subprocess command, streaming output and raising on failure.
+
+    Args:
+        cmd: Argument list (no shell). Each element is coerced to ``str``
+            when echoed; pass paths and flags as separate elements.
+        cwd: Optional working directory in which to run the command.
+        timeout: Wall-clock ceiling in seconds. Defaults to
+            ``DEFAULT_TIMEOUT``; pass ``None`` to disable.
+
+    Raises:
+        click.ClickException: If the subprocess exits non-zero or times out.
+            The exit code/timeout and command are included in the message so
+            the failure surfaces cleanly in the CLI output.
+    """
+    click.echo(f"$ {' '.join(str(c) for c in cmd)}")
+    try:
+        result = subprocess.run(list(cmd), cwd=cwd, timeout=timeout)
+    except subprocess.TimeoutExpired as e:
+        raise click.ClickException(
+            f"Command timed out after {e.timeout:.0f}s: " f"{' '.join(str(c) for c in cmd)}"
+        ) from e
+    if result.returncode != 0:
+        raise click.ClickException(
+            f"Command failed with exit code {result.returncode}: "
+            f"{' '.join(str(c) for c in cmd)}"
+        )