Auspice 2.46.0 customizations repo used to build a customised version of the Auspice client. We followed developer installation guide in combination with some useful information from npm Auspice page, in particular on how to get data.

# grab the GitHub auspice repo
git clone https://github.com/nextstrain/auspice.git
cd auspice

# install dependencies and build auspice
npm ci

# make `auspice` available globally
npm install --global .

Helper script to download a number of datasets for testing

# from the auspice src directory
npm run get-data

Then run auspice view --datasetDir path/to/data or auspice develop --datasetDir path/to/data to select on of the available dataset.

• https://docs.nextstrain.org/projects/auspice/en/latest/customise-client/api.html

Important!!! The functionality detailed in this page needs more attention, both in terms of testing and code development. We expect there to be some bugs and possible API changes. If you rely on this functionality, we recommend you pin your installation of Auspice to a specific version. In this case 2.46.0.

• https://docs.nextstrain.org/projects/auspice/en/latest/customise-client/api.html#available-customisations

The following are definable as top-level keys of the JSON file. A useful reference may be the customisation JSON file used by nextstrain.org.

• sidebarTheme allows modifications to the aesthetics of the sidebar. See below.
• navbarComponent a (relative) path to a JS file exporting a React component to be rendered as the nav bar. See below.
• splashComponent a (relative) path to a JS file exporting a React component to be rendered as the splash page. See below.
• browserTitle The browser title for the page. Defaults to “auspice” if not defined.
• finePrint String of Markdown to add to the “fine print” at the bottom of pages.
• plausibleDataDomain plausible.io analytics
• googleAnalyticsKey You can specify a Google Analytics key to enable (some) analytics functionality. This is deprecated and will be removed from an upcoming release.
• serverAddress Specify the address / prefix which the auspice client uses for API requests.
• mapTiles Specify the address (and other information) for the tiles used to render the map.

• https://docs.nextstrain.org/projects/auspice/en/latest/customise-client/api.html#sidebar-theme

The appearence of the sidebar can be customised by specifing a theme in the config JSON used to build Auspice. This theme is then available (via styled-components) to the components rendered in the sidebar. It is also passed to the nav bar component (see below) as the theme prop.

For instance, here is the customisation we used:

{
  "sidebarTheme": {
    "background": "#F2F2F2",
    "color": "#000",
    "sidebarBoxShadow": "rgba(0, 0, 0, 0.2)",
    "font-family": "Lato, Helvetica Neue, Helvetica, sans-serif",
    "selectedColor": "#5097BA",
    "unselectedColor": "#333"
  }
}

• https://docs.nextstrain.org/projects/auspice/en/latest/customise-client/api.html#components

One way to extend Auspice is by replacing React components with your own custom components. These custom components will receive props defined here, which can be used to update the rendering of the component using the normal react lifecycle methods. Right now this is only available for the splash page and nav-bar components, whose interfaces are defined here.

Each component must be the default export of a javascript file which is specified in the (client) config JSON passed to Auspice at build time (auspice build or auspice develop).

• https://docs.nextstrain.org/projects/auspice/en/latest/customise-client/api.html#custom-map-tiles

Auspice uses Leaflet to render the map, which requires access to a tile set in order to render the geography. By default, auspice uses Mapbox for these tiles, and we make these available for local use of auspice. If you are distributing your own version of auspice (i.e. not running it locally) you must set an appropriate API address here so that the map can fetch suitable tiles.

{
  "mapTiles": {
    "api": "API address for Leaflet to fetch map tiles",
    "attribution": "HTML-formatted attribution string to be displayed in bottom-right-hand corner of map",
    "mapboxWordmark": "(optional) should the Mapbox logo be displayed in the bottom-left of the map? (boolean)"
  }
}

Please see this discussion post for a hands-on guide to setting custom map tile info. For some examples of other tile sets you may use, see the OpenStreetMap wiki, and please remember to adhere to the licenses and terms of use for each tile server. The API address contains parameters as specified by the Leaflet API.

auspice develop --datasetDir path/to/data --extend path/to/config.json or auspice build --extend path/to/config.json

Attention. The hot-reloading development functionality does not work for code which is included via auspice build --extend <JSON> mechanism. Thus, while you can run auspice develop --extend <JSON> it will not update as you may expect!

Important! Please remember to make any modifications, including customisations described here, publicly available.

Auspice is distributed under AGPL 3.0. Any modifications made to the auspice source code, including build-time customisations as described here, must be made publicly available. We ask that the “Powered by Nextstrain” text and link, rendered below the data visualisations, be maintained in all customised versions of auspice, in keeping with the spirit of scientific citations.

Please note. I suggest to make trace of the following customization, future Auspice official release could overwrite them or make them not compatible.

1. Find Auspice installation node-modules folder and launch npm install --save typeface-open-sans
2. Search for typeface-lato in Auspice installation files and add below typeface-open-sans
3. Search for Lato in Auspisce installation files an add before Open Sans

For our installation we had to change the positon of SidebarChevrom from fixed to absolute in order to fit with the header top bar height. We moved also chevron icon to the left side of the sidebar, when scroll bar is active, the button is not usable.

• modified file /source/auspice/src/components/framework/sidebar-chevron.js line 6 and line 7

const chevronStyle = {
  position: "absolute", // position: "fixed",
  left: 3, // left: navWidth ? navWidth-12 : -12,
  ...
}

• https://docs.nextstrain.org/projects/auspice/en/latest/customise-client/requests.html

When a dataset, narrative, or listing of available datasets is to be displayed in Auspice, a selection of the following requests are made to localhost:4000.

/charon/getAvailable – return a list of available datasets and narratives /charon/getDataset – return the requested dataset /charon/getNarrative – return the requested narrative

• https://docs.nextstrain.org/projects/auspice/en/latest/customise-client/api.html#specifying-the-api-server-address

By default, the client makes API requests to “/charon/getAvailable”, “/charon/getDataset” etc. This is using the default server address of “/charon”. This can be changed by specifying serverAddress in the customisation JSON.

If you want to host builded client (auspice build --extend path/to/config.json) in your own server (e.g. https://cohesive.izs.it) and using serverAddress customization, we need a server side settings able to point every url to the root: we need to act as a single page app where index.html is always opened allowing getDataset method to be called.

By using npm live-server locally, you can run this command:

live-server --port=4000 --host=localhost --entry-file=index.html