jidea-56 Metadata endpoint

R/api.R

@@ -30,3 +30,44 @@
   )
   lapply(versions, function(v) scalar(as.character(v)))
 }
+
+# TODO: specify schema and rerun roxygen2::roxygenize()!!
+##' @porcelain GET /metadata => json(metadata)
+metadata <- function() {
+  # TODO: Use relevant model version - from qs if specified, else from latest available metadata file (jidea-62)
+  model_version <- scalar("0.1.0")
+  # TODO: read in correct metadata version according to model_version (jidea-62)
+  metadata_file <- sprintf("metadata_%s.json", model_version)
+  response <- read_json(metadata_file)
+  response$modelVersion <- model_version
+
+  # Helper for the options which don't come from the json
+  get_option <- function(id, label) {
+    list(id = scalar(id), label = scalar(label))
+  }
+
+  # Set available countries from daedalus package
+  # TODO: use the right version of daedalus/model
+  # TODO: get ISO ids from daedalus when available
+  country_options <- lapply(daedalus::country_names, function(country) {
+    country_string <- as.character(country)
+    get_option(country_string, country_string)
+  })
+  country_idx <- match("country", response$parameters$id)
+  response$parameters$options[[country_idx]] <- country_options
+
+  # TODO: get pathogen information from daedalus, when available (JIDEA-61)
+  pathogen_options <- list(
+    get_option("sars-cov-1", "SARS-CoV-1"),
+    get_option("sars-cov-2-pre-alpha", "SARS-CoV-2 pre-alpha (wildtype)"),
+    get_option("sars-cov-2-omicron", "SARS-CoV-2 omicron"),
+    get_option("sars-cov-2-delta", "SARS-CoV-2 delta"),
+    get_option("influenza-2009", "Influenza 2009 (Swine flu)"),
+    get_option("influenza-1957", "Influenza 1957"),
+    get_option("influenza-1918", "Influenza 1918 (Spanish flu)")
+  )
+  pathogen_idx <- match("pathogen", response$parameters$id)
+  response$parameters$options[[pathogen_idx]] <- pathogen_options
+
+  response
+}

R/parameters.R

@@ -0,0 +1,7 @@
+# Allowed parameter ids which we can pass to the model
+expected_parameters = c(
+  "country",
+  "pathogen",
+  "response",
+  "vaccine"
+)

R/util.R

@@ -5,3 +5,17 @@ scalar <- function(x) {
 package_version_string <- function(name) {
   as.character(utils::packageVersion(name))
 }
+
+system_file <- function(...) {
+  tryCatch({
+    system.file(..., mustWork = TRUE, package = "daedalus.api")
+  }, error = function(e) {
+    stop(sprintf("Failed to locate file from args\n%s",
+                 paste(list(...), collapse = " ")))
+  })
+}
+
+read_json <- function(filename) {
+  json <- jsonlite::fromJSON(system_file("json", filename))
+  json
+}

README.md

@@ -1,12 +1,9 @@
-
 # daedalus.api
 
 <!-- badges: start -->
-[![Project Status: Concept – Minimal or no implementation has been done yet, or the repository is only intended to be a limited example, demo, or proof-of-concept.](https://www.repostatus.org/badges/latest/concept.svg)](https://www.repostatus.org/#concept)
-[![CRAN status](https://www.r-pkg.org/badges/version/daedalus.api)](https://CRAN.R-project.org/package=daedalus.api)
-[![Codecov test coverage](https://codecov.io/gh/jameel-institute/daedalus.api/branch/main/graph/badge.svg)](https://app.codecov.io/gh/jameel-institute/daedalus.api?branch=main)
-[![R-CMD-check](https://github.com/jameel-institute/daedalus.api/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/jameel-institute/daedalus.api/actions/workflows/R-CMD-check.yaml)
-[![Build status](https://badge.buildkite.com/2fe5d34f1b4c4681b4e0e8d464f4fdaf44358fc48325b92580.svg)](https://buildkite.com/mrc-ide/daedalus-dot-api)
+
+[![Project Status: Concept -- Minimal or no implementation has been done yet, or the repository is only intended to be a limited example, demo, or proof-of-concept.](https://www.repostatus.org/badges/latest/concept.svg)](https://www.repostatus.org/#concept) [![CRAN status](https://www.r-pkg.org/badges/version/daedalus.api)](https://CRAN.R-project.org/package=daedalus.api) [![Codecov test coverage](https://codecov.io/gh/jameel-institute/daedalus.api/branch/main/graph/badge.svg)](https://app.codecov.io/gh/jameel-institute/daedalus.api?branch=main) [![R-CMD-check](https://github.com/jameel-institute/daedalus.api/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/jameel-institute/daedalus.api/actions/workflows/R-CMD-check.yaml) [![Build status](https://badge.buildkite.com/2fe5d34f1b4c4681b4e0e8d464f4fdaf44358fc48325b92580.svg)](https://buildkite.com/mrc-ide/daedalus-dot-api)
+
 <!-- badges: end -->
 
 _daedalus.api_ is an API package for the [_daedalus_ package](https://github.com/jameel-institute/daedalus) and is primarily intended for internal use.
@@ -37,6 +34,22 @@ curl -s http://localhost:8001 | jq
 docker stop daedalus-api
 ```
 
+## Development
+
+To add an endpoint, implement a method in `api.R` with `@porcelain` comment, then run `roxygen2::roxygenize()` to generate the porcelain code
+in `porcelain.R`. See the [porcelain docs](https://reside-ic.github.io/porcelain/articles/roxygen.html) for more details.
+
+## Model versions
+
+The API should be backwards compatible and support running older versions of the model. 
+Some endpoints support providing `modelVersion` as a query string parameter, e.g. to run or get metadata for a particular version of the model. 
+
+Metadata is stored in the `inst/json` folder, in files named `metadata_[VERSION].json` where `[VERSION]` is the first model version where
+that metadata applied. Requesting metadata for a model version will return the metadata which applies to that version, (which may have been 
+first introduced in an earlier version). The metadata response includes a `modelVersion` property - this value will be the `modelVersion`
+requested in the query string, if provided. If `modelVersion` was not provided in the query string, the returned 
+model version will be the most recent metadata's `[VERSION]`. 
+
 ## Related projects
 
 See the [_daedalus_ package](https://github.com/jameel-institute/daedalus) which implements the DAEDALUS integrated model of economic, social, and health costs of a pandemic.

inst/json/metadata_0.1.0.json

@@ -0,0 +1,47 @@
+{
+  "modelVersion": null,
+  "parameters": [
+    {
+      "id": "country",
+      "label": "Country",
+      "parameterType": "globeSelect",
+      "defaultOption": null,
+      "ordered": false,
+      "options": null
+    },
+    {
+      "id": "pathogen",
+      "label": "Disease",
+      "parameterType": "select",
+      "defaultOption": null,
+      "ordered": false,
+      "options": null
+    },
+    {
+      "id": "response",
+      "label": "Response",
+      "parameterType": "select",
+      "defaultOption": "no_closure",
+      "ordered": true,
+      "options": [
+        { "id": "no_closure", "label": "No closures" },
+        { "id": "school_closure", "label": "School closures" },
+        { "id": "business_closure", "label": "Business closures" },
+        { "id": "elimination", "label": "Elimination" }
+      ]
+    },
+    {
+      "id": "vaccine",
+      "label": "Advance vaccine investment",
+      "parameterType": "select",
+      "defaultOption": "none",
+      "ordered": true,
+      "options": [
+        { "id": "none", "label": "None" },
+        { "id": "low", "label": "Low" },
+        { "id": "medium", "label": "Medium" },
+        { "id": "high", "label": "High" }
+      ]
+    }
+  ]
+}

inst/schema/metadata.json

@@ -0,0 +1,44 @@
+{
+    "$schema": "http://json-schema.org/draft-04/schema#",
+    "type": "object",
+    "properties": {
+      "modelVersion": {
+        "type": "string",
+        "pattern": "^[0-9]+(\\.[0-9]+)*$"
+      },
+      "parameters":{
+        "type": "array",
+        "items": {
+          "type": "object",
+          "properties": {
+            "id": { "type": "string" },
+            "label": { "type": "string" },
+            "parameterType": {
+              "type": "string",
+              "enum": ["select", "globeSelect"]
+            },
+            "defaultOption": {
+              "type": ["string", "null"]
+            },
+            "ordered": { "type": "boolean" },
+            "options": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "properties":{
+                  "id": { "type": "string" },
+                  "label": { "type": "string" }
+                },
+                "additionalProperties": false,
+                "required": ["id", "label"]
+              }
+            }
+          },
+          "additionalProperties": false,
+          "required": ["id", "label", "parameterType", "defaultOption", "ordered", "options"]
+        }
+      }
+    },
+    "additionalProperties": false,
+    "required": ["modelVersion", "parameters"]
+}

tests/testthat/test-endpoints.R

@@ -25,3 +25,23 @@ test_that("Can construct the api", {
   expect_length(logs, 2L)
   expect_identical(logs[[1L]]$logger, "daedalus.api")
 })
+
+test_that("Can get metadata", {
+  endpoint <- daedalus_api_endpoint("GET", "/metadata")
+  res <- endpoint$run()
+  expect_true(res$validated)
+
+  lapply(res$data$parameters$id, function(id){
+    expect_true(id %in% expected_parameters)
+  })
+
+  # expect country ids to match those from daedalus
+  country_idx <- match("country", res$data$parameters$id)
+  country_options <- res$data$parameters$options[[country_idx]]
+  daedalus_countries = daedalus::country_names
+  expect_equal(length(country_options), length(daedalus_countries))
+  lapply(seq_along(country_options), function(idx) {
+    expect_equal(country_options[[idx]]$id, scalar(daedalus_countries[[idx]]))
+    expect_equal(country_options[[idx]]$label, scalar(daedalus_countries[[idx]]))
+  })
+})