more docs

Author: Phuong Quan

R/alert.R

@@ -1,3 +1,6 @@
+# =============================================================================
+# EXPORTED FUNCTIONS
+
 # -----------------------------------------------------------------------------
 #' Generate a data frame containing alert results
 #'
@@ -125,14 +128,6 @@ alertspec <- function(alert_rules,
             class = "mantis_alertspec")
 }
 
-# -----------------------------------------------------------------------------
-#' Test if object is an alertspec object
-#'
-#' @param x object to test
-#' @return Logical
-#' @noRd
-is_alertspec <- function(x) inherits(x, "mantis_alertspec")
-
 
 # -----------------------------------------------------------------------------
 #' Create set of alert rules
@@ -201,63 +196,6 @@ alert_rules <- function(...) {
   structure(ars, class = "mantis_alert_rules")
 }
 
-# -----------------------------------------------------------------------------
-#' Test if object is an alert_rules object
-#'
-#' @param x object to test
-#' @return Logical
-#' @noRd
-is_alert_rules <- function(x) inherits(x, "mantis_alert_rules")
-
-
-# -----------------------------------------------------------------------------
-#' Constructor for an alert_rule
-#'
-#' @param type type of rule
-#' @param function_call expression to pass to `eval()`, that returns either `TRUE` or `FALSE`.
-#'   Return value of `TRUE` means alert result is "FAIL"
-#' @param short_name a short computer-friendly name to uniquely identify the rule
-#' @param description brief but user-friendly explanation of why the rule result is "FAIL"
-#' @param items Named list with names corresponding to members of `item_cols`. List members are
-#'   character vectors of values contained in the named column that the rule should be applied to.
-#'   If `items = NULL` the rule will be applied to all items. See Details.
-#'
-#' @section Details: Use `items` to restrict the rule to be applied only to specified items.
-#'   `items` can either be NULL or a named list of character vectors. If `NULL`, the rule will be
-#'   applied to all items. If a named list, the names must match members of the `item_cols`
-#'   parameter in the `inputspec`, (as well as column names in the `df`), though can be a subset.
-#'   If an `item_col` is not named in the list, the rule will apply to all its members. If an
-#'   `item_col` is named in the list, the rule will only be applied when the `item_col`'s value is
-#'   contained in the corresponding character vector. When multiple `item_col`s are
-#'   specified, the rule will be applied only to items that satisfy all the conditions.
-#'
-#' @noRd
-alert_rule <- function(type,
-                       function_call,
-                       short_name,
-                       description,
-                       items = NULL) {
-
-  structure(
-    list(
-      type = type,
-      function_call = function_call,
-      short_name = short_name,
-      description = description,
-      items = items
-    ),
-    class = c(paste0("mantis_alert_rule_", type), "mantis_alert_rule")
-  )
-}
-
-# -----------------------------------------------------------------------------
-#' Test if object is an alert_rule object
-#'
-#' @param x object to test
-#' @return Logical
-#' @noRd
-is_alert_rule <- function(x) inherits(x, "mantis_alert_rule")
-
 
 # -----------------------------------------------------------------------------
 #' Built-in alert rules
@@ -285,6 +223,7 @@ is_alert_rule <- function(x) inherits(x, "mantis_alert_rule")
 #'
 NULL
 
+
 # -----------------------------------------------------------------------------
 #' Test for missing values
 #'
@@ -351,6 +290,7 @@ alert_missing <- function(extent_type = "all",
   )
 }
 
+
 # -----------------------------------------------------------------------------
 #' Test for specific values
 #'
@@ -412,6 +352,7 @@ alert_equals <- function(extent_type = "all",
   )
 }
 
+
 # -----------------------------------------------------------------------------
 #' Test for values greater than a specific value
 #'
@@ -473,6 +414,7 @@ alert_above <- function(extent_type = "all",
   )
 }
 
+
 # -----------------------------------------------------------------------------
 #' Test for values less than a specific value
 #'
@@ -533,6 +475,7 @@ alert_below <- function(extent_type = "all",
   )
 }
 
+
 # -----------------------------------------------------------------------------
 #' Test for when there is a percentage increase in latest values
 #'
@@ -596,6 +539,7 @@ alert_difference_above_perc <- function(current_period,
   )
 }
 
+
 # -----------------------------------------------------------------------------
 #' Test for when there is a percentage drop in latest values
 #'
@@ -659,6 +603,7 @@ alert_difference_below_perc <- function(current_period,
   )
 }
 
+
 # -----------------------------------------------------------------------------
 #' Create a custom alert rule
 #'
@@ -722,6 +667,76 @@ alert_custom <- function(short_name,
 }
 
 
+# =============================================================================
+# INTERNAL FUNCTIONS
+
+# -----------------------------------------------------------------------------
+#' Test if object is an alertspec object
+#'
+#' @param x object to test
+#' @return Logical
+#' @noRd
+is_alertspec <- function(x) inherits(x, "mantis_alertspec")
+
+
+# -----------------------------------------------------------------------------
+#' Test if object is an alert_rules object
+#'
+#' @param x object to test
+#' @return Logical
+#' @noRd
+is_alert_rules <- function(x) inherits(x, "mantis_alert_rules")
+
+
+# -----------------------------------------------------------------------------
+#' Constructor for an alert_rule
+#'
+#' @param type type of rule
+#' @param function_call expression to pass to `eval()`, that returns either `TRUE` or `FALSE`.
+#'   Return value of `TRUE` means alert result is "FAIL"
+#' @param short_name a short computer-friendly name to uniquely identify the rule
+#' @param description brief but user-friendly explanation of why the rule result is "FAIL"
+#' @param items Named list with names corresponding to members of `item_cols`. List members are
+#'   character vectors of values contained in the named column that the rule should be applied to.
+#'   If `items = NULL` the rule will be applied to all items. See Details.
+#'
+#' @section Details: Use `items` to restrict the rule to be applied only to specified items.
+#'   `items` can either be NULL or a named list of character vectors. If `NULL`, the rule will be
+#'   applied to all items. If a named list, the names must match members of the `item_cols`
+#'   parameter in the `inputspec`, (as well as column names in the `df`), though can be a subset.
+#'   If an `item_col` is not named in the list, the rule will apply to all its members. If an
+#'   `item_col` is named in the list, the rule will only be applied when the `item_col`'s value is
+#'   contained in the corresponding character vector. When multiple `item_col`s are
+#'   specified, the rule will be applied only to items that satisfy all the conditions.
+#'
+#' @noRd
+alert_rule <- function(type,
+                       function_call,
+                       short_name,
+                       description,
+                       items = NULL) {
+
+  structure(
+    list(
+      type = type,
+      function_call = function_call,
+      short_name = short_name,
+      description = description,
+      items = items
+    ),
+    class = c(paste0("mantis_alert_rule_", type), "mantis_alert_rule")
+  )
+}
+
+# -----------------------------------------------------------------------------
+#' Test if object is an alert_rule object
+#'
+#' @param x object to test
+#' @return Logical
+#' @noRd
+is_alert_rule <- function(x) inherits(x, "mantis_alert_rule")
+
+
 # -----------------------------------------------------------------------------
 #' Run all alert rules and return results
 #'
@@ -761,6 +776,7 @@ run_alerts <- function(prepared_df,
     dplyr::filter(alert_result %in% filter_results)
 }
 
+
 # -----------------------------------------------------------------------------
 #' Run single alert rule and return results
 #'

R/construct.R

@@ -141,6 +141,8 @@ bespoke_rmd_output <- function(df,
     tab_name = tab_name,
     tab_level = tab_level
   )
+
+  invisible(df)
 }
 
 
@@ -245,6 +247,8 @@ bespoke_rmd_alert_results <- function(df,
     alert_results = alert_results,
     inputspec = inputspec
   )
+
+  invisible(df)
 }
 
 
@@ -427,6 +431,7 @@ construct_rmd_tab <- function(df,
 #' @param inputspec Specification of data in `df`
 #' @param outputspec Specification for display of tab contents
 #' @param alert_results_subset alert_results filtered for the tab
+#' @return (invisibly) the supplied `df`
 #'
 #' @noRd
 construct_tab_content <- function(prepared_df_subset,
@@ -466,16 +471,17 @@ construct_tab_content <- function(prepared_df_subset,
 
   cat("\n")
 
+  invisible(prepared_df_subset)
 }
 
+
 # -----------------------------------------------------------------------------
 #' Generate an interactive table containing alert results using side-effects
 #'
-#' @param prepared_df_subset prepared_df filtered for the tab
-#'
 #' @param alert_results data frame returned from `run_alerts`
 #' @param inputspec Specification of data in original `df`
 #' @param filter_results only return rows where the alert result is in this vector of values. Alert results can be "PASS", "FAIL", or "NA".
+#' @return (invisibly) the supplied `df`
 #' @noRd
 construct_alert_results_content <- function(alert_results,
                                             inputspec,
@@ -509,7 +515,6 @@ construct_alert_results_content <- function(alert_results,
 #' @param has_child_tabs will there be more tabs underneath
 #' @param alert set to `TRUE` to append an alert icon
 #'
-#' @return markdown-formatted string
 #' @noRd
 construct_tab_label <- function(tab_name, tab_level, has_child_tabs = FALSE, alert = FALSE){
   if (!is.null(tab_name)) {
@@ -523,6 +528,7 @@ construct_tab_label <- function(tab_name, tab_level, has_child_tabs = FALSE, ale
   }
 }
 
+
 # -----------------------------------------------------------------------------
 #' Calculate appropriate fig.height for the chunks
 #'
@@ -535,7 +541,7 @@ construct_tab_label <- function(tab_name, tab_level, has_child_tabs = FALSE, ale
 #' @param inputspec `inputspec()` object
 #' @param outputspec `outputspec()` object
 #'
-#' @return height in inches or NULL
+#' @return numeric height in inches or NULL
 #' @noRd
 rmd_fig_height <- function(df, inputspec, outputspec){
 

R/data.R

@@ -10,6 +10,8 @@
 #' * tab - Labels to group related time series into tabs
 "example_data"
 
+
+# -----------------------------------------------------------------------------
 #' Example data frame containing numbers of antibiotic prescriptions in long format
 #'
 #' Simulated data to demonstrate package usage

R/mantis-package.R

@@ -0,0 +1,6 @@
+#' @keywords internal
+"_PACKAGE"
+
+## usethis namespace: start
+## usethis namespace: end
+NULL

R/plots-static.R

@@ -92,6 +92,7 @@ plot_heatmap_static <- function(prepared_df,
   g
 }
 
+
 # -----------------------------------------------------------------------------
 #' Create a column of plots showing value across all items
 #'
@@ -126,7 +127,6 @@ plot_multipanel_static <- function(prepared_df,
     }
   }
   data <- prepared_df |>
-#    dplyr::filter(item.Location == "SITE1") |>
   # combine item_cols into single variable
     tidyr::unite(col = "item", dplyr::all_of(item_cols_prefix(item_cols_plot)), sep = " - ") |>
     dplyr::mutate(item = factor(item, levels = unique(item)))
@@ -188,6 +188,7 @@ plot_multipanel_static <- function(prepared_df,
 }
 
 
+# -----------------------------------------------------------------------------
 #' Create an empty gglot object
 #'
 #' Use when there is no data but you still want to display a ggplot (for consistency)