| Title: | Core Utilities for Automatically Generated Reports |
|---|---|
| Description: | Provides utility functions for automatic generation of reports in the augere framework. This mostly involves parsing and dynamically editing Rmarkdown files, controlling inputs into the augere pipelines. Each pipeline generates and executes a self-contained Rmarkdown file for a common bioinformatics analysis; see downstream packages like augere.de and augere.screen for examples of some analysis pipelines. |
| Authors: | Aaron Lun [cre, aut] (ORCID: <https://orcid.org/0000-0002-3564-4813>) |
| Maintainer: | Aaron Lun <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 0.99.3 |
| Built: | 2026-05-15 06:34:21 UTC |
| Source: | https://github.com/bioc/augere.core |
Provides utility functions for automatic generation of reports in the augere framework. This mostly involves parsing and dynamically editing Rmarkdown files, controlling inputs into the augere pipelines. Each pipeline generates and executes a self-contained Rmarkdown file for a common bioinformatics analysis; see downstream packages like augere.de and augere.screen for examples of some analysis pipelines.
Maintainer: Aaron Lun [email protected] (ORCID)
Useful links:
Report bugs at https://github.com/augere-bioinfo/augere.core/issues
Compile a Rmarkdown report, typically generated from a template in a pipeline function.
compileReport( file, env, skip.chunks = NULL, contents = NULL, suppress.plots = FALSE )compileReport( file, env, skip.chunks = NULL, contents = NULL, suppress.plots = FALSE )
file |
String containing a path to an Rmarkdown file. |
env |
Environment in which the R code is to be evaluated. |
skip.chunks |
Character vector of the names of Rmarkdown chunks to skip. |
contents |
List or character vector containing the contents of |
suppress.plots |
Boolean indicating whether to suppress the generation of plots.
If |
This function leverages the input cache populated by processInputCommands.
If a chunk contains code generated by processInputCommands,
compileReport will attempt to load the corresponding object from cache instead of re-running the associated code.
This avoids using more time/memory to create an object that is already available in the R session.
compileReport automatically changes the working directory to that of file.
This is consistent with the behavior of knitr and ensures that any relative paths in file are respected.
If contents is supplied, the actual file need not exist but its directory should be accessible.
Code chunks from file are compiled, typically populating env with new variables.
NULL is invisibly returned.
Aaron Lun
processInputCommands, to define the input objects in the Rmarkdown file.
extractChunks and evaluateChunks, to extract the R code chunks and evaluate them, respectively.
tmp <- tempfile() dir.create(tmp) path <- file.path(tmp, "test.Rmd") write("```{r} res <- data.frame(foo=1:5, bar=LETTERS[2:6]) write.csv(res, file='results.csv') ```", file=path) env <- new.env() compileReport(path, env) env$res list.files(dirname(path))tmp <- tempfile() dir.create(tmp) path <- file.path(tmp, "test.Rmd") write("```{r} res <- data.frame(foo=1:5, bar=LETTERS[2:6]) write.csv(res, file='results.csv') ```", file=path) env <- new.env() compileReport(path, env) env$res list.files(dirname(path))
Deparse an object to a single string by concatenation, possibly with indentation for multi-line output.
deparseToString(x, indent = NULL)deparseToString(x, indent = NULL)
x |
R object to be deparsed. |
indent |
Integer scalar specifying the indenting for multi-line deparsed output.
If |
This function is based on deparse but with special accommodations when the deparsed output spans multiple lines.
If indent=NULL, the multiple output lines are directly pasted together with no separator.
If indent is an integer, a newline is added between lines, indented by the specified number of spaces.
String containing the deparsed value of x.
Aaron Lun
x <- sample(100) deparse(x) deparseToString(x) deparseToString(x, indent=4)x <- sample(100) deparse(x) deparseToString(x) deparseToString(x, indent=4)
Evaluate R chunks, typically derived from an Rmarkdown report.
evaluateChunks(chunks, env)evaluateChunks(chunks, env)
chunks |
List of character vectors, typically from |
env |
Environment in which to evaluate |
Each character vector may have some knitr-inspired attributes:
eval is a string that, upon evaluation within env, specifies if the current chunk should be evaluated.
ref.label is a string that, upon evaluation within env, contains the name of another character vector in chunks.
The chunk in the named character vector will be evaluated instead of the current chunk.
error is a string that, upon evaluation within env, specifies if errors should be ignored for this chunk.
All chunks are evaluated within env.
Aaron Lun
chunks <- list("a <- 1", "a <- a + 2", "", "a <- NULL") names(chunks) <- c("", "foo1", "", "foo3") attr(chunks[[3]], "ref.label") <- "paste0('foo', 1)" attr(chunks[[4]], "eval") <- "a < 0" env <- new.env() evaluateChunks(chunks, env) env$achunks <- list("a <- 1", "a <- a + 2", "", "a <- NULL") names(chunks) <- c("", "foo1", "", "foo3") attr(chunks[[3]], "ref.label") <- "paste0('foo', 1)" attr(chunks[[4]], "eval") <- "a < 0" env <- new.env() evaluateChunks(chunks, env) env$a
Extract R chunks from an Rmarkdown document, along with their names and knitr properties.
extractChunks(contents)extractChunks(contents)
contents |
A character vector or list (of lists) of character vectors containing an Rmarkdown document,
typically obtained via |
List of character vectors, each of which contains the R code for a single chunk. Each vector is named according to the name of the chunk. knitr properties are stored in the attributes for each vector.
Aaron Lun
contents <- " ```{r alpha} alpha <- 1 bravo <- 2 ``` Some random text here ```{r, echo=FALSE, eval=FALSE} charlie <- 3 delta <- 4 ``` - point 1 with some `r inline <- TRUE`. - point 2. ```{r i-am-indented, error=TRUE} echo <- 5 foxtrot <- 6 ``` even more text here with `r 'some'` `r 'more'` `r 'inlining'`. " extractChunks(strsplit(contents, "\n"))contents <- " ```{r alpha} alpha <- 1 bravo <- 2 ``` Some random text here ```{r, echo=FALSE, eval=FALSE} charlie <- 3 delta <- 4 ``` - point 1 with some `r inline <- TRUE`. - point 2. ```{r i-am-indented, error=TRUE} echo <- 5 foxtrot <- 6 ``` even more text here with `r 'some'` `r 'more'` `r 'inlining'`. " extractChunks(strsplit(contents, "\n"))
Parse an Rmarkdown report template to extract blocks of text or code.
parseRmdTemplate(contents)parseRmdTemplate(contents)
contents |
String or character vector containing an Rmarkdown report template. |
An Rmarkdown report template may contain any number of paired :BEGIN and :END tags.
These tags enclose blocks of text that may be dynamically removed or duplicated by the pipeline functions.
Tag pairs should follow these rules:
Each tag should start on its own line.
The :BEGIN tag should be followed by a name, e.g., :BEGIN my-name-here.
The corresponding :END tag does not need to be followed by a name, but if it does, the name should be the same as that of the matching :BEGIN tag.
Tag pairs may be nested within another tag pair.
Names should be unique for any given level of nesting. For nested tag pairs, there should be no other tag pair with the same name within the parent tag pair. For unnested tag pairs, there should be no other unnested tag pair with the same name.
In the output of this function, each entry of the top-level list may be either:
A list, corresponding to a tag pair. This list contains all text in the Rmarkdown template enclosed by the tag pair, which may be character vectors or further lists corresponding to nested tag pairs. If the tag pair is named, the same name will be used for this list entry.
A character vector, to store newline-separated text within or between tag pairs.
Calling unlist on the output of this function will return a newline-separated version of contents without the tags.
List of character vectors or nested lists, see Details.
Aaron Lun
template <- " Ochite iku sunadokei bakari miteru yo Sakasama ni sureba hora mata hajimaru yo Kizanda dake susumu jikan ni Itsuka boku mo haireru kana ```{r} nagisa <- 'furukawa' ``` :BEGIN clannad Kimi dake ga sugisatta saka no tochuu wa Atataka na hidamari ga ikutsu mo dekiteta Boku hitori ga koko de yasashii Atatakasa wo omoikaeshiteru :BEGIN after-story ```{r} tomoya <- 'Okazaki' ``` :END Kimi dake wo kimi dake wo Suki de ita yo Kaze de me ga nijinde Tooku naru yo :BEGIN toki-wa-kizamu-uta Itsumademo oboeteru Kono machi ga kawatte mo Dore dake no kanashimi to deau koto ni natte mo Misete yaru hontou wa tsuyokatta doki no koto Saa iku yo arukidasu saka no michi wo ```{r} ushio <- TRUE ``` :END :END" parseRmdTemplate(template)template <- " Ochite iku sunadokei bakari miteru yo Sakasama ni sureba hora mata hajimaru yo Kizanda dake susumu jikan ni Itsuka boku mo haireru kana ```{r} nagisa <- 'furukawa' ``` :BEGIN clannad Kimi dake ga sugisatta saka no tochuu wa Atataka na hidamari ga ikutsu mo dekiteta Boku hitori ga koko de yasashii Atatakasa wo omoikaeshiteru :BEGIN after-story ```{r} tomoya <- 'Okazaki' ``` :END Kimi dake wo kimi dake wo Suki de ita yo Kaze de me ga nijinde Tooku naru yo :BEGIN toki-wa-kizamu-uta Itsumademo oboeteru Kono machi ga kawatte mo Dore dake no kanashimi to deau koto ni natte mo Misete yaru hontou wa tsuyokatta doki no koto Saa iku yo arukidasu saka no michi wo ```{r} ushio <- TRUE ``` :END :END" parseRmdTemplate(template)
Convert an input object into commands that can be stored in an Rmarkdown report for a reproducible analysis.
processInputCommands(x, name) resetInputCache() wrapInput(object, commands)processInputCommands(x, name) resetInputCache() wrapInput(object, commands)
x |
An arbitrary R object.
Alternatively, a list with the |
name |
String containing the name of the object in the Rmarkdown report. |
object |
An arbitrary R object.
Alternatively |
commands |
Character vector of R commands to be used to generate |
Pipeline developers should call processInputCommands to define the generation of input objects in the Rmarkdown report.
Each call to processInputCommands will store the input R object in an internal cache.
Upon compiling the report with compileReport, the cached object will be used instead of rerunning the code returned by processInputCommands.
This saves time and avoids errors for inputs that have no associated commands.
(The exception is if object=NULL, in which case the commands must be run to generate the object.)
At the start of a pipeline function, it is good practice to call resetInputCache.
This clears any existing cached inputs from calls to other pipeline functions,
e.g., in the pathological case where one pipeline function is called within another function.
The function returned by resetInputCache should then be called once the pipeline function completes, e.g., in an on.exit block.
processInputCommands will return a string containing R commands that can be inserted into an Rmarkdown code chunk.
If x is an augere.input with non-NULL commands, those commands will be used directly.
Otherwise, a stop command will be generated that instructs the user to manually insert commands to generate x.
wrapInput will return an augere.input list containing the object and commands fields.
resetInputCache will set the input cache to an empty list.
It returns a function that restores the input cache to the state prior to the function's invocation.
Aaron Lun
compileReport, which uses the input cache.
replacePlaceholders, to insert the input commands into the Rmarkdown template.
fun <- resetInputCache() df <- data.frame(foo=1:5, bar=LETTERS[2:6]) cat(processInputCommands(df, "my_df")) wrapped <- wrapInput(df, c("y <- data.frame(foo = 1:5)", "y$bar <- LETTERS[2:6]", "y")) cat(processInputCommands(wrapped, "my_df")) fun()fun <- resetInputCache() df <- data.frame(foo=1:5, bar=LETTERS[2:6]) cat(processInputCommands(df, "my_df")) wrapped <- wrapInput(df, c("y <- data.frame(foo = 1:5)", "y$bar <- LETTERS[2:6]", "y")) cat(processInputCommands(wrapped, "my_df")) fun()
Find all placeholders in an Rmarkdown template and replace them with actual text.
replacePlaceholders(contents, replacements, error = TRUE)replacePlaceholders(contents, replacements, error = TRUE)
contents |
String, character vector or list containing an Rmarkdown report template.
This is typically the output of |
replacements |
Named character vector of replacement text for placeholders. The name is the placeholder and the value is the replacement text. This may also be a named list of strings. |
error |
Boolean indicating whether to throw an error if a placeholder does not have a replacement in |
A placeholder takes the form <%= LABEL %>, where LABEL can be any name without % or newlines.
Pipeline functions are expected to replace these placeholders with actual text, usually based on user-supplied parameters.
An object of the same type as contents, but with all of the placeholders replaced.
Aaron Lun
replacePlaceholders( "Hi my name is <%= NAME %> and I enjoy <%= FOOD %>.", replacements=c(NAME="Aaron", FOOD="pork") )replacePlaceholders( "Hi my name is <%= NAME %> and I enjoy <%= FOOD %>.", replacements=c(NAME="Aaron", FOOD="pork") )
Save result objects to disk using the alabaster.base framework.
saveResult(x, path, metadata, meta.name = "_metadata.json", requires = NULL) readResult(path, meta.name = "_metadata.json")saveResult(x, path, metadata, meta.name = "_metadata.json", requires = NULL) readResult(path, meta.name = "_metadata.json")
x |
Result object to be saved. |
path |
String containing the path to the directory in which |
metadata |
Named list of metadata to save alongside |
meta.name |
String containing the name of the metadata file within |
requires |
String containing the name of the alabaster.* package containing the relevant methods to save |
For saveResult, x and metadata (if supplied) are saved to disk at path.
NULL is invisibly returned.
Aaron Lun
saveObject and readObject, for the underlying functionality.
df <- S4Vectors::DataFrame(A = 1:5, B=2:6) meta <- list( title = "This is a very important result", author = "Myself", date = "2022-02-22" ) tmp <- tempfile() saveResult(df, tmp, metadata = meta) list.files(tmp, recursive=TRUE) readResult(tmp)df <- S4Vectors::DataFrame(A = 1:5, B=2:6) meta <- list( title = "This is a very important result", author = "Myself", date = "2022-02-22" ) tmp <- tempfile() saveResult(df, tmp, metadata = meta) list.files(tmp, recursive=TRUE) readResult(tmp)
Write Rmarkdown-formatted strings to file.
writeRmd(contents, file, append = FALSE, clean.empty = TRUE)writeRmd(contents, file, append = FALSE, clean.empty = TRUE)
contents |
A character vector of a (nested) list of such vectors. |
file |
String containing a file path or a connection object to an opened file. |
append |
Logical scalar indicating whether to append |
clean.empty |
Logical scalar indicating whether extraneous empty lines should be removed. |
Each element of each character vector in contents is placed on a new line in the output.
Empty strings are respected and manifest as empty lines.
If clean.empty=TRUE, repeated empty lines are removed.
contents is written to file and NULL is invisibly returned.
Aaron Lun
contents <- list( c("# TITLE", ""), list( c("```{r}", "a <- 1", "```"), c("", "super foo bar") ), c("", "## section") ) tmp <- tempfile(fileext=".Rmd") writeRmd(contents, tmp) cat(readLines(tmp), sep="\n") # having a lookcontents <- list( c("# TITLE", ""), list( c("```{r}", "a <- 1", "```"), c("", "super foo bar") ), c("", "## section") ) tmp <- tempfile(fileext=".Rmd") writeRmd(contents, tmp) cat(readLines(tmp), sep="\n") # having a look