diff --git a/DESCRIPTION b/DESCRIPTION index 2e62e761..1f5bc70c 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -6,6 +6,7 @@ Authors@R: c( comment = c(ORCID = "0000-0002-4094-1476")), person("Thibaut", "Jombart", role = "aut"), person("Carmen", "Tamayo", role = "aut", comment = c(ORCID = "0000-0003-4184-2864")), + person("Karim", "Mané", role = "aut", comment = c(ORCID = "0000-0002-9892-2999")), person("data.org", role = "fnd") ) Description: A store of outbreak analytics pipelines using different @@ -16,7 +17,9 @@ URL: https://epiverse-trace.github.io/episoap, BugReports: https://github.com/epiverse-trace/episoap/issues Imports: renv (>= 0.13.0), - rmarkdown + rmarkdown, + withr, + xfun Suggests: knitr, spelling, diff --git a/NAMESPACE b/NAMESPACE index a0a451c3..81f73abe 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -1,3 +1,4 @@ # Generated by roxygen2: do not edit by hand export(list_templates) +export(run_pipeline) diff --git a/R/run_pipeline.R b/R/run_pipeline.R new file mode 100644 index 00000000..1f15c39d --- /dev/null +++ b/R/run_pipeline.R @@ -0,0 +1,65 @@ +#' Create report from template +#' +#' @param report A character vector of report template(s) to render (default to all +#' templates) +#' @param out_dir A character vector with the output directory (default to an +#' `episoap_report` in the current directory +#' @param preview A logical (default `TRUE`) indicating whether the rendered +#' report should be opened in the default browser +#' @param ... Arguments passed as parameters to the report template(s) +#' +#' @returns (invisibly) a character vector of paths to the rendered reports +#' +#' @export +#' +#' @examples +#' # Download data we need for this example +#' wd <- file.path(tempdir(), "episoap_report") +#' dir.create(wd) +#' download.file( +#' "https://github.com/epiverse-trace/episoap/blob/main/inst/rmarkdown/templates/transmissibility/skeleton/data/covid_linelist_england.rds?raw=true", +#' file.path(wd, "covid_linelist_england.rds") +#' ) +#' # Running the pipeline with custom data saved on your computer +#' run_pipeline( +#' report = "transmissibility", +#' out_dir = wd, +#' # this is passed as a rmarkdown parameter to the report +#' data_file = "covid_linelist_england.rds" +#' ) +run_pipeline <- function( + report = list_templates(), + out_dir = "episoap_report", + preview = TRUE, + ... +) { + + if (!dir.exists(out_dir)) { + dir.create(out_dir, recursive = TRUE) + } + + withr::local_dir(out_dir) + + report <- match.arg(report, several.ok = TRUE) + + rendered <- vapply(report, function(r) { + rmarkdown::draft( + file = paste0(r, ".Rmd"), + template = r, + create_dir = FALSE, + package = "episoap", + edit = FALSE + ) + # We run in a new session the prevent renv to leak in the user's environment + xfun::Rscript_call( + rmarkdown::render, + list(input = paste0(r, ".Rmd"), params = list(...)) + ) + }, character(1)) + + if (preview) { + utils::browseURL(rendered[[1]]) + } + + return(invisible(rendered)) +} diff --git a/man/run_pipeline.Rd b/man/run_pipeline.Rd new file mode 100644 index 00000000..8310378f --- /dev/null +++ b/man/run_pipeline.Rd @@ -0,0 +1,47 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/run_pipeline.R +\name{run_pipeline} +\alias{run_pipeline} +\title{Create report from template} +\usage{ +run_pipeline( + report = list_templates(), + out_dir = "episoap_report", + preview = TRUE, + ... +) +} +\arguments{ +\item{report}{A character vector of report template(s) to render (default to all +templates)} + +\item{out_dir}{A character vector with the output directory (default to an +\code{episoap_report} in the current directory} + +\item{preview}{A logical (default \code{TRUE}) indicating whether the rendered +report should be opened in the default browser} + +\item{...}{Arguments passed as parameters to the report template(s)} +} +\value{ +(invisibly) a character vector of paths to the rendered reports +} +\description{ +Create report from template +} +\examples{ +# Download data we need for this example +wd <- file.path(tempdir(), "episoap_report") +dir.create(wd) +download.file( + "https://github.com/epiverse-trace/episoap/blob/main/inst/rmarkdown/templates/transmissibility/skeleton/data/covid_linelist_england.rds?raw=true", + file.path(wd, "covid_linelist_england.rds") +) +# Running the pipeline with custom data saved on your computer +run_pipeline( + report = "transmissibility", + out_dir = wd, + # this is passed as a rmarkdown parameter to the report + data_file = "covid_linelist_england.rds" +) +} diff --git a/vignettes/design.Rmd b/vignettes/design.Rmd index cc33dcb6..34d4f70a 100644 --- a/vignettes/design.Rmd +++ b/vignettes/design.Rmd @@ -16,6 +16,15 @@ knitr::opts_chunk$set( As always during software development, we were faced with tough design choices while developing this package. We want to clearly document which choices were made, and what are the reasons behind them. +## Report parameters + +### Names + +As much as possible, parameter names should be re-used across reports. This allows us to: + +- provide a consistent user experience +- pass a common set of arguments in a potential wrapper function that would render multiple reports at once + ## Package and version management Breaking changes during R package updates in one of the major sources of non-[reproducibility](https://cran.r-project.org/web/views/ReproducibleResearch.html) and of headaches for R users of all levels. To guard users against this, but also to ensure that the provided templates work out of the box, throughout the time a given `{episoap}` version is on CRAN, we [pin specific versions for our dependencies](https://cloud.google.com/blog/topics/developers-practitioners/best-practices-dependency-management), via `{renv}`.