Wodin demo and documentation

This site exists for two reasons; to show off different core features of Wodin and to act as a source of documentation by example for people configuring a Wodin deployment. Let us know if there's something you would like to see here (via Teams or email Rich or Emma).

To see what major new features have been added, see the Wodin news blog.

Examples

First, here is a list of examples that show common ways of configuring an app. There's more information on the details of configuration in the next section.

Empty basic app

Go to app

The simplest application - a continuous time (ODE) model, with which you can edit code to create a model, visualise traces over time, and run simple sensitivity analyses. This version starts up completely empty, so the user has to start writing code to get going. Because there is no code, there will be no plot shown on startup.

See configuration here.

Start with default code

Go to app

If you want to start an application but have a model pre-loaded. This will be run immediately on startup, so the users will see a graph with a set of trajectories on it (in this case it's an SIR model of course).

Note that here, we also change the endTime attribute to make the time domain match more neatly the interesting region of the system by default.

See configuration here, and the default code itself here.

Include explanation tab

Go to app

Include a tab of guidance as the first tab in your application. This can include LaTeX-style maths, as well as images and other markdown-supported formatting.

See configuration here, the help file here (and the default code).

Fit model to data

Go to app

A simple least-squared fitting app.

You may want to distribute data, but we don't currently support pre-loading the data into the app (let us know if this is something you need). Generally, if you want to distribute the data, you should put the file within files/ and reference it here.

• Download influenza_data.csv here, and upload it into the app to get started.

Once the users have uploaded data, they'll need to go to the Options tab and link the data to their model variables, go to the "Fit" tab on the right hand pane, then select the parameter to vary, then run the fit.

See the configuration here, alongside the file to supply with the app. Within this index file we reference that file as <a href="files/fit/influenza_data.csv">influenza_data.csv</a> (see the source code for this page).

Stochastic

Go to app

The stochastic support is still in development, partly because the previous version in the shiny app was very simple.

Currently, the visualisation tab will always initially show individual traces, and there is no limit to the number that a user can select. This could make their browser quite slow.

Note that loading and saving a session from this app will rerun the model on restore, so individual traces will not necessarily be the same. We have plans to improve this in the future but it's not straightforward.

See configuration here.

Read-only code

Go to app

In cases where you do not want the users to edit the model, just interact with it, you can disable changing the code. Be sure that the initial code is provided and valid or this produces a fairly useless app!

See configuration here.

Multi-sensitivity

Go to app

You can enable multi-sensitivity in an app, by including "multiSensitivity": true in the app config. This will allow users to define multiple parameters for sensitivity, run multi-sensitivity and download summary results. Single sensitivity with plotting is still included in the app, with separate parameter settings to multi-sensitivity.

See configuration here.

General layout and configuration

For Wodin deployments, you will generally have a collection of apps (e.g., for different days in a course). These apps can all be of different types (e.g., one for fitting to data, another for running stochastic simulations, see below for details).

The file wodin.config.json

This will be core configuration for your deployment. It is in "JSON" format, which is designed more for computers than humans, but should hopefully be easy enough to work with. Keys are case sensitive (e.g., courseTitle is different to coursetitle) and quotes are required on all strings including keys. We will create a validator to help with creating these.

• courseTitle: The human-readable title for your course. This will be displayed in the top-left of every app, clicking it will return to the main landing page
• savePrefix: A single word, used to organise saved sessions within the database. This should reflect your courseTitle to some degree but not contain spaces. We use this to allow cleaning up of saved sessions once a course is finished (depending on how long you need to keep them for).
• baseUrl: The URL to find your site. For a deployment on epimodels, this will be https://epimodels.dide.ic.ac.uk/<path>, where <path> is specific to your deployment.
• appsPath: The path where each app will be found. The default is apps, so if you had an app called "ebola" and a baseURL of https://epimodels.dide.ic.ac.uk/mycourse then it would be available at https://epimodels.dide.ic.ac.uk/mycourse/apps/ebola. You can use something else here (e.g., models, example) if you prefer.

There are few others that you should leave alone:

• port: The port that the application will serve on; because this will be behind a proxy this does not really matter in a production deployment.
• odinAPI: The URL to find the odin.api server. Typically the default value http://odin.api:8001 will be appropriate here.
• redisURL: The URL to find the Redis server. Typically the default value redis://redis:6379 will be appropriate here.

At the top level, some other files and directories should exist

• index.html: A single HTML file that users can use to navigate between your apps. Clicking on the course name in the top-left of each app will return to this page. You can write your HTML however you want.
• apps/: A directory with different application configurations (see below). If you adjust appsPath you must rename this to reflect that value.
• defaultCode/: A directory with default code. If a file example.R exists, then the app at apps/example will load this code.
• help: Markdown files used as per-application help. See example for more information.
• files: Additional files that you can reference from your HTML.

As a concrete example, you can see the configuration for this demo deployment here

App-level configuration

Each app is defined by a file <name>.config.json within the apps/ directory. As with wodin.config.json this is a JSON file with fields:

• appType: The overall app type. The valid values are "basic" (visualisation of an ODE model), "stochastic" (visualisation of a discrete time stochastic model) or "fit" (simple fitting of a continuous time model)
• title: The application title, a human-readable string. This will be rendered in the title bar next to the course title, and also in the page title (so will appear in the browser's tabs).
• readOnlyCode: Boolean, (true or false indicating if the code should be non-editable. If true then the users cannot edit the model code, though they can still change parameters and run sensitivity analyses. This can be used with any of the three appType values.
• endTime: The default end time. This can be altered by the user once the app has started via the "end time" option in the Options tab. In the appType is "fit", then after the user uploads data, the end time in the data overrides this value. The idea here is that as the course designer, you may have a good idea of the likely timescale it makes sense to run the models you'll be writing over.
• stateUploadIntervalMillis: The time, in milliseconds, between saves to the server (1500 is 1.5s). This normally does not need changing. We wait this long since the last substantive change to the app state (changing the code, altering a parameter, etc) then send the state to be saved. On very slow connections it might be wise to increase his.
• help: A JSON object that controls how the help tab is rendered. If present it should have the form { "tabname": "mytabname" }, replacing mytabname with the string that you would like the help text to have. If this is provided then you must also make sure that that a file help/appname.md exists (with appname being your application name, the same as in appname.config.json).
• multiSensitivity: true or false to indicate whether multi-Sensitivity should be enabled in the app (default is false if omitted). When enabled, an additional right-hand tab, "Multi-sensitivity" will be shown, and when this is open users can define multiple sensitivity parameter settings, run multi-sensitivity and download summary results. There is currently no plotting of multi-sensitivity results. Single-parameter sensitivity is still included side-by-side with multi-sensitivity.

General points

Can't mix app types (no fit within stochastic models). Can't support *both* stochastic and deterministic models from a single app.

Not all odin features are supported. Arrays, interpolation, etc. Discrete time and stochastic models can't use output()

Unimplemented features in the backlog

We do plan on implementing these, but your feedback is welcome

• Hide a subset of variables from the interface to keep the plots simpler
• Freeze a set of parameters so that you can compare multiple parameter sets against each other (including via sensitivity)
• Download data from sensitivity plots, and from the stochastic app.
• Multiple plots at the same time; show several plots above each other so that it's easier to compare traces that have very different scales
• Better control of plotting options, including log scale axes
• Improvements to the process of creating a new configuration, seeing what it will look like, testing that it is correct, and automatically deploying it. It is not currently straightforward to run Wodin on your laptop at present.

Using the plots

Some useful tips for interacting with the plots, which are implemented using plotly.js

• Double click on a line in the legend to display only that trace in the plot. Useful for simplifying complicated plots. Unfortunately, plotly makes this a bit tricky and people on trackpads sometimes struggle.
• Click and drag anywhere on the plot to zoom in. If you drag only horizontally or vertically then it will zoom to a horizontal or vertical region only, which can be useful.
• Double click on the background of the plot to reset the zoom to show the entire plot, after zooming in.
• You can download a copy of a plot as a png image by clicking the camera icon on the plotly toolbar.