Metadata-Version: 2.4
Name: virusdicer
Version: 0.1.1
Summary: CLI toolkit for building distance-based proteomic virus phylogenies from protein or nucleotide inputs
Author: Dmitry Bespiatykh
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Environment :: Console
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click
Requires-Dist: pyrodigal-gv
Provides-Extra: dev
Requires-Dist: black; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Dynamic: license-file

<p align="center">
  <img src="https://github.com/dbespiatykh/VirusDicer/blob/main/assets/logo.png?raw=true" alt="virusdicer logo" height=200>
</p>
<hr>

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

## Workflow

<!-- workflow-mermaid:start -->
<details>
<summary>Show workflow chart</summary>

```mermaid
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.
</details>
<!-- workflow-mermaid:end -->

## Installation

External dependencies:

- [DIAMOND](https://github.com/bbuchfink/diamond) (tested with v2.1.24)
- [R](https://cran.r-project.org/) (tested with v4.5.3)
- R package [ape](https://cran.r-project.org/web/packages/ape/index.html) (tested with v5.8.1)

### If you have all the external dependencies:

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

### Conda:
```bash
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:

```bash
virusdicer --in-fna genomes/ -o virusdicer_out
```

From protein FASTAs:

```bash
virusdicer --in-faa faa/ -o virusdicer_out
```

From a DIAMOND output table:

```bash
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:

```bash
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
