fix #219 and add quickstart

R/iidda.api/DESCRIPTION

@@ -1,6 +1,6 @@
 Package: iidda.api
 Title: IIDDA API
-Version: 0.0.2
+Version: 0.0.3
 Authors@R: 
     person("Steve", "Walker", , "swalk@mcmaster.ca", role = c("aut", "cre"))
 Description: R Bindings for the IIDDA API.

R/iidda.api/R/parse.R

@@ -1,16 +1,38 @@
 set_dict_names = function(x) setNames(x, vapply(x, getElement, character(1L), "name"))
 get_dict = function() suppressWarnings({iidda.api::ops_staging$data_dictionary() |> set_dict_names()})
 
+## converted to messager objects in zzz.R
+messages = list(
+  conversion = list(
+    "Now converting some fields from character to numeric or date. ",
+    "You can turn this off with\noptions(iidda_api_all_char = TRUE). "
+  ),
+  sort = list(
+    "Now converting some fields from character to numeric or date. ",
+    "You can turn this off with\noptions(iidda_api_all_char = TRUE). "
+  )
+)
+MakeMessage = function(msg) {
+  self = new.env()
+  self$on = TRUE
+  self$msg_msg = list(
+    "\nDo not display any iidda.api messages with",
+    "\noptions(iidda_api_msgs = FALSE).",
+    "\nMessages displayed at most once per R session.\n"
+  )
+  self$msg = c(msg, self$msg_msg)
+  self$display = function() {
+    if (isTRUE(self$on) & isTRUE(getOption("iidda_api_msgs"))) {
+      do.call(message, self$msg)
+      self$on = FALSE
+    }
+  }
+  self
+}
+
 parse_columns = function(data) {
   if (getOption("iidda_api_all_char")) return(data)
-  if (getOption("iidda_api_msgs")) {
-    message(
-      "Now converting some fields from character to numeric or date. ",
-      "You can turn this off with\noptions(iidda_api_all_char = TRUE). ",
-      "Turn these messages off with\noptions(iidda_api_msgs = FALSE).",
-      "\n"
-    )
-  }
+  messages$conversion$display()
   dict = get_dict()
   if (!all(names(data) %in% names(dict))) return(data)
   for (cc in names(data)) {
@@ -26,14 +48,7 @@ parse_columns = function(data) {
 
 arrange_rows = function(data) {
   if (!getOption("iidda_api_date_sort")) return(data)
-  if (getOption("iidda_api_msgs")) {
-    message(
-      "Now sorting by date. ",
-      "You can turn this off with\noptions(iidda_api_date_sort = FALSE). ",
-      "Turn these messages off with\noptions(iidda_api_msgs = FALSE). ",
-      "\n"
-    )
-  }
+  messages$sort$display()
   dict = get_dict()
   if (!all(names(data) %in% names(dict))) return(data)
   if (any(names(data) == "period_end_date")) {

R/iidda.api/R/zzz.R

@@ -5,11 +5,12 @@
     , iidda_api_date_sort = TRUE
     , iidda_api_msgs = TRUE
   )
-
+  messages = lapply(messages, MakeMessage)
   ops = suppressWarnings({try(do.call(make_ops_list, production), silent = TRUE)})
   ops_local = suppressWarnings({try(do.call(make_ops_list, local), silent = TRUE)})
   ops_staging = suppressWarnings({try(do.call(make_ops_list, staging), silent = TRUE)})
   assignInNamespace("ops", ops, "iidda.api")
   assignInNamespace("ops_local", ops_local, "iidda.api")
   assignInNamespace("ops_staging", ops_staging, "iidda.api")
+  assignInNamespace("messages", messages, "iidda.api")
 }

R/iidda.api/vignettes/Quickstart.Rmd

@@ -0,0 +1,56 @@
+---
+title: "Quickstart"
+output: rmarkdown::html_vignette
+vignette: >
+  %\VignetteIndexEntry{Quickstart}
+  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEncoding{UTF-8}
+---
+
+```{r, include = FALSE}
+knitr::opts_chunk$set(
+  collapse = TRUE,
+  comment = "#>"
+)
+```
+
+```{r installation, message=FALSE}
+if (!require(iidda.api)) {
+  if (!require(remotes)) install.packages("remotes")
+  remotes::install_github(
+      "canmod/iidda-tools"
+    , subdir = "R/iidda.api"
+  )
+}
+```
+
+```{r api_hook}
+api_hook = iidda.api::ops_staging
+```
+
+```{r other_packages, message=FALSE}
+library(dplyr)
+library(ggplot2)
+```
+
+## Scarlet Fever Data in Ontario
+
+```{r scarlet_fever_ontario}
+scarlet_fever_ontario = api_hook$filter(resource_type = "CANMOD CDI"
+  , iso_3166 = "CA"
+  , iso_3166_2 = "CA-ON"
+  , time_scale = "wk"
+  , disease = "scarlet-fever"
+  , period_end_date = "1929-08-01/1930-10-01"
+)
+print(scarlet_fever_ontario)
+```
+
+```{r scarlet_fever_ontario_plot, fig.width=7}
+(scarlet_fever_ontario
+  |> ggplot(aes(period_mid_date, cases_this_period))
+  + geom_line() + geom_point()
+  + ggtitle("Scarlet Fever Incidence in Ontario, Canada")
+  + theme_bw()
+)
+```