diff --git a/docs/advanced-functionality/drag-drop-csv-tsv.rst b/docs/advanced-functionality/drag-drop-csv-tsv.rst index 00be3cd6d..cf1a11cb4 100644 --- a/docs/advanced-functionality/drag-drop-csv-tsv.rst +++ b/docs/advanced-functionality/drag-drop-csv-tsv.rst @@ -87,7 +87,11 @@ The following fields are ignored completely. (Some of these may be allowed in th month day -Fields which end with certain strings are treated as follows: - ``__autocolour``: this suffix is dropped, but the column is otherwise parsed as normal - ``__colour``: see above section on adding colours - ``__shape``: this column is currently ignored +Fields which end with certain strings are treated as follows: + +- ``__autocolour``: this suffix is dropped, but the column is otherwise parsed as normal +- ``__colour``: see above section on adding colours +- ``__shape``: this column is currently ignored The following columns are interpreted as geographic locations (see section above) and therefore are not added as a colouring: diff --git a/docs/advanced-functionality/misc.rst b/docs/advanced-functionality/misc.rst index 31d187beb..a4b526781 100644 --- a/docs/advanced-functionality/misc.rst +++ b/docs/advanced-functionality/misc.rst @@ -15,12 +15,22 @@ If a trait is not set on a node it is considered missing, as well as if (after c GISAID specific changes to behavior ----------------------------------- -**GISAID data provenance annotation** -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +GISAID data provenance annotation +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -If the dataset JSON defines a data provenance named ``"GISAID"`` (``JSON → metadata → data_provenance``, see `schema `__), then there are two changes to Auspice behaviour: 1. The GISAID data provenance text (displayed at the top of the page in auspice) will be replaced with the GISAID logo, which is also a link to `gisaid.org `__. 2. The available metadata for download is different. We now use a “Per-sample acknowledgments table” where each row is a strain in the tree, with the following columns: - ``strain`` - ``gisaid_epi_isl`` - ``genbank_accession`` - ``originating_lab`` - ``submitting_lab`` - ``author`` +If the dataset JSON defines a data provenance named ``"GISAID"`` (``JSON → metadata → data_provenance``, see `schema `__), then there are two changes to Auspice behaviour: -**Node annotated with ``gisaid_epi_isl``** -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +1. The GISAID data provenance text (displayed at the top of the page in auspice) will be replaced with the GISAID logo, which is also a link to `gisaid.org `__. +2. The available metadata for download is different. We now use a “Per-sample acknowledgments table” where each row is a strain in the tree, with the following columns: + + - ``strain`` + - ``gisaid_epi_isl`` + - ``genbank_accession`` + - ``originating_lab`` + - ``submitting_lab`` + - ``author`` + +Node annotated with ``gisaid_epi_isl`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ When hovering or clicking on tips (in the tree), nodes annotated with ``gisaid_epi_isl`` will behave slightly differently. These info-boxes will display “GISAID EPI ISL” and, in the tip-clicked info-panel, the value will also be a link to `gisaid.org `__. diff --git a/docs/advanced-functionality/second-trees.rst b/docs/advanced-functionality/second-trees.rst index 428cc6eca..ee5554868 100644 --- a/docs/advanced-functionality/second-trees.rst +++ b/docs/advanced-functionality/second-trees.rst @@ -13,6 +13,10 @@ You can compare any two datasets which you have available -- for instance if you Showing potential datasets in the sidebar ----------------------------------------- -Depending on the way you've labelled your datasets, potential second trees are available in a sidebar dropdown. These are defined by the `getAvailable API request `__. Currently, the logic in ``auspice view`` is to match all datasets which: - contain the same first "part" of the URL -- interpreted here to represent the same pathogen. - have the same number of "parts" in the URL (parts are delimited by a ``_`` in the filename or a ``/`` in the URL). - differ from the currently selected dataset by only 1 part. +Depending on the way you've labelled your datasets, potential second trees are available in a sidebar dropdown. These are defined by the :ref:`getAvailable API request `. Currently, the logic in ``auspice view`` is to match all datasets which: + +- contain the same first "part" of the URL -- interpreted here to represent the same pathogen. +- have the same number of "parts" in the URL (parts are delimited by a ``_`` in the filename or a ``/`` in the URL). +- differ from the currently selected dataset by only 1 part. .. |two-trees| image:: ../assets/tangle.png diff --git a/docs/advanced-functionality/view-settings.rst b/docs/advanced-functionality/view-settings.rst index 5fed355eb..3750ce740 100644 --- a/docs/advanced-functionality/view-settings.rst +++ b/docs/advanced-functionality/view-settings.rst @@ -1,7 +1,11 @@ View Settings ============= -View settings refer to things such as how we display the tree (radial? root-to-tip?), what panels we display (map? tree? both?), what colouring we are using etcetera. There are three ways these can be controlled: 1. The defaults are configured by the dataset creators (and stored as "display defaults" in the dataset JSON). This allows 2. Interacting with the visualisation (e.g. changing the color-by) modifies the view, and the URL is changed accordingly. For instance, change `nextstrain.org/zika `__ to have a color-by of author, and you'll see the URL silently update to `?c=author `__. If you reload the page or share this URL, then the color-by is set via this URL. 3. Narratives, in which the narrative author chooses different "views" for each page, are created by associating each page with a URL (see (2)) which defines a specific view into the data. +View settings refer to things such as how we display the tree (radial? root-to-tip?), what panels we display (map? tree? both?), what colouring we are using etcetera. There are three ways these can be controlled: + +1. The defaults are configured by the dataset creators (and stored as "display defaults" in the dataset JSON). This allows +2. Interacting with the visualisation (e.g. changing the color-by) modifies the view, and the URL is changed accordingly. For instance, change `nextstrain.org/zika `__ to have a color-by of author, and you'll see the URL silently update to `?c=author `__. If you reload the page or share this URL, then the color-by is set via this URL. +3. Narratives, in which the narrative author chooses different "views" for each page, are created by associating each page with a URL (see (2)) which defines a specific view into the data. Auspice (hardcoded) defaults ---------------------------- diff --git a/docs/customise-client/api.rst b/docs/customise-client/api.rst index e8cab6866..e750e95c1 100644 --- a/docs/customise-client/api.rst +++ b/docs/customise-client/api.rst @@ -1,6 +1,8 @@ Client Customisation API ======================== +.. warning:: + 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. Please `get in touch with us `__ if you are using these customisations so that we can work with you! This page details the available options and format of the customisations available at (client) build time. They are contained in a JSON file supplied to Auspice via @@ -9,7 +11,11 @@ This page details the available options and format of the customisations availab auspice build --extend -*Note that the hot-reloading development functionality does not work for code which is included via this client customisation mechanism.* *Thus, while you can run ``auspice develop --extend `` it will not update as you may expect!* +.. note:: + + The hot-reloading development functionality does not work for code which is included via this client customisation mechanism. Thus, while you can run ``auspice develop --extend `` it will not update as you may expect! + +.. _client-api-available-customisations: Available Customisations ------------------------ @@ -26,9 +32,9 @@ The following are definable as top-level keys of the JSON file. A useful referen - ``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. -.. +.. note:: - Please remember to make any modifications, including customisations described here, publicly available. See `the previous page <./index.rst>`__ for more details. + Please remember to make any modifications, including customisations described here, publicly available. See :doc:`the previous page ` for more details. -------------- @@ -138,9 +144,11 @@ Where the javascript file contains a default export of a React component. Specifying the API server address ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -By default, the client makes API requests (`as detailed here `__) 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. +By default, the client makes API requests (:doc:`as detailed here `) 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. + +.. note:: - Note that if you specify a ``serverAddress`` on a different origin (protocol + domain + port) than Auspice, the server will need to send CORS headers to permit the requests from Auspice. + If you specify a ``serverAddress`` on a different origin (protocol + domain + port) than Auspice, the server will need to send CORS headers to permit the requests from Auspice. -------------- diff --git a/docs/customise-client/requests.rst b/docs/customise-client/requests.rst index a9c811d23..8361637fc 100644 --- a/docs/customise-client/requests.rst +++ b/docs/customise-client/requests.rst @@ -26,7 +26,7 @@ When a dataset, narrative, or listing of available datasets is to be displayed i - ``/charon/getDataset`` -- return the requested dataset - ``/charon/getNarrative`` -- return the requested narrative -See `the server API documentation <../server/api.md>`__ for more details about the requests, or the `client customisation API `__ for the ability to change "/charon" to a different value. +See :doc:`the server API documentation <../server/api>` for more details about the requests, or the :doc:`client customisation API ` for the ability to change "/charon" to a different value. Image Requests ~~~~~~~~~~~~~~ @@ -51,4 +51,4 @@ If a map is displayed by Auspice the individual tiles are requested from api.map Google Analytics (Optional) ~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Auspice has the potential to include Google Analytics in a limited fashion. See `the client customisation API documentation `__ for how to set this. Note that these requests are only made if you specify a Google Analytics key during build-time customisation of the client. +Auspice has the potential to include Google Analytics in a limited fashion. See :ref:`the client customisation API documentation ` for how to set this. Note that these requests are only made if you specify a Google Analytics key during build-time customisation of the client. diff --git a/docs/introduction/how-to-run.rst b/docs/introduction/how-to-run.rst index 830ffffab..02bc9aa5d 100644 --- a/docs/introduction/how-to-run.rst +++ b/docs/introduction/how-to-run.rst @@ -41,12 +41,16 @@ This is the main command we'll run Auspice with, as it makes Auspice available i | narrativeDir | PATH | Directory where narratives (Markdown files) are sourced. This is ignored if you define custom handlers. | +---------------------+--------------------------+---------------------------------------------------------------------------------------------------------+ -For more complicated setups, where you define your own server handlers, see `supplying custom handlers to the Auspice server <../server/api.md#supplying-custom-handlers-to-the-auspice-server>`__. +For more complicated setups, where you define your own server handlers, see :ref:`supplying custom handlers to the Auspice server `. ``auspice build`` ----------------- -Build the client source code bundle. This is needed in three cases: 1. You have installed Auspice from source, or updated the source code. 1. You are editing the source code and need to rebuild the client 1. You wish to build a customised version of the Auspice client. See `Customising Auspice <../customise-client/index>`__ for more info. +Build the client source code bundle. This is needed in three cases: + +1. You have installed Auspice from source, or updated the source code. +2. You are editing the source code and need to rebuild the client +3. You wish to build a customised version of the Auspice client. See `Customising Auspice <../customise-client/index>`__ for more info. ``auspice develop`` ------------------- @@ -58,7 +62,7 @@ This is only useful if you are editing the client source code! ``auspice convert`` ------------------- -This is a utility command to convert between dataset formats. Currently, it only converts "Auspice v1" JSONs into "Auspice v2" JSONs, using the same code that is `programatically importable <../server/api.md#convertfromv1>`__. +This is a utility command to convert between dataset formats. Currently, it only converts "Auspice v1" JSONs into "Auspice v2" JSONs, using the same code that is :ref:`programatically importable `. Right now, ``auspice view`` will automatically convert "v1" JSONs into "v2" JSONs, so there's no need to do this yourself. @@ -67,29 +71,49 @@ Input File Formats Auspice is agnostic about the data it visualises -- they don't have to be viral genomes, or real-time, or generated in Augur. (They do, however have to be in a specific file format.) -Auspice takes two different file types: \* Datasets (the tree, map, etc.), which are defined as one or more JSON files. \* Narratives, which are specified as a Markdown file. +Auspice takes two different file types: + +* Datasets (the tree, map, etc.), which are defined as one or more JSON files. +* Narratives, which are specified as a Markdown file. -See the `Server API <../server/api.md>`__ for more details about the file formats an Auspice server (e.g. ``auspice view``) sends to the client. +See the :doc:`Server API <../server/api>` for more details about the file formats an Auspice server (e.g. ``auspice view``) sends to the client. Dataset JSONs ~~~~~~~~~~~~~ Currently we mainly use `Augur `__ to create these datasets. See `the Nextstrain documentation `__ for more details on this process. -Datasets JSONs include: \* Auspice v2 JSON (required) - `schema here `__. It includes the following information: \* ``tree``: The tree structure encoded as a deeply nested JSON object. \* Traits (such as country, divergence, collection date, attributions, etc.) are stored on each node. \* The presence of a ``children`` property indicates that it's an internal node and contains the child objects. \* ``metadata``: Additional data to control and inform the visualization. \* Frequency JSON (optional) - `example here `__ \* Generates the frequencies panel, e.g. on `nextstrain.org/flu `__. +Datasets JSONs include: + +* Auspice v2 JSON (required) - `schema here `__. It includes the following information: + * ``tree``: The tree structure encoded as a deeply nested JSON object. + * Traits (such as country, divergence, collection date, attributions, etc.) are stored on each node. + * The presence of a ``children`` property indicates that it's an internal node and contains the child objects. + * ``metadata``: Additional data to control and inform the visualization. +* Frequency JSON (optional) - `example here `__ + * Generates the frequencies panel, e.g. on `nextstrain.org/flu `__. + +.. note:: We are working on ways to make datasets in Newick / Nexus formats available. You can see an early prototype of this at `auspice-us.herokuapp.com `__ where you can drop on Newick (and CSV) files. Using BEAST trees is possible, but you have to use Augur to convert them first. -.. +.. note:: - If you happen to maintain builds that rely on Auspice v1, don’t worry - Auspice v2 is backward compatible and accepts the v1 format as well. The v1 schema is also available below. See `the v2 release notes <../releases/v2.md>`__ for details and motivation for the v2 format. + If you happen to maintain builds that rely on Auspice v1, don't worry - Auspice v2 is backward compatible and accepts the v1 format as well. The v1 schema is also available below. See :doc:`the v2 release notes <../releases/v2>` for details and motivation for the v2 format. Auspice v1 JSONs (for backwards compatibility use only) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Auspice works with the v1 format for backwards compatibility. *The zika dataset we download above is in this format.* -This format includes: \* Tree JSON (required) - `schema here `__ \* The same tree information as in the v2 JSON above in a separate file whose name *must* end with ``_tree.json``. \* Metadata JSON (required) - `schema here `__ \* The same metadata information as in the v2 JSON above in a separate file whose name *must* end with ``_meta.json`` and have the same prefix as the tree JSON above. \* Frequency JSON (optional) - `example here `__ \* Generates the frequencies panel, e.g. on `nextstrain.org/flu `__. +This format includes: + +* Tree JSON (required) - `schema here `__ + * The same tree information as in the v2 JSON above in a separate file whose name *must* end with ``_tree.json``. +* Metadata JSON (required) - `schema here `__ + * The same metadata information as in the v2 JSON above in a separate file whose name *must* end with ``_meta.json`` and have the same prefix as the tree JSON above. +* Frequency JSON (optional) - `example here `__ + * Generates the frequencies panel, e.g. on `nextstrain.org/flu `__. Narratives ~~~~~~~~~~ diff --git a/docs/introduction/install.rst b/docs/introduction/install.rst index 4c2d70d68..9d545d056 100644 --- a/docs/introduction/install.rst +++ b/docs/introduction/install.rst @@ -27,7 +27,7 @@ Install Auspice as a user npm install --global auspice -If you look at the `release notes `__ you can see the changes that have been made to Auspice (see your version of Auspice via ``auspice --version``). To upgrade, you can run +If you look at the :doc:`release notes <../releases/changelog>` you can see the changes that have been made to Auspice (see your version of Auspice via ``auspice --version``). To upgrade, you can run .. code:: bash diff --git a/docs/releases/v2.rst b/docs/releases/v2.rst index fec1cafec..0449c67ad 100644 --- a/docs/releases/v2.rst +++ b/docs/releases/v2.rst @@ -118,7 +118,7 @@ Auspice has had the ability to display two trees side-by-side for a while now (a We now use a more verbose syntax to define the display of multiple trees, specifying the entire pathname for both datasets. The above example is now "flu/seasonal/h3n2/ha/2y:flu/seasonal/h3n2/na/2y". Any available datasets can be compared using this URL syntax, even if the result is rather nonsensical. The old syntax will continue to work and will automatically correct to the new syntax (and show you a warning). -P.S. The list of available second trees, which is displayed in the sidebar, is now handed to Auspice by the `getAvailable API request `__. +P.S. The list of available second trees, which is displayed in the sidebar, is now handed to Auspice by the :ref:`getAvailable API request `. Display better dates on the tree axis ------------------------------------- @@ -142,7 +142,7 @@ If your analysis produces results in ``-`` (gaps), ``X`` (unknown residue) or `` Removal of Twitter & Google Analytics ------------------------------------- -These were a holdover from the early days when `nextstrain.org `__ and Auspice were the same thing. We've now removed all calls to Twitter, and made Google Analytics opt in. See `requests made from the client <../customise-client/requests.md>`__ for details on exactly what requests are made and how to opt-in to Google Analytics if you desire. +These were a holdover from the early days when `nextstrain.org `__ and Auspice were the same thing. We've now removed all calls to Twitter, and made Google Analytics opt in. See :doc:`requests made from the client <../customise-client/requests>` for details on exactly what requests are made and how to opt-in to Google Analytics if you desire. Improvements in the entropy panel --------------------------------- @@ -162,24 +162,24 @@ This allows custom servers (`nextstrain.org `__, for ins Importing (server) code from Auspice ------------------------------------ -Auspice now makes a few helper commands available for those who are writing custom Auspice servers. See `these docs `__ for more info. +Auspice now makes a few helper commands available for those who are writing custom Auspice servers. See :ref:`these docs ` for more info. New Auspice subcommand: ``auspice convert`` ------------------------------------------- -This is a utility command to convert between dataset formats. Currently, it only converts "Auspice v1" JSONs into "Auspice v2" JSONs, using the same code that is `programatically importable `__. +This is a utility command to convert between dataset formats. Currently, it only converts "Auspice v1" JSONs into "Auspice v2" JSONs, using the same code that is :ref:`programatically importable `. Right now, ``auspice view`` will automatically convert "v1" JSONs into "v2" JSONs, so there's no need to do this yourself. Ability to show a "build" source URL in the sidebar --------------------------------------------------- -Auspice used to contain some hard-coded logic which was used by nextstrain to display a link to the GitHub repo behind community URLs. We have now generalised this, and the `getAvailable API request `__ can define a ``buildUrl`` property for each dataset which auspice will display in the sidebar. +Auspice used to contain some hard-coded logic which was used by nextstrain to display a link to the GitHub repo behind community URLs. We have now generalised this, and the :ref:`getAvailable API request ` can define a ``buildUrl`` property for each dataset which auspice will display in the sidebar. ``auspice view`` uses a custom Auspice client if present -------------------------------------------------------- -It's possible to use ``auspice build`` to `build a custom auspice client <../customise-client/introduction.md>`__. If this has been done, then running ``auspice view`` will serve it -- before you had to run ``auspice view --customBuild``. This streamlines generating custom auspice bundles and serving them locally. +It's possible to use ``auspice build`` to :doc:`build a custom auspice client <../customise-client/overview>`. If this has been done, then running ``auspice view`` will serve it -- before you had to run ``auspice view --customBuild``. This streamlines generating custom auspice bundles and serving them locally. .. |auspice-v2-gif| image:: ../assets/v2-pie-charts.gif .. |pie-charts| image:: ../assets/v2-pie-charts.png diff --git a/docs/server/api.rst b/docs/server/api.rst index d4a2cb28f..cfd9d29ec 100644 --- a/docs/server/api.rst +++ b/docs/server/api.rst @@ -6,6 +6,8 @@ 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) +.. _server-api-charon-getavailable: + ``/charon/getAvailable`` ~~~~~~~~~~~~~~~~~~~~~~~~ @@ -49,7 +51,7 @@ Failure to return a valid JSON will result in a warning notification shown in Au 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. +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 -- :ref:`see below ` for how to convert these. Alternative file type reponses are to be documented. @@ -81,12 +83,14 @@ If a JSON is requested then the narrative file is parsed into JSON format by the res.send(JSON.stringify(blocks).replace(/