Metadata-Version: 2.5
Name: viralfetch
Version: 0.2.1
Summary: Query and download viral taxonomy, metadata and sequences (ICTV VMR + NCBI E-utilities + ICTV Report).
Author: gabrielvpina
License: MIT License
        
        Copyright (c) 2026 Gabriel Rodrigues
        
        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.
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: alv>=1.8
Requires-Dist: beautifulsoup4>=4.12
Requires-Dist: lxml>=5.0
Requires-Dist: openpyxl>=3.1
Requires-Dist: pillow>=10.0
Requires-Dist: platformdirs>=4.0
Requires-Dist: requests>=2.31
Requires-Dist: rich>=13.0
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

<div align="center">

<img src="viralfetch/assets/logo.png" alt="viralfetch logo" width="540">

<br>

![Version](https://img.shields.io/badge/version-0.2.1-blue)
![Python](https://img.shields.io/badge/python-3.10%2B-3776AB?logo=python&logoColor=white)
![License](https://img.shields.io/badge/license-MIT-green)
![CLI](https://img.shields.io/badge/CLI-Typer-0b7261)
![Output](https://img.shields.io/badge/output-Rich-009688)
![Tests](https://img.shields.io/badge/tests-passing-brightgreen)

**Viral taxonomy, sequences, trees and curated knowledge — from one command.**

</div>

viralfetch brings together the ICTV taxonomy, NCBI, the ICTV Report and
ViralZone in the terminal:

| Source | What it provides | Access |
|---|---|---|
| **ICTV VMR** | taxonomy, exemplar isolates, GenBank/RefSeq accessions | local (bundled) |
| **ICTV Report** | family chapters (text + figures), phylogenetic trees and alignments | chapters on demand · trees bundled |
| **NCBI** (E-utilities, Datasets) | taxonomy, sequences, metadata, genome counts | on demand, cached |
| **ViralZone** (SIB) | curated factsheets: host, geography, diseases, transmission, vaccines, antivirals | local (bundled) |

## Install

```bash
pip install viralfetch
viralfetch config --store-ncbi-email you@example.com   # required by NCBI for remote queries
```

Python 3.10+. An NCBI API key (`--store-ncbi-apikey KEY`) is optional and raises the
rate limit from 3 to 10 requests/s. Without an email, local commands still work.

## Quick start: profile any virus

Type a name — family, genus, species or a common virus name:

```bash
viralfetch Flaviviridae
viralfetch Orthoflavivirus denguei     # quotes are optional
viralfetch SARS-CoV-2                  # names only NCBI knows work too
```

```
╭──────────────────────────────────────────────────────────────────────────────────────────────────╮
│ Orthoflavivirus   genus · Flaviviridae                                                           │
│ ssRNA(+) · Group IV · NCBI taxid 3044782 · ✓ ICTV-accepted name            ✓ ICTV and NCBI agree │
│ Riboviria › Orthornavirae › Kitrinoviricota › Flasuviricetes › Amarillovirales › Flaviviridae ›  │
│ Orthoflavivirus                                                                                  │
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
╭───────────────────────────────────────┬──────────────────────────────────────────────────────────╮
│ ICTV (VMR)                            │ NCBI                                                     │
├───────────────────────────────────────┼──────────────────────────────────────────────────────────┤
│ 57 species                            │ 106,498 nucleotide records                               │
│ 82 isolates (57 exemplar)             │  10,792 complete genomes (by title) █░░░░░░░░░░░ 10%     │
│ ssRNA(+)                              │      85 RefSeq sequences                                 │
│ hosts: invertebrates, vertebrates     │     944 genome assemblies                                │
╰───────────────────────────────────────┴──────────────────────────────────────────────────────────╯
╭─ ViralZone · Orthoflavivirus (genus) ────────────────────────────────────────────────────────────╮
│ ● human  ● invertebrate                                                              factsheet ↗ │
│ diseases      YFV: Hemorrhagic fever, encephalitis                                               │
│               DENV: Dengue fever                                                                 │
│               ZIKV: Zika fever                                                                   │
│ transmission  Zoonosis, arthropod bite, mainly mosquitoes                                        │
│ …                                                                                                │
╰────────────────────────────────────────── ViralZone (SIB) · CC BY 4.0 · doi:10.1093/nar/gkad946 ─╯
```

The profile compares the ICTV and NCBI lineages, counts what NCBI holds and shows
the closest ViralZone factsheet. Above species (genus, family, order, …) it adds the
genome features of the taxon's RefSeq genomes:

```
╭─ Genomes · 74 RefSeq genomes ─────────────────────────────────────────────────────╮
│ size          28.3 kb median · 27.5 kb–29.9 kb  IQR · 25.4 kb–36.7 kb  range      │
│               ▁▁▅▂▂▂▂▇▄█▄▄▂▃▁▃▄▁▂▁▃▄▁                ▁                            │
│               25.4 kb                          36.7 kb                            │
│ segments      1 in every genome                                                   │
│ topology      linear 93% · not recorded 7%                                        │
│ genetic code  1 (standard) in every genome                                        │
│ proteins      9 per genome (5–16) · 97% coding · polyprotein in 100%              │
│ hosts         Homo sapiens ×5, Chiroptera ×4, Sus scrofa ×3, …                    │
│                                                                                   │
│ protein               genomes             median                                  │
│ nucleocapsid protein  ████████████ 96%    411 aa                                  │
│ spike glycoprotein    ███████████░ 91%  1,345 aa                                  │
│ membrane protein      ███████████░ 89%    227 aa                                  │
│ ORF1ab polyprotein    ██████████░░ 84%  6,758 aa                                  │
│ …                                                                                 │
│ mature peptides  nsp2 · nsp4 · nsp6 · nsp7 · nsp8 · nsp9 · nsp10 · …              │
╰────────────────────────────────────────────────────────── NCBI RefSeq (Datasets) ─╯
```

A genome is one RefSeq record, or the segments of a segmented virus summed. Topology
and genetic code (NCBI translation table) come from the records' nucleotide summaries. Partial
genomes, and single-gene records shorter than a third of the median, are set aside.
Protein names are normalised ("spike protein" = "spike glycoprotein") but come from
each record's annotation, so families annotated with gene codes (herpesvirus `ORF25`,
`UL19`) are undercounted. Taxa with more than 3,000 RefSeq records are summarised
from the first 3,000.

Useful variants:

```bash
viralfetch Orthoflavivirus --full                 # + lineage table, RefSeq list, all proteins, biology
viralfetch Coronaviridae --local                  # offline: VMR + ViralZone only
viralfetch --json Coronaviridae | jq .viralzone.factsheet.diseases
viralfetch --csv Coronaviridae > profile.csv     # one wide row
```

## Commands

### Taxonomy — `tax`, `members`

```bash
viralfetch tax Coronaviridae                          # ICTV lineage
viralfetch tax "Betacoronavirus pandemicum" --compare-ncbi   # ICTV vs NCBI, side by side
viralfetch tax SARS-CoV-2 --ncbi                      # NCBI taxonomy directly

viralfetch members Coronaviridae --rank genus         # genera, with species counts
viralfetch members Coronaviridae --tree               # full descendant hierarchy
viralfetch members Riboviria --rank family --count    # "158 families in realm Riboviria"

viralfetch members Flaviviridae --rank genus --host human        # human-infecting genera
viralfetch members Riboviria --rank family --genome dsRNA        # dsRNA families
viralfetch members Riboviria --rank genus --host plants --genome ssRNA
```

`--host` uses the VMR host source per species (`bacteria`, `vertebrates`, `plants`,
`fungi`, `soil`, `marine`, …); `human` comes from ViralZone and is recorded per genus.
`--genome` takes `dsDNA`, `ssDNA`, `dsRNA`, `ssRNA` (any polarity), `ssRNA(+)`,
`ssRNA(-)`, `ssRNA-RT`, `dsDNA-RT`, or the broad `RNA` / `DNA` / `RT`.

### Annotate a list of names — `annotate`

Turn a list of virus names (one per line: species, genera, families, old names or
common names) into a table with the full taxonomy:

```bash
viralfetch annotate names.txt -o names_taxonomy.csv     # .tsv / .json by extension
cat hits.txt | viralfetch annotate - > table.csv
```

| Columns | Content |
|---|---|
| `query`, `status`, `name`, `rank` | the input and what it resolved to (`ictv`, `ncbi` = placed via NCBI, `ncbi_only`, `not_found`) |
| `realm` … `species` | one column per ICTV rank |
| `genome`, `host_source`, `species_count` | from the VMR |
| `ncbi_taxid`, `ncbi_taxonomy_url` | the NCBI taxonomy record |
| `accession`, `accession_url` | exemplar GenBank/RefSeq accession(s) of a species, all segments in one link |
| `note` | how a name was placed, or "did you mean" suggestions |

Old and NCBI-only names are placed through NCBI (`Zaire ebolavirus` → *Orthoebolavirus
zairense*); `--local` skips NCBI.

### Sequences — `seq`

Accessions come from the VMR; records come from NCBI.

```bash
viralfetch seq "Betacoronavirus pandemicum"                   # metadata table
viralfetch seq "Betacoronavirus pandemicum" --fasta -o sars.fa
viralfetch seq "Betacoronavirus pandemicum" --protein --fasta # proteins via elink
viralfetch seq --taxon Coronaviridae --meta                   # local download estimate
viralfetch seq --taxon Filoviridae --moltype ssRNA --gb -o filo.gb
```

Downloads above 500 accessions ask for confirmation (`--yes` to skip).

### ICTV Report — `text`

```bash
viralfetch text Coronaviridae                    # chapter rendered as Markdown
viralfetch text Coronaviridae --section summary
viralfetch text Coronaviridae --images           # figures drawn in the terminal
viralfetch text Geminiviridae --raw > gemini.md
viralfetch text Betacoronavirus                  # genera/species resolve to their family
```

### Trees and alignments — `tree`, `msa`

The ICTV Report trees and alignments are bundled, so these work offline.

```bash
viralfetch tree "Betacoronavirus pandemicum"     # family tree, the species highlighted
viralfetch tree Coronaviridae --tree 2           # another figure of the same family
viralfetch tree Geminiviridae --newick > gemini.nwk

viralfetch msa "Betacoronavirus pandemicum" --consensus
viralfetch msa Coronaviridae --range 100:180
viralfetch msa Coronaviridae --fasta > coronaviridae_msa.fasta
```

```
Coronaviridae · Figure 5A · RdRp (AA) · maximum likelihood · 55 tips · 2 matches
     ┌─ Alphacoronavirus BT020
   ┌─┤
   │ └─ Scotophilus bat coronavirus 512
  ─┤          …
   │     ┌ severe acute respiratory syndrome coronavirus  ← match
   └─────┤
         └ severe acute respiratory syndrome coronavirus 2  ← match
```

### Names the VMR doesn't know

Every command falls back to NCBI taxonomy for strains, synonyms and very recent taxa,
and says so on stderr:

```bash
viralfetch tree "Dengue virus 2"
# 'Dengue virus 2' is not in the local VMR; NCBI places it in family Flaviviridae —
# its subgenus 'Euflavivirus' is highlighted instead (closest relatives on the tree).
```

## Keeping data up to date

```bash
viralfetch update                  # install a newer ICTV VMR, if one was published
viralfetch update --trees          # rebuild trees/alignments from the ICTV Report (~15 min)
viralfetch update --viralzone      # rebuild the ViralZone factsheets (~20 min)
viralfetch update --reset          # back to the bundled VMR (--trees / --viralzone too)
```

Updates go to your user data directory and only replace the current data once they
complete successfully.

## Options, output and cache

| | |
|---|---|
| `--json`, `--csv`, `--tsv` | data on stdout instead of the Rich view — every command has a table form (goes **before** the name/command) |
| `--no-cache` | refetch instead of using the cache |
| `--email`, `--api-key` | NCBI credentials for this run only |
| exit codes | `1` not found · `2` bad usage · `3` no NCBI email · `4` remote request failed |
| cache | sequences and figures kept permanently; ICTV chapters 30 days; NCBI counts 7 days — `viralfetch cache info` / `cache clear` |

Run `viralfetch COMMAND --help` for every option.

## Credits

- **ICTV** — taxonomy (VMR), Report chapters, trees and alignments. Chapter content is
  licensed [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/); `text` shows each
  chapter's citation.
- **NCBI** — E-utilities and Datasets APIs, used per the NCBI usage policies.
- **ViralZone**, SIB Swiss Institute of Bioinformatics — factsheet content (images
  CC BY 4.0; data for research and education, not for medical use). Please cite:

  > De Castro E, Hulo C, Masson P, Auchincloss A, Bridge A, Le Mercier P. ViralZone 2024
  > provides higher-resolution images and advanced virus-specific resources.
  > *Nucleic Acids Res.* 2024;52(D1):D817–D821.
  > doi:[10.1093/nar/gkad946](https://doi.org/10.1093/nar/gkad946)

## License

MIT
