ViralQC Documentation

🌐 Language / Idioma

Esta documentação também está disponível em Português: Clique aqui

ViralQC is a Python tool and package developed for virus identification and quality control from FASTA files.

The tool uses Nextclade, BLAST, and a series of internal logics to classify viral sequences and perform quality control of complete genomes, regions, or target genes.

The tool was developed with the goal of automating the use of Nextclade and BLAST tools, focusing on integration with viral genomic databases, in order to reduce submission errors (such as submitting genomes with incorrect taxonomic information) and also to provide the user viral genome quality metrics of submitted sequences, combining Nextclade metrics provided by standardized datasets, as well as providing general metrics and annotations based on reference genomes (refseq) provided by NCBI.

Main Features

• Automatic virus identification using Nextclade and BLAST

• Quality control of viral genomes using Nextclade

• Target region extraction (CDS or specific genes)

• Analysis of multiple viruses in a single FASTA file

• Flexible configuration through the datasets.yml file

Documentation Contents

• Installation
  • Prerequisites
  • Installation via pip
  • Installation from Source Code
  • Docker
• Dataset Configuration
  • datasets.yml File Structure
  • Nextclade Datasets
  • GitHub Datasets
  • Configuration Parameters
• Scoring Logic
  • Why a Custom System?
  • Quality Metrics
  • genomeQuality Calculation
  • Target Region Extraction
• Commands and Usage
  • get-nextclade-datasets
  • get-blast-database
  • run
  • API
• Preparing NCBI Submissions
  • Grouping by Virus (virus)
  • Grouping by Sample (sample)
  • Metadata CSV
  • FASTA Headers and Annotations
  • Batch Splitting
  • Python API
• How to Add New Datasets
  • Adding a Nextclade Dataset
  • Adding a GitHub Dataset
• Output Structure
  • Main File: results.tsv (or .csv, .json)
  • Target Regions Files
  • Annotation Files
• Practical Examples
  • Example 1: Basic Dengue Analysis
  • Example 2: Influenza (Multiple Segments)
  • Example 3: Metagenomic Analysis
  • Example 4: Reproducible Database
  • Example 5: JSON Output
  • Example 6: Sensitive BLAST Search
• Troubleshooting
  • Problem 1: vqc command not found
  • Problem 2: Error downloading datasets
  • Problem 3: BLAST database not found
  • Problem 4: No sequences mapped
  • Problem 5: Memory errors
  • Problem 6: Permission denied
  • Problem 7: GitHub datasets not downloaded
  • Getting Help
• Developer Guide
  • Dataset Management
  • Analysis Pipeline

Quick Links

• GitHub Repository

• Issues/Bugs

• License: MIT

References

When using viralQC for academic purposes, also cite:

• Nextclade: Aksamentov, I., Roemer, C., Hodcroft, E. B., & Neher, R. A., (2021). Nextclade: clade assignment, mutation calling and quality control for viral genomes. JOSS, 6(67), 3773.

• BLAST: Altschul SF, et al. (1990). Basic local alignment search tool. J Mol Biol. 215(3):403-10.