tar_quarto_raw {tarchetypes} | R Documentation |
Target with a Quarto project (raw version).
Description
Shorthand to include a Quarto project or standalone
Quarto source document in a targets
pipeline.
Usage
tar_quarto_raw(
name,
path = ".",
working_directory = NULL,
extra_files = character(0),
execute = TRUE,
execute_params = NULL,
cache = NULL,
cache_refresh = FALSE,
debug = FALSE,
quiet = TRUE,
quarto_args = NULL,
pandoc_args = NULL,
profile = NULL,
packages = NULL,
library = NULL,
error = targets::tar_option_get("error"),
memory = targets::tar_option_get("memory"),
garbage_collection = targets::tar_option_get("garbage_collection"),
deployment = "main",
priority = targets::tar_option_get("priority"),
resources = targets::tar_option_get("resources"),
retrieval = targets::tar_option_get("retrieval"),
cue = targets::tar_option_get("cue"),
description = targets::tar_option_get("description")
)
Arguments
name |
Character of length 1, name of the target. A target
name must be a valid name for a symbol in R, and it
must not start with a dot. Subsequent targets
can refer to this name symbolically to induce a dependency relationship:
e.g. |
path |
Character of length 1,
either the single |
working_directory |
Optional character string,
path to the working directory
to temporarily set when running the report.
The default is |
extra_files |
Character vector of extra files and
directories to track for changes. The target will be invalidated
(rerun on the next |
execute |
Whether to execute embedded code chunks. |
execute_params |
A non-expression language object
(use |
cache |
Cache execution output (uses knitr cache and jupyter-cache respectively for Rmd and Jupyter input files). |
cache_refresh |
Force refresh of execution cache. |
debug |
Leave intermediate files in place after render. |
quiet |
Suppress warning and other messages. |
quarto_args |
Character vector of other |
pandoc_args |
Additional command line options to pass to pandoc. |
profile |
Character of length 1, Quarto profile. If |
packages |
Deprecated on 2023-09-05 (version 0.7.8.9000). Please load R packages inside the Quarto report itself. |
library |
Deprecated on 2023-09-05 (version 0.7.8.9000). Please load R packages inside the Quarto report itself. |
error |
Character of length 1, what to do if the target stops and throws an error. Options:
|
memory |
Character of length 1, memory strategy.
If |
garbage_collection |
Logical, whether to run |
deployment |
Character of length 1. If |
priority |
Numeric of length 1 between 0 and 1. Controls which
targets get deployed first when multiple competing targets are ready
simultaneously. Targets with priorities closer to 1 get dispatched earlier
(and polled earlier in |
resources |
Object returned by |
retrieval |
Character of length 1, only relevant to
|
cue |
An optional object from |
description |
Character of length 1, a custom free-form human-readable
text description of the target. Descriptions appear as target labels
in functions like |
Details
tar_quarto_raw()
is just like tar_quarto()
except that it uses standard evaluation for the
name
and execute_params
arguments (instead of quoting them).
Value
A target object with format = "file"
.
When this target runs, it returns a sorted character vector
of all the important file paths: the rendered documents,
the Quarto source files, and other input and output files.
The output files are determined by the YAML front-matter of
standalone Quarto documents and _quarto.yml
in Quarto projects,
and you can see these files with tar_quarto_files()
(powered by quarto::quarto_inspect()
).
All returned paths are relative paths to ensure portability
(so that the project can be moved from one file system to another
without invalidating the target).
See the "Target objects" section for background.
Target objects
Most tarchetypes
functions are target factories,
which means they return target objects
or lists of target objects.
Target objects represent skippable steps of the analysis pipeline
as described at https://books.ropensci.org/targets/.
Please read the walkthrough at
https://books.ropensci.org/targets/walkthrough.html
to understand the role of target objects in analysis pipelines.
For developers, https://wlandau.github.io/targetopia/contributing.html#target-factories explains target factories (functions like this one which generate targets) and the design specification at https://books.ropensci.org/targets-design/ details the structure and composition of target objects.
Literate programming limitations
Literate programming files are messy and variable,
so functions like tar_render()
have limitations:
* Child documents are not tracked for changes.
* Upstream target dependencies are not detected if tar_read()
and/or tar_load()
are called from a user-defined function.
In addition, single target names must be mentioned and they must
be symbols. tar_load("x")
and tar_load(contains("x"))
may not
detect target x
.
* Special/optional input/output files may not be detected in all cases.
* tar_render()
and friends are for local files only. They do not
integrate with the cloud storage capabilities of targets
.
Quarto troubleshooting
If you encounter difficult errors, please read
https://github.com/quarto-dev/quarto-r/issues/16.
In addition, please try to reproduce the error using
quarto::quarto_render("your_report.qmd", execute_dir = getwd())
without using targets
at all. Isolating errors this way
makes them much easier to solve.
See Also
Other Literate programming targets:
tar_knit()
,
tar_knit_raw()
,
tar_quarto()
,
tar_quarto_rep()
,
tar_quarto_rep_raw()
,
tar_render()
,
tar_render_raw()
,
tar_render_rep()
,
tar_render_rep_raw()
Examples
if (identical(Sys.getenv("TAR_LONG_EXAMPLES"), "true")) {
targets::tar_dir({ # tar_dir() runs code from a temporary directory.
# Unparameterized Quarto document:
lines <- c(
"---",
"title: report.qmd source file",
"output_format: html",
"---",
"Assume these lines are in report.qmd.",
"```{r}",
"targets::tar_read(data)",
"```"
)
# In tar_dir(), not part of the user's file space:
writeLines(lines, "report.qmd")
# Include the report in a pipeline as follows.
targets::tar_script({
library(tarchetypes)
list(
tar_target(data, data.frame(x = seq_len(26), y = letters)),
tar_quarto_raw("report", path = "report.qmd")
)
}, ask = FALSE)
# Then, run the pipeline as usual.
# Parameterized Quarto:
lines <- c(
"---",
"title: 'report.qmd source file with parameters'",
"output_format: html_document",
"params:",
" your_param: \"default value\"",
"---",
"Assume these lines are in report.qmd.",
"```{r}",
"print(params$your_param)",
"```"
)
# In tar_dir(), not part of the user's file space:
writeLines(lines, "report.qmd")
# Include the report in the pipeline as follows.
targets::tar_script({
library(tarchetypes)
list(
tar_target(data, data.frame(x = seq_len(26), y = letters)),
tar_quarto_raw(
"report",
path = "report.qmd",
execute_params = quote(list(your_param = data))
)
)
}, ask = FALSE)
# Then, run the pipeline as usual.
})
}