Visualisation of evofr model outputs

This is a work in progress - all functionality, parameters etc are in flux

React components to parse evofr model outputs and visualise them. Based on prior work including:

• https://github.com/blab/rt-from-frequency-dynamics/tree/master/results/omicron-countries-split
• https://github.com/blab/rt-from-frequency-dynamics/tree/master/results/pango-countries

This repo includes the source code for the library (./src/lib) and a small test-app to showcase them and for development purposes (./src/App.js).

Currently the name of the library in @nextstrain/evofr-viz (as defined in package.json). Once we settle on a final name this GitHub repo will be renamed accordingly.

Examples of how to use the Components

Please see the api.md file for documentation and the code in ./src/App.js for a working example

How to import the library

If you wish to use this library in another project (i.e. outside this repo), you can use the following steps. This approach is how we use the library in forecasts-ncov. Note that this is temporary: once we publish this on npm it'll be a typical npm install command.

1. In this repo run npm pack to produce a tarball such as nextstrain-evofr-viz-0.1.0.tgz.
2. Move this tarball to your App directory
3. npm install nextstrain-evofr-viz-0.1.0.tgz (filename may be slightly different).
4. Import components in your code as normal, e.g. import { ModelDataProvider, ModelDataStatus } from 'nextstrain-evofr-viz';

How to run the test-app contained in this repo

We use a basic test-app in this repo to help with development of the library. The test app has two pages:

• http://localhost:3000 - visualises SARS-CoV-2 data (see forecasts-ncov for details).
• http://localhost:3000/dragdrop - allows a model JSON to be dropped onto the window to visualise

Firstly create a suitable environment with nodejs, e.g. by using conda:

conda create -n node18 -c conda-forge nodejs=18 # or similar
conda activate node18

Then install dependencies and run the test app:

npm ci

Then you can either run the test app fetching canonical data JSONs from S3:

npm run start

Or (recommended) pre-fetch the JSON files (to ./data):

npm run download
npm run start:local

To run the test app in a production mode:

npm run build:local
npm run serve

Linting

npm run lint

To deploy to GitHub pages

GitHub pages, at https://nextstrain.github.io/forecasts-viz/, runs the drag-and-drop page to facilitate previewing a model data JSON. To update:

npm run deploy # will automatically push assets to the gh-pages branch

How to develop the library in the context of a consuming app

In this directory (forecasts-viz) run npm develop:library. This will bundle the library code, without dependencies, to dist/ and keep it up-to-date as you make changes to the code.

In the consuming app, first install the tarball and associated dependencies as above. Then use hardlinks to swap out the bundled library code with the version we are keeping up-to-date, e.g.:

rm -rf node_modules/\@nextstrain/evofr-viz/dist
cp -lR ~/github/nextstrain/forecasts-viz/dist  node_modules/\@nextstrain/evofr-viz/dist

(your paths will differ). Then run the app and you should be using the current state of the underlying library code. If your development mode doesn't work then try the production mode to see if it's due to build-tool caching.

If you need to update dependencies of the library then you're on your own!

To undo this, in the consuming app directory delete all the dependencies and re-install: rm -rf node_modules && npm ci.