Merge pull request #43 from ThomUK/label_limits

Add `annotate_limits` argument to spcr_make_report()

Thanks @francisbarton!

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: SPCreporter
 Title: Creates Metric Reports using Statistical Process Control in the NHS style
-Version: 0.1.5.6
+Version: 0.1.6
 Authors@R: c(
     person("Tom", "Smith",, "[email protected]", role = c("aut", "cre")),
     person("Fran", "Barton",, "[email protected]", role = "ctb"))
@@ -28,7 +28,7 @@ Imports:
     ggplot2,
     knitr,
     lubridate,
-    NHSRplotthedots (== 0.1.0),
+    NHSRplotthedots,
     purrr,
     readr,
     rlang,

NAMESPACE

@@ -5,6 +5,7 @@ export(spcr_make_report)
 importFrom(dplyr,across)
 importFrom(dplyr,if_any)
 importFrom(dplyr,pick)
+importFrom(glue,glue)
 importFrom(rlang,":=")
 importFrom(rlang,.data)
 importFrom(tidyselect,all_of)

NEWS.md

@@ -1,3 +1,16 @@
+# SPCreporter 0.1.6
+
+## Feature addition
+
+* There is a new argument "annotate_limits" available for `spcr_make_report()`. By default it is `TRUE`, and adds labels for the numeric values of the control limits and mean to the right of the plot.
+
+## Bugfix
+
+* Fixed a bug which caused status messages to be printed in the main report if report generation is done on a slow computer.
+* Fixed minor README argument name mistake, which would have thrown an error for new users.
+
+---
+
 # SPCreporter 0.1.5.6
 
 This version introduces a large number of changes to the package.
@@ -30,59 +43,71 @@ Some additional tests have been written, and existing tests amended to match the
 
 * Example data already supplied with the package (as xlsx files in the `inst` folder) is now also available as internal package data, which can be used as example data for demonstrating package functions and also for facilitating testing.
 
+---
 
 # SPCreporter 0.1.5
 
 ## Feature addition
 
-* Rebasing of SPC charts is now supported.  Pass in a date string in "YYYY-MM-DD" format, or multiple date strings.  `'"2020-01-01"'`, or `'"2020-01-01", "2021-05-01"'`
-* Stale data is now highlighted in the report.  By default data is highlighted as stale if the report cutoff is after the data update date (as defined by the `updated_to` argument for the data, and the `data_cutoff_dttm` for the report).  Optionally, a column called `allowable_days_lag` can be included in the measure_config.  This can be used to delay the flagging of stale data.  For example using a value of 31 in the `allowable_days_lag` column will enable a measure to be reported a month in arrears without being flagged as stale.  
+* Rebasing of SPC charts is now supported. Pass in a date string in "YYYY-MM-DD" format, or multiple date strings. `'"2020-01-01"'`, or `'"2020-01-01", "2021-05-01"'`
+
+* Stale data is now highlighted in the report. By default data is highlighted as stale if the report cutoff is after the data update date (as defined by the `updated_to` argument for the data, and the `data_cutoff_dttm` for the report). Optionally, a column called `allowable_days_lag` can be included in the measure_config. This can be used to delay the flagging of stale data. For example using a value of 31 in the `allowable_days_lag` column will enable a measure to be reported a month in arrears without being flagged as stale.
 
 ## Useability
 
-* Fixes an issue where if there are mismatches in measure_name across any of the 3 supplied dataframes (measure_data, report_config, measure_config) the error message throw reported missing data.  `Error: spcr_check_dataset_is_complete: Data is missing for 1 report items. The first is ref 1, M1, monthly.`  The correct and more helpful error in this case is to complain of the name mismatch: `Error: spcr_check_measure_names: There is a name mismatch for measure ref: 1. Check for typos or mismatching refs or data.`
+* Fixes an issue where if there are mismatches in measure_name across any of the 3 supplied dataframes (measure_data, report_config, measure_config) the error message throw reported missing data. `Error: spcr_check_dataset_is_complete: Data is missing for 1 report items. The first is ref 1, M1, monthly.` The correct and more helpful error in this case is to complain of the name mismatch: `Error: spcr_check_measure_names: There is a name mismatch for measure ref: 1. Check for typos or mismatching refs or data.`
 * Improved progress messages during `spcr_make_data_bundle()` to support debugging of incoming data.
 
 ## Bugfix
 
-* Fix a bug relating to NAs in the dataset which was causing printed warnings in the final report, as well as blank space in the charts.  The new behaviour strips NAs from all data, meaning that the chart axis starts at the first data point, and ends at the last.  
+* Fix a bug relating to NAs in the dataset which was causing printed warnings in the final report, as well as blank space in the charts. The new behaviour strips NAs from all data, meaning that the chart axis starts at the first data point, and ends at the last.
+
+---
 
 # SPCreporter 0.1.4
 
 ## Feature addition
 
-* Add two new optional columns to the measure_config: "Reviewed At", and "Escalated To".  If present the text in these fields is rendered into the final report below each chart.  
+* Add two new optional columns to the measure_config: "Reviewed At", and "Escalated To". If present the text in these fields is rendered into the final report below each chart.
 
 ## Bugfix
 
-* Fixed an error caused when measure_data contained NAs.  The package will now tolerate NAs in the data.  
+* Fixed an error caused when measure_data contained NAs. The package will now tolerate NAs in the data.
+
+---
 
 # SPCreporter 0.1.3
 
 ## Useability improvements
 
-* Significant improvements to error messages relating to measure_data, report_config, and measure_config.  Error messages now explicitly name any required columns which the user has not supplied.  This is intended to make troubleshooting simpler to do.  
-* The data source for metrics is now named in charts as a caption.  
-* Other minor useability improvements intended to make working with real-world config documents easier to do.  
+* Significant improvements to error messages relating to measure_data, report_config, and measure_config. Error messages now explicitly name any required columns which the user has not supplied. This is intended to make troubleshooting simpler to do.
+* The data source for metrics is now named in charts as a caption.
+* Other minor useability improvements intended to make working with real-world config documents easier to do.
+
+---
 
 # SPCreporter 0.1.2
 
 ## Useability improvements
 
-* measure_data requires data for only one (or more) of "week" or "month".
-* measure_data tolerates capitalised list (worksheet) names.
+* `measure_data` requires data for only one (or more) of "week" or "month".
+* `measure_data` tolerates capitalised list (worksheet) names.
 * Use the base pipe |> in place of %>%.
 * Throw a helpful error if insufficient data items have been provided for a given report.
 
+---
+
 # SPCreporter 0.1.1
 
 ## Bugfix
 
 * Fixes an error occurring when targets are not set for any of the reported measures
 
+---
 
 # SPCreporter 0.1.0
+
 ## Initial Release
 
-* spcr_make_data_bundle()
-* spcr_make_report()
+* `spcr_make_data_bundle()`
+* `spcr_make_report()`

R/spcr_make_report.R

@@ -18,7 +18,8 @@
 #' @param fresh_colour string. Customise the date lozenge to indicate that data is up to date, using a hex code, or CSS colour name
 #' @param output_directory string. The name of the directory in which to save the resulting report
 #' @param include_dq_icon logical. Whether to include the data quality icon on the final report
-#' @param export_csv logical. Whether to export a CSV file of the source data as well as the HTML report. Default TRUE.
+#' @param annotate_limits logical. Whether to add annotations to a secondary y axis for process limits and mean
+#' @param export_csv logical. Whether to export a CSV file of the source data as well as the HTML report. Default TRUE
 #'
 #' @export
 spcr_make_report <- function(
@@ -40,6 +41,7 @@ spcr_make_report <- function(
     fresh_colour = "white",
     output_directory = ".",
     include_dq_icon = TRUE,
+    annotate_limits = TRUE,
     export_csv = TRUE) {
   start_time <- Sys.time()
 
@@ -63,6 +65,7 @@ spcr_make_report <- function(
       "aggregation"
     ))) |>
     dplyr::mutate(spc_data = spc_data) |>
+    dplyr::mutate(label_limits = annotate_limits) |>
     purrr::pmap(make_spc_chart, .progress = "SPC charts")
 
 
@@ -71,9 +74,8 @@ spcr_make_report <- function(
     purrr::pmap_chr(\(x, y) paste0("tmp_", x, "_", y, "_")) |>
     tempfile(fileext = ".png")
 
-
   tmp_files |>
-    purrr::walk2(spc_charts, ggplot2::ggsave, width = 1800, height = 900, units = "px", dpi = 144)
+    purrr::walk2(spc_charts, write_chart_to_img)
 
   spc_chart_uris <- tmp_files |>
     purrr::map_chr(knitr::image_uri)
@@ -134,6 +136,7 @@ spcr_make_report <- function(
       toc = FALSE,
       self_contained = TRUE,
       fig_caption = FALSE,
+      highlight = NULL,
       mathjax = NULL
     ),
     output_dir = file.path(getwd(), output_directory),
@@ -147,19 +150,34 @@ spcr_make_report <- function(
   path <- file.path("file://", wd, output_directory, output_file_name)
   usethis::ui_info(paste0("Full path: ", path))
 
+  # open the result in the browser
+  utils::browseURL(path)
+  beepr::beep()
+
   process_duration <- lubridate::as.period(Sys.time() - start_time) |>
     round() |>
     tolower()
 
-  usethis::ui_done("Process completed in {process_duration}.")
-  beepr::beep()
+  usethis::ui_done("Report generated in {process_duration}.")
 
   invisible(TRUE)
 }
 
 
 
-
+#' Write a ggplot2 chart to a temporary png file (wrapper round `ggsave()`)
+#' @noRd
+write_chart_to_img <- function(img_file, chart) {
+  ggplot2::ggsave(
+    filename = img_file,
+    plot = chart,
+    device = ragg::agg_png,
+    width = 1500,
+    height = 750,
+    units = "px",
+    dpi = 125
+    )
+}
 
 
 #' Create a 'plot the dots' SPC data parcel from data bundle columns
@@ -186,7 +204,8 @@ make_spc_chart <- function(
     data_source,
     unit,
     aggregation,
-    spc_data) {
+    spc_data,
+    label_limits = TRUE) {
   spc_data |>
     NHSRplotthedots::ptd_create_ggplot(
       point_size = 4, # default is 2.5, orig in this package was 5
@@ -195,6 +214,7 @@ make_spc_chart <- function(
       x_axis_label = NULL,
       y_axis_label = NULL,
       x_axis_date_format = dplyr::if_else(aggregation == "week", "%d-%b-%Y", "%b '%y"),
+      label_limits = label_limits,
       icons_position = "none",
       break_lines = "limits"
     ) +

README.Rmd

@@ -109,7 +109,7 @@ data_bundle <- spcr_make_data_bundle(
 # make the report, including information for the six mandatory arguments.
 spcr_make_report(
   data_bundle = data_bundle,
-  title = "My Example Report",
+  report_title = "My Example Report",
   report_ref = "EG.001",
   data_cutoff_dttm = as.POSIXct("2022-09-30 23:59:59"),
   author_name = "Anne Author",
@@ -128,7 +128,7 @@ spcr_make_report(
 # example where we map over several reports, creating them in one go
 
 all_my_reports <- tibble::tibble(
-  title = c("Report 1", "Report 2", "Report 3"),
+  report_title = c("Report 1", "Report 2", "Report 3"),
   report_ref = c("ID.1", "ID.2", "ID.3"),
   author_name = "Anne Author",
   author_email = "[email protected]",
@@ -142,7 +142,6 @@ all_my_reports <- tibble::tibble(
 purrr::pwalk(all_my_reports, spcr_make_report, data_bundle = data_bundle)
 
 # ... but you may want to pass different data to each:
-
 all_my_reports |>
   dplyr::mutate(data_bundle = list(data_bundle1, data_bundle2, data_bundle3)) |>
   purrr::pwalk(spcr_make_report)

README.md

@@ -100,7 +100,7 @@ data_bundle <- spcr_make_data_bundle(
 # make the report, including information for the six mandatory arguments.
 spcr_make_report(
   data_bundle = data_bundle,
-  title = "My Example Report",
+  report_title = "My Example Report",
   report_ref = "EG.001",
   data_cutoff_dttm = as.POSIXct("2022-09-30 23:59:59"),
   author_name = "Anne Author",
@@ -116,7 +116,7 @@ spcr_make_report(
 # example where we map over several reports, creating them in one go
 
 all_my_reports <- tibble::tibble(
-  title = c("Report 1", "Report 2", "Report 3"),
+  report_title = c("Report 1", "Report 2", "Report 3"),
   report_ref = c("ID.1", "ID.2", "ID.3"),
   author_name = "Anne Author",
   author_email = "[email protected]",
@@ -130,7 +130,6 @@ all_my_reports <- tibble::tibble(
 purrr::pwalk(all_my_reports, spcr_make_report, data_bundle = data_bundle)
 
 # ... but you may want to pass different data to each:
-
 all_my_reports |>
   dplyr::mutate(data_bundle = list(data_bundle1, data_bundle2, data_bundle3)) |>
   purrr::pwalk(spcr_make_report)