Skip to contents

Including the Algorithm Viewer in publications: best practices

Source: vignettes/explanation-publications.Rmd
explanation-publications.Rmd

Audience: Researchers who want to reference the Algorithm Viewer, or share a specific algorithm through it, in a paper or other publication.

Two things you may want to cite

When you use the Algorithm Viewer in connection with a publication, there are usually two distinct things a reader cares about, and they should be referenced separately:

  1. The algorithm itself — the model you developed or are describing. This is the scientific artifact; cite it as you would any model (its own paper, DOI, or repository).
  2. The Algorithm Viewer — the software used to visualize it. This is a tool citation.

Keeping them distinct means a reader can find and reuse your algorithm independently of the viewer, and vice versa.

Cite the software

Reference the Algorithm Viewer by name, note that it was developed by Project Big Life at The Ottawa Hospital, and link to its repository:

Algorithm Viewer. Project Big Life, The Ottawa Hospital. https://github.com/Big-Life-Lab/algorithm-viewer

Record the version you used so the reference is reproducible — the version is shown in the app and recorded in the package DESCRIPTION. If the repository provides a CITATION file or a release DOI, prefer those.

Make the specific algorithm reproducible

The value of citing the viewer is that a reader can interactively explore the exact algorithm your paper describes. To make that possible:

  • Version the algorithm. Set a clear version in the algorithm YAML’s meta block and reference that version in the paper, so readers explore the same model you reported.
  • Publish all of the algorithm’s files together, in one repository. Because the viewer reads files from disk rather than from a URL, readers need both parts to view the algorithm locally:
    • the Model Parameters CSV files — the model export CSV(s) and the supporting variable and coefficient files they reference, and
    • the algorithm YAML configuration file (and, optionally, an app config file), whose model_export paths are relative to the YAML file’s own directory.
    Commit the algorithm YAML alongside the CSVs in the same repository rather than distributing it separately — the relative paths only resolve if the two travel together, and a reader who clones the repository then has everything needed to open the algorithm. Deposit that repository somewhere durable — a tagged release, or an archive with a DOI — and link to it. See Add Algorithm Viewer configurations to your own Model Parameters repository.
  • Pin the reference group. The reference-group defaults determine what every plot is calculated against. If your paper’s figures assume a particular reference patient, set those values in the algorithm YAML’s reference_group so readers start from the same baseline.

Referencing a hosted algorithm by URL

If the algorithm is served from a hosted deployment that has URL-based selection enabled, you can link readers directly to it. With allow_algorithm_in_url: true, the algorithm is selected by a query parameter:

https://your-deployment.example.org/?algorithm=my-algorithm-id

where my-algorithm-id matches a key in the deployment’s algorithms configuration. A URL like this is ideal for a paper: it takes a reader straight to an interactive view of your model with nothing to install. See the Application configuration reference for the allow_algorithm_in_url and algorithms settings.

A reproducibility checklist

Before submitting, confirm that a reader could reproduce your figures:

Next steps