viralQC 0.1.0__tar.gz

viralqc-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+.venv/
+.venv
+
+# Python build outputs
+dist/
+build/
+*.egg-info/
+.DS_Store
+
+# Snakemake and test outputs
+.snakemake/
+tests/
+estudo_ref/
+datasets/
+__pycache__/

viralqc-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Instituto Todos pela Saúde (ITpS)
+
+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.

viralqc-0.1.0/MANIFEST.in

@@ -0,0 +1,4 @@
+include README.md
+include pyproject.toml
+recursive-include viralqc/config/ *.yml
+recursive-include viralqc *.py

viralqc-0.1.0/PKG-INFO

@@ -0,0 +1,195 @@
+Metadata-Version: 2.4
+Name: viralQC
+Version: 0.1.0
+Summary: A tool and package for quality control of consensus virus genomes.
+Project-URL: Homepage, https://github.com/InstitutoTodosPelaSaude/viralQC
+Author-email: Filipe Zimmer Dezordi <zimmer.filipe@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: python,quality-control,snakemake,virus
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Requires-Python: <3.12,>=3.8
+Requires-Dist: colorlog>=6.3
+Requires-Dist: fastapi>=0.116
+Requires-Dist: pandas>=2.2
+Requires-Dist: python-multipart==0.0.20
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: typer>=0.16
+Requires-Dist: uvicorn[standard]>=0.35
+Provides-Extra: all
+Requires-Dist: vqc[api,cli]; extra == 'all'
+Provides-Extra: api
+Requires-Dist: fastapi>=0.116; extra == 'api'
+Requires-Dist: python-multipart==0.0.20; extra == 'api'
+Requires-Dist: uvicorn[standard]>=0.35; extra == 'api'
+Provides-Extra: cli
+Requires-Dist: colorlog>=6.3; extra == 'cli'
+Requires-Dist: typer>=0.16; extra == 'cli'
+Provides-Extra: dev
+Requires-Dist: black>=24.3; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+## Install
+
+### From pip
+
+First, install the dependencies:
+
+- [Snakemake 7.32](https://snakemake.readthedocs.io/en/v7.32.0/getting_started/installation.html)
+- [Ncbi-blast 2.16](https://ftp.ncbi.nlm.nih.gov/blast/executables/blast+/2.16.0/)
+- [Nextclade 3.15](https://docs.nextstrain.org/projects/nextclade/en/3.15.3/user/nextclade-cli/installation/)
+- [Seqtk 1.5](https://github.com/lh3/seqtk/releases/tag/v1.5)
+- [Python < 3.12](https://www.python.org/downloads/)
+
+or with micromamba
+
+```bash
+micromamba install \
+  -c conda-forge \
+  -c bioconda \
+  "python>=3.8.0,<3.12.0" \
+  "snakemake-minimal>=7.32.0,<7.33.0" \
+  "blast>=2.16.0,<2.17.0" \
+  "nextclade>=3.15.0,<3.16.0" \
+  "seqtk>=1.5.0,<1.6.0"
+```
+
+Then, install viralQC
+
+```bash
+pip install viralQC
+```
+
+### From Source
+
+```bash
+git clone https://github.com/InstitutoTodosPelaSaude/viralQC.git
+cd viralQC
+```
+
+#### Dependencies
+
+```bash
+micromamba env create -f env.yml
+micromamba activate viralQC
+```
+
+#### viralQC
+
+```bash
+pip install .
+```
+
+### Check installation (CLI)
+
+```bash
+vqc --help
+```
+
+## Usage (CLI)
+
+### get-nextclade-datasets
+
+This command configures local datasets using nextclade. It is necessary to run at least once to generate a local copy of the nextclade datasets, before running the `run-from-fasta` command
+
+```bash
+vqc get-nextclade-datasets --cores 2
+```
+
+A directory name can be specified, the default is `datasets`.
+
+```bash
+vqc get-nextclade-datasets --cores 2 --datasets-dir <directory_name>
+```
+
+### run-from-fasta
+
+This command runs several steps to identify viruses represented in the input FASTA file and executes Nextclade for each identified virus/dataset. There are two modes for viral identification:
+
+    - nextclade (default): Run `nextclade sort`
+    - blast: Run `blastn`.
+
+#### run-from-fasta (nextclade)
+
+```bash
+vqc run-from-fasta --sequences-fasta test_data/sequences.fasta
+```
+
+Some parameters can be specified:
+
+- `--output-dir` — Output directory name. **Default:** `output`
+- `--datasets-dir` — Path to the local Nextclade datasets directory. **Default:** `datasets`
+- `--ns-min-score` — Minimum score used by the Nextclade `sort` command. **Default:** `0.1`
+- `--ns-min-hits` — Minimum number of hits for Nextclade to consider a dataset. **Default:** `10`
+- `--cores` — Number of threads used in `nextclade sort` and `nextclade run`. **Default:** `1`
+
+The output directory has the following structure:
+
+```
+├── <datasets>                    # Output from nextclade sort; sequences for each dataset split into sequences.fa files.
+├── datasets_selected.tsv         # Formatted nextclade sort output showing the mapping between input sequences and local datasets.
+├── <virus/dataset>.nextclade.tsv # Nextclade run output for each identified virus, including clade assignments and QC metrics.
+├── unmapped_sequences.txt        # Names of input sequences that were not mapped to any virus.
+└── viruses.tsv                   # Nextclade sort output showing the mapping between input sequences and remote
+```
+
+#### run-from-fasta (nextclade)
+
+For a run-from-fasta analysis using BLAST to identify the corresponding virus, a BLAST database must first be created:
+
+```bash
+vqc get-blast-database
+```
+
+Some parameters can be specified:
+
+- `--output-dir` — Path to store the BLAST database.. **Default:** `datasets`
+- `--datasets-dir` — Path of local nextclade datasets. **Default:** `datasets`
+- `--cores` — Number of threads used in `nextclade sort` and `nextclade run`. **Default:** `1`
+
+
+Then:
+
+```bash
+vqc run-from-fasta --sequences-fasta test_data/sequences.fasta --sort-mode blast
+```
+
+Some parameters can be specified:
+
+- `--output-dir` — Output directory name. **Default:** `output`
+- `--datasets-dir` — Path to the local BLAST database directory. **Default:** `datasets`
+- `--cores` — Number of threads used in `nextclade sort` and `nextclade run`. **Default:** `1`
+
+The output directory has the following structure:
+
+```bash
+├── datasets_selected.tsv            # Mapping between input sequences and local datasets.
+├── <virus/dataset>.nextclade.tsv    # Nextclade run output for each identified virus, including clade assignments and QC metrics.
+├── sequences.<virus/dataset>.fasta  # Input sequences split by virus/dataset.
+├── unmapped_sequences.txt           # Names of input sequences that were not mapped to any virus.
+└── viruses.tsv                      # BLAST output.
+```
+
+## Usage (API)
+
+```bash
+vqc-server
+```
+
+Go to `http://127.0.0.1:8000/docs`
+
+### Development
+
+Install development dependencies and run `black` into `viralqc` directory.
+
+```bash
+pip install -e ".[dev]"
+black viralqc
+```

viralqc-0.1.0/README.md

@@ -0,0 +1,157 @@
+## Install
+
+### From pip
+
+First, install the dependencies:
+
+- [Snakemake 7.32](https://snakemake.readthedocs.io/en/v7.32.0/getting_started/installation.html)
+- [Ncbi-blast 2.16](https://ftp.ncbi.nlm.nih.gov/blast/executables/blast+/2.16.0/)
+- [Nextclade 3.15](https://docs.nextstrain.org/projects/nextclade/en/3.15.3/user/nextclade-cli/installation/)
+- [Seqtk 1.5](https://github.com/lh3/seqtk/releases/tag/v1.5)
+- [Python < 3.12](https://www.python.org/downloads/)
+
+or with micromamba
+
+```bash
+micromamba install \
+  -c conda-forge \
+  -c bioconda \
+  "python>=3.8.0,<3.12.0" \
+  "snakemake-minimal>=7.32.0,<7.33.0" \
+  "blast>=2.16.0,<2.17.0" \
+  "nextclade>=3.15.0,<3.16.0" \
+  "seqtk>=1.5.0,<1.6.0"
+```
+
+Then, install viralQC
+
+```bash
+pip install viralQC
+```
+
+### From Source
+
+```bash
+git clone https://github.com/InstitutoTodosPelaSaude/viralQC.git
+cd viralQC
+```
+
+#### Dependencies
+
+```bash
+micromamba env create -f env.yml
+micromamba activate viralQC
+```
+
+#### viralQC
+
+```bash
+pip install .
+```
+
+### Check installation (CLI)
+
+```bash
+vqc --help
+```
+
+## Usage (CLI)
+
+### get-nextclade-datasets
+
+This command configures local datasets using nextclade. It is necessary to run at least once to generate a local copy of the nextclade datasets, before running the `run-from-fasta` command
+
+```bash
+vqc get-nextclade-datasets --cores 2
+```
+
+A directory name can be specified, the default is `datasets`.
+
+```bash
+vqc get-nextclade-datasets --cores 2 --datasets-dir <directory_name>
+```
+
+### run-from-fasta
+
+This command runs several steps to identify viruses represented in the input FASTA file and executes Nextclade for each identified virus/dataset. There are two modes for viral identification:
+
+    - nextclade (default): Run `nextclade sort`
+    - blast: Run `blastn`.
+
+#### run-from-fasta (nextclade)
+
+```bash
+vqc run-from-fasta --sequences-fasta test_data/sequences.fasta
+```
+
+Some parameters can be specified:
+
+- `--output-dir` — Output directory name. **Default:** `output`
+- `--datasets-dir` — Path to the local Nextclade datasets directory. **Default:** `datasets`
+- `--ns-min-score` — Minimum score used by the Nextclade `sort` command. **Default:** `0.1`
+- `--ns-min-hits` — Minimum number of hits for Nextclade to consider a dataset. **Default:** `10`
+- `--cores` — Number of threads used in `nextclade sort` and `nextclade run`. **Default:** `1`
+
+The output directory has the following structure:
+
+```
+├── <datasets>                    # Output from nextclade sort; sequences for each dataset split into sequences.fa files.
+├── datasets_selected.tsv         # Formatted nextclade sort output showing the mapping between input sequences and local datasets.
+├── <virus/dataset>.nextclade.tsv # Nextclade run output for each identified virus, including clade assignments and QC metrics.
+├── unmapped_sequences.txt        # Names of input sequences that were not mapped to any virus.
+└── viruses.tsv                   # Nextclade sort output showing the mapping between input sequences and remote
+```
+
+#### run-from-fasta (nextclade)
+
+For a run-from-fasta analysis using BLAST to identify the corresponding virus, a BLAST database must first be created:
+
+```bash
+vqc get-blast-database
+```
+
+Some parameters can be specified:
+
+- `--output-dir` — Path to store the BLAST database.. **Default:** `datasets`
+- `--datasets-dir` — Path of local nextclade datasets. **Default:** `datasets`
+- `--cores` — Number of threads used in `nextclade sort` and `nextclade run`. **Default:** `1`
+
+
+Then:
+
+```bash
+vqc run-from-fasta --sequences-fasta test_data/sequences.fasta --sort-mode blast
+```
+
+Some parameters can be specified:
+
+- `--output-dir` — Output directory name. **Default:** `output`
+- `--datasets-dir` — Path to the local BLAST database directory. **Default:** `datasets`
+- `--cores` — Number of threads used in `nextclade sort` and `nextclade run`. **Default:** `1`
+
+The output directory has the following structure:
+
+```bash
+├── datasets_selected.tsv            # Mapping between input sequences and local datasets.
+├── <virus/dataset>.nextclade.tsv    # Nextclade run output for each identified virus, including clade assignments and QC metrics.
+├── sequences.<virus/dataset>.fasta  # Input sequences split by virus/dataset.
+├── unmapped_sequences.txt           # Names of input sequences that were not mapped to any virus.
+└── viruses.tsv                      # BLAST output.
+```
+
+## Usage (API)
+
+```bash
+vqc-server
+```
+
+Go to `http://127.0.0.1:8000/docs`
+
+### Development
+
+Install development dependencies and run `black` into `viralqc` directory.
+
+```bash
+pip install -e ".[dev]"
+black viralqc
+```

viralqc-0.1.0/env.yml

@@ -0,0 +1,13 @@
+name: viralQC
+
+channels:
+- bioconda
+- conda-forge
+- defaults
+
+dependencies:
+- snakemake-minimal>=7.32.0,<7.33.0
+- blast>=2.16.0,<2.17.0
+- nextclade>=3.15.0,<3.16.0
+- python>=3.8.0,<3.12.0
+- seqtk>=1.5.0,<1.6.0

viralqc-0.1.0/pyproject.toml

@@ -0,0 +1,62 @@
+[project]
+name = "viralQC"
+version = "0.1.0"
+description = "A tool and package for quality control of consensus virus genomes."
+authors = [
+    { name = "Filipe Zimmer Dezordi", email = "zimmer.filipe@gmail.com" }
+]
+readme = "README.md"
+requires-python = ">=3.8,<3.12"
+license = { text = "MIT" }
+dependencies = [
+    "typer>=0.16",
+    "fastapi>=0.116",
+    "uvicorn[standard]>=0.35",
+    "colorlog>=6.3",
+    "pyyaml>=6.0",
+    "pandas>=2.2",
+    "python-multipart==0.0.20"
+]
+
+keywords = ["virus", "quality-control", "python", "snakemake"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Intended Audience :: Science/Research",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Utilities",
+    "Development Status :: 3 - Alpha"
+]
+
+[project.optional-dependencies]
+cli = [
+    "typer>=0.16",
+    "colorlog>=6.3"
+]
+api = [
+    "fastapi>=0.116",
+    "uvicorn[standard]>=0.35",
+    "python-multipart==0.0.20"
+]
+all = [
+    "vqc[cli,api]"
+]
+dev = [
+    "black>=24.3",
+    "pytest>=8.0",
+]
+
+[project.scripts]
+vqc = "viralqc.cli:app"
+vqc-server = "viralqc.api:start"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.setuptools.package-data]
+viralqc = ["config/nextclade_datasets.yml"]
+
+[project.urls]
+Homepage = "https://github.com/InstitutoTodosPelaSaude/viralQC"