pyvoa

pyvoa (Python Virus Open Analysis) is a Python™ package that provides:

• easy access to COVID-19 and other viral disease datasets;
• tools for analysing and visualising these data through time series, charts and maps.

It is designed to be accessible to non-specialists, including high-school students learning Python, university students, science journalists and researchers unfamiliar with data extraction. Users can perform simple analyses with a few commands or build more advanced workflows in Python.

pyvoa retrieves data from multiple providers and returns them in a standardised format. Its geolocation layer reconciles country and region names, supports joins between datasets using different geographical labels, and provides geographical information for mapping. This layer can also be used independently for applications beyond viral data analysis.

Installation

pyvoa requires Python ≥ 3.10 and is published on PyPI:

pip install pyvoa

A single package provides both data as pandas or GeoPandas objects and visualisations as charts and maps, with Matplotlib and Bokeh backends installed as dependencies.

To work from a clone instead, see CONTRIBUTING.md §3.

A first example

import pyvoa.front as pf

pf.setwhom('owid')          # select a database — Our World in Data, worldwide, country-level data
pf.listwhich()              # list the available variables

# retrieve the data as a pandas DataFrame: one row per date and place
df = pf.get(where=['France', 'Italy', 'Spain'],
            which='total_deaths',
            what='daily',
            output='pandas')

# plot the same selection
pf.setvis('matplotlib')     # or 'bokeh'
pf.plot(where=['France', 'Italy', 'Spain'], which='total_deaths', what='daily')

# map total deaths across all places covered by the database
pf.map(which='total_deaths')

• where accepts a place name or a list of place names. Names are matched through the geolocation layer, regardless of case or accents ('france' matches France).

• pf.listwhere() lists the places covered by the selected database: countries for owid, French départements for spf, and so on. Requesting a place that is not covered raises a PyvoaError identifying that place.

• what specifies how the series is processed: current returns the original cumulative or instantaneous values, while daily and weekly return daily and weekly changes, respectively.

• output selects the return type: pandas, geopandas, list, dict or array.

Downloads are cached in ~/.cache/pyvoa.data_<username>/, making subsequent runs faster. Calling pf.setwhom('owid', reload=False) reuses the local copy saved by a previous call without downloading the data again.

Archived data, live data

By default, pyvoa uses archive mode, retrieving data from the project’s Zenodo mirrors wherever available. These archived snapshots preserve reproducibility even when the original providers change or their files become unavailable. Databases available only from live online sources are an exception: archive mode automatically falls back to the provider.

To retrieve data from live online sources instead of the Zenodo mirrors:

pf.setlive(True)            # use live online sources
pf.setwhom('owid')          # load the database in live mode
pf.getlive()                # True
pf.setlive(False)           # return to archive mode

The live online URL for each dataset is stored in the urlparent field of its JSON descriptor, alongside the urldata field used in archive mode. Switching modes clears the selected database, so call setwhom() again afterwards to load data from the newly selected source. Live and archived copies are cached separately and never overwrite each other. In live mode, cached files are downloaded again once they are more than a few hours old; archived files are downloaded once and retained.

Live online sources provide the latest available data, but their availability and format are less predictable: a provider’s file may have moved, changed format or disappeared since your pyvoa release, and results may vary from day to day.

Some databases, such as ebolardc, are available only from live online sources. Others are available only through the Zenodo archive because their original URLs are no longer accessible.

Exploring the API

The following introspection functions provide a quick way to explore the API. Each returns a standard Python list.

pf.listwhom()      # available databases
pf.listwhich()     # variables available in the selected database
pf.listwhat()      # ['current', 'daily', 'weekly']
pf.listwhere()     # places covered by the selected database
pf.listoption()    # processing options, e.g. 'sumall', 'nonneg', 'smooth7', 'normalize:pop100'
pf.listvis()       # ['bokeh', 'matplotlib']
pf.listoutput()    # ['geopandas', 'pandas', 'list', 'dict', 'array']

Supported databases

pyvoa includes 23 databases. pf.listwhom() returns the keys listed below, and pf.setwhom(key) selects a database. Each is described by a JSON file in pyvoa/data/. Adding a source usually requires only a new JSON descriptor, with no Python code to write (see CONTRIBUTING.md §6).

By default, data are retrieved from Zenodo mirrors where available, preserving reproducibility even after the original files become unavailable. The Availability column indicates where each database can be accessed:

• both: available from a Zenodo mirror and a live online source. Nineteen databases fall into this category, although an accessible source is not necessarily still updated.
• both (live recommended): measles-usa, included among those nineteen, tracks an ongoing epidemic. Its mirror preserves a snapshot, while the live online source provides more recent data.
• archive only: the original sources are no longer accessible for three databases. phe lost its API host, while files used by minciencia and moh were renamed or withdrawn.
• live only: ebolardc has no Zenodo mirror, so archive mode automatically falls back to the live online source. The database transcribes situation reports from the Institut National de Santé Publique, whose permission is required before republication.

Only the archived data provide reproducible results across retrieval dates; see Archived data, live data.

The Licence column refers to the data licence specified by the provider and retained with the Zenodo mirror, where one exists. These terms govern reuse of the data and are separate from pyvoa’s MIT licence. For example, the licence for imed prohibits commercial use.

Most of these databases contain COVID-19 series. The exceptions are mpoxgh, which covers mpox; ebolardc, which covers the 2026 Bundibugyo ebolavirus outbreak in the Democratic Republic of the Congo; and measles-usa, which tracks measles cases in the United States. Several providers have stopped updating their COVID-19 datasets, so the latest available date varies by database. pf.setwhom() displays this date when a database is selected.

Documentation and examples

• examples/notebooks/ — Jupyter notebooks: PyvoaForBeginners.ipynb introduces the main features; GeoByExamples.ipynb explores the geolocation layer independently; PyvoaFront-withINSEE.ipynb shows how to use pyvoa’s visualisation tools with an external dataset; and PaperExamples.ipynb runs the examples of the software paper.
• examples/pyfiles/ — Python scripts: pyvoa_for_beginners.py and geo_by_examples.py, the script equivalents of the first two notebooks, write their charts to files; insee_deaths.py, the script equivalent of PyvoaFront-withINSEE.ipynb, passes pyvoa a DataFrame built from INSEE death records; paper_examples.py, the script equivalent of PaperExamples.ipynb, reproduces the examples of a forthcoming software paper and writes its figures.
• pyvoa.org — the project website.
• pf.whattodo() — a quick reference within a Python session. It returns a DataFrame listing all keywords accepted by get, plot, hist and map, along with their allowed values.

pyvoa works in Jupyter notebooks, whether run locally or on hosted services such as Google Colab or Binder. It can also be used directly from a Python script or an interactive console.

API reference

The API reference is generated from the docstrings and is available at pyvoa.github.io/pyvoa.

To build it locally, run:

pip install -r docs/requirements.txt
make -C docs html

Then open docs/_build/html/index.html in your browser.

Community and support

• Questions about using pyvoa — ask in GitHub Discussions. Beginner questions are welcome: pyvoa is designed to be accessible to people new to data analysis.
• Bug reports and requests for new data sources — open an issue. Before reporting a problem, see SUPPORT.md for support channels and the checks worth running first. Many problems arise from changes to the original data sources.
• Contributing — see CONTRIBUTING.md, including the checklist for adding a new database.
• Community guidelines — all participants are expected to follow our Code of Conduct.
• Security or privacy concerns — contact contact@pyvoa.org privately rather than opening a public issue.

Citation

If you use pyvoa in your work, please cite it. Citation metadata is provided in CITATION.cff. On GitHub, select Cite this repository to generate a formatted citation.

See AUTHORS for authorship details and CONTRIBUTORS.md for acknowledgements of other contributions.

Funding

This work was supported by the IdEx « Université Paris Cité 2022 », funded by the French State under the « Investissements d'avenir » programme [grant number ANR-18-IDEX-0001]; and by the « Institut Covid-19 Ad Memoriam » of Université Paris Cité.

The pyvoa team is required to acknowledge both funding sources in its publications, presentations and other project materials; see the Funding section of AUTHORS. Users of pyvoa are not required to acknowledge these funding sources in their own work.

Licence

pyvoa’s code is released under the MIT licence. The data remain subject to their providers’ respective licences, listed in the supported databases table.