diff --git a/NAMESPACE b/NAMESPACE index ce61de0..f1895be 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -2,4 +2,5 @@ export(execute_checks) export(load_checks) +export(render_rmarkdown) importFrom(rlang,.data) diff --git a/R/execute-checks.R b/R/execute-checks.R index c7417e9..e3f07d1 100644 --- a/R/execute-checks.R +++ b/R/execute-checks.R @@ -1,5 +1,4 @@ -#' @title Load and parse checks in a yaml file, and return a list -#' of useful objects. +#' @title Execute the checks against a dataset to return a nested list. #' @param ds The [data.frame] to be checked. Required. #' @param checks The [list] describing the check. Is the output of #' [trawler::load_checks()]. Required. diff --git a/R/render-rmarkdown.R b/R/render-rmarkdown.R new file mode 100644 index 0000000..5fec6e5 --- /dev/null +++ b/R/render-rmarkdown.R @@ -0,0 +1,55 @@ +#' @title Render (executed) checks to an html document with [R Markdown](https://rmarkdown.rstudio.com/) +#' @param path_checks The file path of the output of +#' [trawler::execute_checks()]. Required. +#' @param directory_output A writable directory to save the report outputs. +#' The html file is the primary output. The markdown file is sometimes +#' useful too. Required. +#' @param path_template The +#' [rmd file](https://rmarkdown.rstudio.com/articles_intro.html), +#' which serves as the report template. Defaults to the +#' [standard template](https://github.com/OuhscBbmc/trawler/tree/main/inst/report-templates/rmarkdown-1/report-1.Rmd) +#' built into the trawler package. +#' +#' @examples +#' # Step 0: define paths. +#' # So this package example executes on every machine, temp files are used. +#' +#' # Replace the two paths for your specific project +#' path_data <- system.file("datasets/pt-event-biochemical.rds", package = "trawler") +#' path_defs <- system.file("checks/checks-biochemical.yml", package = "trawler") +#' +#' # In your real code, this will probably in a static directory. +#' # If PHI or sensitive info is contained, use a secure location. +#' directory_output <- file.path(tempdir(check = TRUE), "trawler") +#' if (!dir.exists(directory_output)) dir.create(directory_output) +#' path_checks <- tempfile("trawler-checks-", fileext = ".rds", tmpdir = directory_output) +#' +#' # Step 1: load the check definitions and the dataset to test +#' ds_pt_event <- readr::read_rds(path_data) +#' checks <- load_checks(path_defs) +#' +#' # Step 2: execute the checks and save to an rds file +#' execute_checks(ds_pt_event, checks) |> +#' readr::write_rds(path_checks) +#' +#' # Step 3: render checks as an html report with R Markdown +#' render_rmarkdown(path_checks, directory_output) +#' +#' # For the sake of this example, clean up temp files. +#' # You probably do NOT want this line in your real code. +#' unlink(directory_output, recursive = TRUE) +#' +#' @export +render_rmarkdown <- function ( + path_checks, + directory_output, + path_template = system.file("report-templates/rmarkdown-1/report-1.Rmd", package = "trawler") +) { + checkmate::assert_file_exists(path_checks) + + rmarkdown::render( + input = path_template, + params = list(path_checks = path_checks), + output_dir = directory_output + ) +} diff --git a/man/execute_checks.Rd b/man/execute_checks.Rd index fc3e4d9..bca7b38 100644 --- a/man/execute_checks.Rd +++ b/man/execute_checks.Rd @@ -2,8 +2,7 @@ % Please edit documentation in R/execute-checks.R \name{execute_checks} \alias{execute_checks} -\title{Load and parse checks in a yaml file, and return a list -of useful objects.} +\title{Execute the checks against a dataset to return a nested list.} \usage{ execute_checks(ds, checks) } @@ -14,8 +13,7 @@ execute_checks(ds, checks) \code{\link[=load_checks]{load_checks()}}. Required.} } \description{ -Load and parse checks in a yaml file, and return a list -of useful objects. +Execute the checks against a dataset to return a nested list. } \examples{ # Replace the two paths for your specific project diff --git a/man/render_rmarkdown.Rd b/man/render_rmarkdown.Rd new file mode 100644 index 0000000..d1241a5 --- /dev/null +++ b/man/render_rmarkdown.Rd @@ -0,0 +1,60 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/render-rmarkdown.R +\name{render_rmarkdown} +\alias{render_rmarkdown} +\title{Render (executed) checks to an html document with \href{https://rmarkdown.rstudio.com/}{R Markdown}} +\usage{ +render_rmarkdown( + path_checks, + directory_output, + path_template = system.file("report-templates/rmarkdown-1/report-1.Rmd", package = + "trawler") +) +} +\arguments{ +\item{path_checks}{The file path of the output of +\code{\link[=execute_checks]{execute_checks()}}. Required.} + +\item{directory_output}{A writable directory to save the report outputs. +The html file is the primary output. The markdown file is sometimes +useful too. Required.} + +\item{path_template}{The +\href{https://rmarkdown.rstudio.com/articles_intro.html}{rmd file}, +which serves as the report template. Defaults to the +\href{https://github.com/OuhscBbmc/trawler/tree/main/inst/report-templates/rmarkdown-1/report-1.Rmd}{standard template} +built into the trawler package.} +} +\description{ +Render (executed) checks to an html document with \href{https://rmarkdown.rstudio.com/}{R Markdown} +} +\examples{ +# Step 0: define paths. +# So this package example executes on every machine, temp files are used. + +# Replace the two paths for your specific project +path_data <- system.file("datasets/pt-event-biochemical.rds", package = "trawler") +path_defs <- system.file("checks/checks-biochemical.yml", package = "trawler") + +# In your real code, this will probably in a static directory. +# If PHI or sensitive info is contained, use a secure location. +directory_output <- file.path(tempdir(check = TRUE), "trawler") +if (!dir.exists(directory_output)) dir.create(directory_output) +path_checks <- tempfile("trawler-checks-", fileext = ".rds", tmpdir = directory_output) + +# Step 1: load the check definitions and the dataset to test +ds_pt_event <- readr::read_rds(path_data) +checks <- load_checks(path_defs) + +# Step 2: execute the checks and save to an rds file +execute_checks(ds_pt_event, checks) |> + readr::write_rds(path_checks) + +# Step 3: render checks as an html report with R Markdown +render_rmarkdown(path_checks, directory_output) + +# For the sake of this example, clean up temp files. +# You probably do NOT want this line in your real code. +unlink(directory_output, recursive = TRUE) + +}