viralfetch 0.2.1

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

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

Install

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:

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:

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

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:

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

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.

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

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.

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:

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

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

Run viralfetch COMMAND --help for every option.

Credits

• ICTV — taxonomy (VMR), Report chapters, trees and alignments. Chapter content is licensed CC 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

License

MIT