Title: | Avoid the Typical Working Directory Pain When Using 'knitr' |
---|---|
Description: | An extension of 'knitr' that adds flexibility in several ways. One common source of frustration with 'knitr' is that it assumes the directory where the source file lives should be the working directory, which is often not true. 'ezknitr' addresses this problem by giving you complete control over where all the inputs and outputs are, and adds several other convenient features to make rendering markdown/HTML documents easier. |
Authors: | Dean Attali [aut, cre] |
Maintainer: | Dean Attali <[email protected]> |
License: | MIT + file LICENSE |
Version: | 0.6.3 |
Built: | 2024-09-05 05:54:20 UTC |
Source: | https://github.com/ropensci/ezknitr |
ezknitr
is an extension of knitr
that adds flexibility in several
ways. One common source of frustration with knitr
is that it assumes
the directory where the source file lives should be the working directory,
which is often not true. ezknitr
addresses this problem by giving you
complete control over where all the inputs and outputs are, and adds several
other convenient features. The two main functions are ezknit
and
ezspin
, which are wrappers around knitr
's knit
and
spin
, used to make rendering markdown/HTML documents easier.
ezspin( file, wd, out_dir, fig_dir, out_suffix, params = list(), verbose = FALSE, chunk_opts = list(tidy = FALSE), keep_rmd = FALSE, keep_md = TRUE, keep_html = TRUE, move_intermediate_file = TRUE, ... ) ezknit( file, wd, out_dir, fig_dir, out_suffix, params = list(), verbose = FALSE, chunk_opts = list(tidy = FALSE), keep_md = TRUE, keep_html = TRUE )
ezspin( file, wd, out_dir, fig_dir, out_suffix, params = list(), verbose = FALSE, chunk_opts = list(tidy = FALSE), keep_rmd = FALSE, keep_md = TRUE, keep_html = TRUE, move_intermediate_file = TRUE, ... ) ezknit( file, wd, out_dir, fig_dir, out_suffix, params = list(), verbose = FALSE, chunk_opts = list(tidy = FALSE), keep_md = TRUE, keep_html = TRUE )
file |
The path to the input file (.Rmd file if using |
wd |
The working directory to be used in the Rmd/R script. Defaults to
the current working directory (note that this is not the same behaviour as
|
out_dir |
The output directory for the rendered markdown or HTML files
(if |
fig_dir |
The name (or path) of the directory where figures should be generated. See the 'Detailed Arguments' section for more details. |
out_suffix |
A suffix to add to the output files. Can be used to
differentiate outputs from runs with different parameters. The name of the
output files is the name of the input file appended by |
params |
A named list of parameters to be passed to use in the input
Rmd/R file. For example, if the script to execute assumes that there is a
variable named |
verbose |
If TRUE, then show the progress of knitting the document. |
chunk_opts |
List of knitr chunk options to use. See
|
keep_rmd , keep_md
|
Should intermediate |
keep_html |
Should the final |
move_intermediate_file |
Should the intermediate |
... |
Any extra parameters that should be passed to |
If you have a very simple project with a flat directory structure, then
knitr
works great. But even something as simple as trying to knit a
document that reads a file from a different directory or placing the output
rendered files in a different folder cannot be easily done with knitr
.
ezknitr
improves basic knitr
functionality in a few ways.
You get to decide:
What the working directory of the source file is
Where the output files will go
Where the figures used in the markdown will go
Any parameters to pass to the source file
The path to the output directory (invisibly).
All paths given in the arguments can be either absolute or relative.
The wd
argument is very important and is set to the current working
directory by default. The path of the input file and the path of the output
directory are both relative to wd
(unless they are absolute paths).
Moreover, any code in the R script that reads or writes files will use
wd
as the working directory.
The fig_dir
argument is relative to the output directory, since the
figures accompanying a markdown file should be placed in the same
directory. It is recommended to either leave fig_dir
as default or
set it to a different name but not to a different directory. Because of the
way knitr
works, there are a few known minor issues if fig_dir
is set to a different directory.
ezknit
is a wrapper around knitr::knit
while ezspin
is a wrapper around ezspin
. The two functions are very similar.
knit
is the more popular and well-known function. It is used
to render a markdown/HTML document from an Rmarkdown source.
spin
takes an R script as its input, produces an
Rmarkdown document from the R script, and then calls knit
on it.
open_output_dir
setup_ezknit_test
setup_ezspin_test
set_default_params
knit
spin
## Not run: tmp <- setup_ezknit_test() ezknit("R/ezknit_test.Rmd", wd = "ezknitr_test") ezknit("R/ezknit_test.Rmd", wd = "ezknitr_test", out_dir = "output", fig_dir = "coolplots", params = list(numPoints = 50)) open_output_dir() unlink(tmp, recursive = TRUE, force = TRUE) tmp <- setup_ezspin_test() ezspin("R/ezspin_test.R", wd = "ezknitr_test") ezspin("R/ezspin_test.R", wd = "ezknitr_test", out_dir = "output", fig_dir = "coolplots", params = list(numPoints = 50), keep_rmd = TRUE) open_output_dir() unlink(tmp, recursive = TRUE, force = TRUE) ## End(Not run)
## Not run: tmp <- setup_ezknit_test() ezknit("R/ezknit_test.Rmd", wd = "ezknitr_test") ezknit("R/ezknit_test.Rmd", wd = "ezknitr_test", out_dir = "output", fig_dir = "coolplots", params = list(numPoints = 50)) open_output_dir() unlink(tmp, recursive = TRUE, force = TRUE) tmp <- setup_ezspin_test() ezspin("R/ezspin_test.R", wd = "ezknitr_test") ezspin("R/ezspin_test.R", wd = "ezknitr_test", out_dir = "output", fig_dir = "coolplots", params = list(numPoints = 50), keep_rmd = TRUE) open_output_dir() unlink(tmp, recursive = TRUE, force = TRUE) ## End(Not run)
Call this function after running ezspin or ezknit to open the resulting output directory in your file browser. This is simply a convenience function so that if you want to see the results you don't need to navigate to the appropriate folder manually.
open_output_dir()
open_output_dir()
## Not run: library(ezknitr) setup_ezspin_test() ezspin("R/ezspin_test.R", wd = "ezknitr_test") open_output_dir() ## End(Not run)
## Not run: library(ezknitr) setup_ezspin_test() ezspin("R/ezspin_test.R", wd = "ezknitr_test") open_output_dir() ## End(Not run)
Create variables with the given values only if these variables do not currently exist.
set_default_params(params)
set_default_params(params)
params |
List of parameters. |
Sometimes it may be useful to define a variable only it hasn't been defined yet. One example where this can be useful is when you have an Rmd script that uses some variables and you want to be able to use custom values for these variables, but also give them a default value in the script in case they are not set beforehand.
exists("foo") exists("bar") foo <- 5 set_default_params(list(foo = 10, bar = 20)) print(foo) print(bar)
exists("foo") exists("bar") foo <- 5 set_default_params(list(foo = 10, bar = 20)) print(foo) print(bar)
ezspin
or ezknit
Create a few directories that try to mimic a real
data-analysis project structure, and add a data file and a simple R script
(for ezspin
) or Rmarkdown file (for ezknit
).
After setting up these files and directories, you can run ezknitr
commands and their equivalent knitr
commands to compare and see the
benefits of using ezknitr
.
More specific instructions on how to interact with this test directory will
be printed to the console.
setup_ezspin_test() setup_ezknit_test()
setup_ezspin_test() setup_ezknit_test()
The path to the test directory.
ezspin
spin
ezknit
knit
open_output_dir
## Not run: library(ezknitr) # setup the test directory structures and run naive spin setup_ezspin_test() knitr::spin("ezknitr_test/R/ezspin_test.R") file.remove(c("ezspin_test.md", "ezspin_test.html")) # setup the test directory structures and run simple ezspin setup_ezspin_test() ezspin("R/ezspin_test.R", wd = "ezknitr_test") # setup the test directory structures and run ezspin with more parameters tmp <- setup_ezspin_test() ezspin("R/ezspin_test.R", wd = "ezknitr_test", out_dir = "output", fig_dir = "coolplots") unlink(tmp, recursive = TRUE, force = TRUE) ## End(Not run)
## Not run: library(ezknitr) # setup the test directory structures and run naive spin setup_ezspin_test() knitr::spin("ezknitr_test/R/ezspin_test.R") file.remove(c("ezspin_test.md", "ezspin_test.html")) # setup the test directory structures and run simple ezspin setup_ezspin_test() ezspin("R/ezspin_test.R", wd = "ezknitr_test") # setup the test directory structures and run ezspin with more parameters tmp <- setup_ezspin_test() ezspin("R/ezspin_test.R", wd = "ezknitr_test", out_dir = "output", fig_dir = "coolplots") unlink(tmp, recursive = TRUE, force = TRUE) ## End(Not run)