render_docs: Render an R Markdown file summarizing the results of an...

In Yu-Group/simChef: Intensive Computational Experiments Made Easy

Render an R Markdown file summarizing the results of an Experiment or set of Experiments.

Description

Knits and/or writes an R Markdown file summarizing the results of an Experiment or set of Experiments. This document may contain (1) the code corresponding to the DGPs, Methods, Evaluators, Visualizers, and vary_across parameters from the Experiment, (2) the results of the Evaluators (typically tables), and (3) the results of the Visualizers (typically figures). Note that render_docs() will process and include results from all Experiments found under the root directory. This root directory is determined via experiment$get_save_dir() if experiment is provided and save_dir otherwise.

Usage

render_docs(
  experiment,
  save_dir,
  write_rmd = FALSE,
  output_file = NULL,
  output_format = vthemes::vmodern(),
  title = NULL,
  author = "",
  show_code = TRUE,
  show_eval = TRUE,
  show_viz = TRUE,
  eval_order = NULL,
  viz_order = NULL,
  eval_cache = ".rds",
  viz_cache = ".rds",
  viz_interactive = FALSE,
  use_icons = TRUE,
  quiet = TRUE,
  verbose = 2,
  ...
)

Arguments

experiment	An Experiment object. If provided, documentation is created for all previously saved Experiments that are found in the directory given by experiment$get_save_dir(). If no Experiments have been previously saved under this directory, then the current experiment is saved to disk and used to create the documentation template.
save_dir	An optional directory in which to find previously saved Experiment objects. Documentation is created for these found Experiments. Not used if experiment is provided.
write_rmd	Logical indicating whether or not to write out the raw R Markdown file used to generate the results. If TRUE, both the raw R Markdown file and the rendered R Markdown output are saved to disk. If FALSE, only the rendered R Markdown output is saved. Default is FALSE.
output_file	The name of the output file. If using NULL, then the output filename will be based on the experiment's root results directory and the name of the experiment. Note that the filename may include the path to the output file.
output_format	The R Markdown output format to convert to. Must be an object of class rmarkdown_output_format (e.g., rmarkdown::html_document(), rmarkdown::pdf_document(), rmarkdown::md_document).
title	Character string. Title of the report. By default, this will be the name of the experiment if experiment is provided.
author	Character string of author names to display in knitted R Markdown document.
show_code	Logical indicating whether or not to show code portions in the output document.
show_eval	Logical indicating whether or not to show the results of the Evaluators in the output document.
show_viz	Logical indicating whether or not to show the results of the Visualizers in the output document.
eval_order	Vector of Evaluator names in their desired order for display. By default, the report will display the Evaluator results in the order that they were computed.
viz_order	Vector of Visualizer names in their desired order for display. By default, the report will display the Visualizer results in the order that they were computed.
eval_cache	File extension of the cached evaluator results to read in. Typically ".rds" or "none", but can be any file extension where evaluator results are stored as eval_results.ext and can be read in using data.table::fread(eval_results.ext). If "none", evaluator results are computed using the experiment via evaluate_experiment().
viz_cache	File extension of the cached visualizer results to read in. Typically ".rds" or "none", but can be any (image) file extension (e.g., "png", "jpg") where the visualizer results have been previously stored as separate ⁠{visualizer_name}.ext⁠ images (typically using export_visualizers()). If "none", visualizer results are computed using the experiment via visualize_experiment().
viz_interactive	Logical, indicating whether or not to display plot visualizers interactively in the R Markdown document using plotly::ggplotly(). Default is FALSE. Can also specify a character vector of Visualizer names to display interactively. Note that only the visualizers that can be coerced into an interactive plot using plotly::ggplotly() will be displayed interactively.
use_icons	Logical indicating whether or not to use fontawesome icons.
quiet	An option to suppress printing during rendering from knitr, pandoc command line and others. To only suppress printing of the last "Output created: " message, you can set rmarkdown.render.message to FALSE
verbose	Level of verboseness (0, 1, 2) when knitting R Markdown. Default is 2.
...	Additional arguments to pass to rmarkdown::render(). Useful for applying a custom R Markdown output theme.

Value

The original Experiment object if provided. Otherwise, returns NULL.

Examples

## Not run: 
# create basic Rmd from an experiment (of class `Experiment`)
render_docs(experiment)

# or alternatively, create basic Rmd from a specific directory
render_docs(save_dir = experiment$get_save_dir())
## End(Not run)

Yu-Group/simChef documentation built on Jan. 11, 2025, 1:25 a.m.