Auspice

Auspice

  • Docs

›Using a Custom Server

Introduction

  • Overview
  • Install Auspice
  • How to Run Auspice

Advanced Functionality

  • Displaying multiple trees
  • View Settings
  • Adding extra metadata via CSV/TSV
  • Miscellaneous

Customising Auspice

  • Customising Auspice
  • Client Customisation API
  • Requests Made from the Client

Using a Custom Server

  • Auspice servers
  • Server API
  • Authentication

Narratives

  • Communicating Results Using Narratives
  • Writing a Narrative
  • Converting a narrative to PDF

Release Notes

  • Changelog
  • Auspice Version 2.0

Contributing

  • Contributing to Auspice development

Server API

Auspice client requests

The Auspice server handles requests to 3 API endpoints made by the Auspice client:

  • /charon/getAvailable (returns a list of available datasets and narratives)
  • /charon/getDataset (returns the requested dataset)
  • /charon/getNarrative (returns the requested narrative)

/charon/getAvailable

URL query arguments:

  • prefix (optional) - the pathname of the requesting page in Auspice. The getAvailable handler can use this to respond according appropriately. Unused by the default Auspice handler.

JSON Response (on success):

{
  "datasets": [
    {
      "request": "[required] The pathname of a valid dataset. \
          Will become the prefix of the getDataset request.",
      "buildUrl": "[optional] A URL to display in the sidebar representing \
          the build used to generate this analysis.",
      "secondTreeOptions": "[optional] A list of requests which should \
          appear as potential second-trees in the sidebar dropdown"
    },
    ...
  ],
  "narratives": [
    {"request": "URL of a narrative. Will become the prefix in a getNarrative request"},
    ...
  ]
}

Failure to return a valid JSON will result in a warning notification shown in Auspice.

/charon/getDataset

URL query arguments:

  • prefix (required) - the pathname of the requesting page in Auspice. Use this to determine which dataset to return.
  • type (optional) -- if specified, then the request is for an additional file (e.g. "tip-frequencies"), not the main dataset.

JSON Response (on success):

The JSON response depends on the file-type being requested.

If the type is not specified, i.e. we're requesting the "main" dataset JSON then see this JSON schema. Note that the Auspice client cannot process v1 (meta / tree) JSONs -- see below for how to convert these.

Alternative file type reponses are to be documented.

Alternative responses:

A 204 reponse will cause Auspice to show its splash page listing the available datasets & narratives. Any other non-200 reponse behaves similarly but also displays a large "error" message indicating that the dataset was not valid.

/charon/getNarrative

URL query arguments:

  • prefix (required) - the pathname of the requesting page in Auspice. Use this to determine which narrative to return.

JSON Response (on success):

The output from the parseNarrativeFile function defined below. For instance, here is the code from the default Auspice handler:

const fileContents = fs.readFileSync(pathName, 'utf8');
const blocks = parseNarrative(fileContents);
res.send(JSON.stringify(blocks).replace(/</g, '\\u003c'));

Note that in a future version of Auspice we plan to move the parsing of the narrative to the client.


Suppling custom handlers to the Auspice server

The provided Auspice servers -- i.e. auspice view and auspice develop both have a --handlers <JS> option which allows you to define your own handlers. The provided JavaScript file must export three functions, each of which handles one of the GET requests described above and must respond accordingly (see above for details).

function nameargumentsAPI endpoint
getAvailablereq, res/charon/getAvailable
getDatasetreq, res/charon/getDataset
getNarrativereq, res/charon/getNarrative

For information about the req and res arguments see the express documentation for the request object and response object, respectively.

You can see nextstrain.org's implementation of these handlers here.

Here's a pseudocode example of an implementation for the getAvailable handler which may help understanding:

const getAvailable = (req, res) => {
  try {
    /* collect available data */
    res.json(data);
  } catch (err) {
    res.statusMessage = `error message to display in client`;
    console.log(res.statusMessage); /* printed by the server, not the client */
    return res.status(500).end();
  }
};

Importing code from Auspice

The servers included in Auspice contain lots of useful code which you may want to use to either write your own handlers or entire servers. For instance, the code to convert v1 dataset JSONs to v2 JSONs (which the client requires) can be imported into your code so you don't have to reinvent the wheel!

Currently

const auspice = require("auspice");

returns an object with two properties:

convertFromV1

Signature:

const v2json = convertFromV1({tree, meta})

where tree is the v1 tree JSON, and meta the v1 meta JSON.

Returns:

An object representing the v2 JSON defined by this schema.

parseNarrativeFile

Signature:

const blocks = parseNarrativeFile(fileContents);

where fileContents is a string representation of the narrative Markdown file.

Returns:

An array of objects, each entry representing a different narrative "block" or "page". Each object has properties

  • __html -- the HTML to render in the sidebar to form the narrative
  • dataset -- the dataset associated with this block
  • query -- the query associated with this block
Last updated on 3/22/2020
← Auspice serversAuthentication →
  • Auspice client requests
    • /charon/getAvailable
    • /charon/getDataset
    • /charon/getNarrative
  • Suppling custom handlers to the Auspice server
  • Importing code from Auspice
    • convertFromV1
    • parseNarrativeFile
Auspice
External Links
GitHub repoNPM packageNextstrain
Contact Us
emailtwitter
Website built by James Hadfield using Docusaurus
If you use auspice, please cite Hadfield et al., 2018
Copyright © 2014-2020 Richard Neher & Trevor Bedford