virusdicer 0.1.1

CLI toolkit for building distance-based proteomic virus phylogenies from protein or nucleotide inputs

---

VirusDicer is a command-line toolkit for building distance-based proteomic virus phylogenies from protein or nucleotide inputs.

Workflow

Show workflow chart

flowchart TD
    input[Input sequences or table] --> mode{Input type}
    mode -->|--in-fna| orfs[Predict ORFs with pyrodigal-gv]
    mode -->|--in-faa| faa[Prepare protein FASTA]
    mode -->|--in-dmnd-tab| dmnd[DIAMOND output table]
    orfs --> faa
    faa --> blast[DIAMOND makedb + blastp]
    blast --> dmnd
    dmnd --> filter[Filter DIAMOND hits]
    filter --> best[Best hit per query protein and target genome]
    best --> score[Symmetric genome bitscore matrix]
    score --> dice[Dice distance matrix]
    dice --> support{Support replicates?}
    support -->|yes| reps[Bootstrap or jackknife replicates]
    reps --> tree[BioNJ tree with midpoint rooting]
    support -->|no| tree
    tree --> final[Final Newick tree]

Dice distance:

$$ D_{AB} = 1 - \frac{2AB}{AA + BB} $$

where AB is the symmetric bitscore between genomes A and B, and AA and BB are their self bitscores.

Installation

External dependencies:

• DIAMOND (tested with v2.1.24)
• R (tested with v4.5.3)
• R package ape (tested with v5.8.1)

If you have all the external dependencies:

python3 -m venv venv
source venv/bin/activate
pip install virusdicer

Conda:

conda env create --file https://raw.githubusercontent.com/dbespiatykh/VirusDicer/refs/heads/main/environment.yml
conda activate virusdicer
virusdicer -h

Usage

Usage: virusdicer [OPTIONS]

  `VirusDicer` builds a distance-based proteomic virus phylogeny.

  Examples:
    virusdicer --in-fna genomes/ -o virusdicer_out
    virusdicer --in-dmnd-tab hits.tsv -o virusdicer_out

  Provide either FAA/FNA inputs for a full end-to-end run, or a correctly
  formatted all-vs-all DIAMOND outfmt6 table with self hits and columns:
  qseqid sseqid pident length qlen slen evalue bitscore

Options:
  --in-faa TEXT                   Protein FAA inputs. Provide one or more files or directories. Provide one or more
                                  values after the option name.  [default: all_proteins.faa]
  --in-fna TEXT                   Nucleotide FASTA inputs used for ORF calling. Provide one or more files or
                                  directories. Provide one or more values after the option name.
  --in-dmnd-tab TEXT              Use an existing DIAMOND outfmt6 table instead of running DIAMOND.
  -o, --output-dir TEXT           Write pipeline outputs to this directory.  [default: virusdicer_out]
  -t, --threads INTEGER           Total worker budget for pyrodigal-gv ORF prediction, DIAMOND, and support
                                  replicate computation.  [default: 4]
  --diamond-sensitivity INTEGER   DIAMOND search sensitivity level.
                                  
                                  1 default
                                  2 fast
                                  3 mid-sensitive
                                  4 sensitive
                                  5 more-sensitive
                                  6 very-sensitive (default)
                                  7 ultra-sensitive
  --min-pident FLOAT              Minimum percent identity retained from DIAMOND hits.  [default: 30.0]
  --min-aalen FLOAT               Minimum alignment length in amino acids retained from DIAMOND hits.  [default:
                                  30.0]
  --max-evalue FLOAT              Maximum e-value retained from DIAMOND hits.  [default: 0.01]
  --min-bitscore FLOAT            Minimum bitscore retained from DIAMOND hits.  [default: 30.0]
  --min-qcov FLOAT                Minimum query coverage retained from DIAMOND hits. Accepts values like 50 or 0.5.
                                  [default: 0.5]
  --min-scov FLOAT                Minimum subject coverage retained from DIAMOND hits. Accepts values like 50 or
                                  0.5.  [default: 0.5]
  --min-protein-len INTEGER       Exclude hits where either protein is shorter than this.  [default: 50]
  --id-regex TEXT                 Regex with one capture group used to derive genome IDs from protein IDs.  [default:
                                  ^(.*)_\d+$]
  --write-score-matrix            Write the symmetric genome-vs-genome bitscore matrix.
  --support-mode [bootstrap|jackknife]
                                  Resampling strategy used when --support-replicates is greater than zero.  [default:
                                  bootstrap]
  --support-replicates INTEGER    Number of protein-level support replicates to compute for branch support.  [default:
                                  0]
  --jackknife-fraction FLOAT      Fraction of proteins to keep per genome in each jackknife replicate.  [default: 0.5]
  --support-seed INTEGER          Random seed for bootstrap or jackknife replicate generation.  [default: 1984]
  -v, --version                   Show the version and exit.
  -h, --help                      Show this message and exit.

From nucleotide FASTAs:

virusdicer --in-fna genomes/ -o virusdicer_out

From protein FASTAs:

virusdicer --in-faa faa/ -o virusdicer_out

From a DIAMOND output table:

diamond blastp \
  --query faa \
  --db db \
  --out diamond_output.tsv \
  --outfmt 6 qseqid sseqid pident length qlen slen evalue bitscore \
  --max-target-seqs 0 \
  --evalue 1000.0 \
  --more-sensitive


virusdicer --in-dmnd-tab diamond_output.tsv -o virusdicer_out

With bootstrap support:

virusdicer --in-fna genomes/ -o virusdicer_out \
  --support-replicates 1000 \
  --support-mode bootstrap

Main output

• virusdicer_out/dice_distance.tsv - Distance matrix
• virusdicer_out/genome_bitscore.tsv when --write-score-matrix is used - Score matrix
• virusdicer_out/bionj.nwk - BioNJ phylogeny

Citation

• Buchfink, B., Reuter, K. & Drost, HG. Sensitive protein alignments at tree-of-life scale using DIAMOND. Nat Methods 18, 366–368 (2021). https://doi.org/10.1038/s41592-021-01101-x

• Emmanuel Paradis, Julien Claude, Korbinian Strimmer, APE: Analyses of Phylogenetics and Evolution in R language, Bioinformatics, Volume 20, Issue 2, January 2004, Pages 289–290, https://doi.org/10.1093/bioinformatics/btg412

• O Gascuel, BIONJ: an improved version of the NJ algorithm based on a simple model of sequence data., Molecular Biology and Evolution, Volume 14, Issue 7, Jul 1997, Pages 685–695, https://doi.org/10.1093/oxfordjournals.molbev.a025808

• R Core Team (2026). R: A Language and Environment for Statistical Computing. R Foundation for Statistical Computing, Vienna, Austria. https://www.R-project.org/

• Hyatt, D., Chen, GL., LoCascio, P.F. et al. Prodigal: prokaryotic gene recognition and translation initiation site identification. BMC Bioinformatics 11, 119 (2010). https://doi.org/10.1186/1471-2105-11-119

• Larralde, M., (2022). Pyrodigal: Python bindings and interface to Prodigal, an efficient method for gene prediction in prokaryotes. Journal of Open Source Software, 7(72), 4296, https://doi.org/10.21105/joss.04296

• Camargo, A.P., Roux, S., Schulz, F. et al. Identification of mobile genetic elements with geNomad. Nat Biotechnol 42, 1303–1312 (2024). https://doi.org/10.1038/s41587-023-01953-y