The draft_report()
function takes a raw dataset (data
-argument) and the
output from the refine_chapter_overview()
-function as the
chapter_structure
-argument and outputs a set of pre-populated qmd-files in the
specified path
-folder. You can edit, render, and
ultimately publish these as usual with Quarto features in RStudio. See also
{saros.post}
-package for post-processing tools.
Usage
draft_report(
data,
chapter_structure,
...,
path = tempdir(),
title = "Report",
authors = NULL,
authors_col = "author",
chapter_yaml_file = NULL,
chapter_qmd_start_section_filepath = NULL,
chapter_qmd_end_section_filepath = NULL,
index_filename = "index",
index_yaml_file = NULL,
index_qmd_start_section_filepath = NULL,
index_qmd_end_section_filepath = NULL,
report_filename = "report",
report_yaml_file = NULL,
report_qmd_start_section_filepath = NULL,
report_qmd_end_section_filepath = NULL,
ignore_heading_for_group = c(".template_name", ".variable_type_dep",
".variable_type_indep", ".variable_group_dep", "chapter"),
replace_heading_for_group = c(.variable_label_suffix_dep = ".variable_name_dep",
.variable_label_suffix_indep = ".variable_name_indep"),
prefix_heading_for_group = NULL,
suffix_heading_for_group = NULL,
require_common_categories = TRUE,
combined_report = TRUE,
attach_chapter_dataset = TRUE,
auxiliary_variables = NULL,
serialized_format = c("rds", "qs"),
max_path_warning_threshold = 260,
log_file = NULL
)
Arguments
- data
Survey data
obj:<data.frame>|obj:<tbl_df>|obj:<srvyr>
// RequiredA data frame (or a srvyr-object) with the columns specified in the chapter_structure 'dep', etc columns.
- chapter_structure
What goes into each chapter and sub-chapter
obj:<data.frame>|obj:<tbl_df>
// RequiredData frame (or tibble, possibly grouped). One row per chapter. Should contain the columns 'chapter' and 'dep', Optionally 'indep' (independent variables) and other informative columns as needed.
- ...
Dynamic dots
Arguments forwarded to the corresponding functions that create the elements.
- path
Output path
scalar<character>
// default:tempdir()
(optional
)Path to save all output. Defaults to a temporary directory.
- title
Title of report
scalar<character>
// default:NULL
(optional
)Added automatically to YAML-header of index.qmd and report.qmd-files.
Authors of entire report
vector<character>
// default:NULL
(optional
)If NULL, infers from
chapter_structure[[authors_col]]
, and collates for entire report. If multiple authors per chapter, separate with semicolon. Ensure consistency.Column name for author
scalar<character>
// default:"author"
(optional
)Only used if it exists. Multiple authors are separated by semicolon (and optionally with a subsequent space).
- chapter_yaml_file
Path to YAML-file to insert into each chapter qmd-file
scalar<character>
// default:NULL
(optional
)Path to file used to insert header YAML, in each chapter.
- chapter_qmd_start_section_filepath, chapter_qmd_end_section_filepath, index_qmd_start_section_filepath, index_qmd_end_section_filepath, report_qmd_start_section_filepath, report_qmd_end_section_filepath,
Path to qmd-bit for start/end of each qmd
scalar<character>
// default:NULL
(optional
)Path to qmd-snippet placed before/after body of all chapter/index/report qmd-files.
- index_filename
Index filename
scalar<character>
// default:"index.qmd"
(optional
)The name of the main index Quarto file used as landing page for each report. Will link to a PDF (report.qmd) which collects all chapters.
- index_yaml_file, report_yaml_file
Path to YAML-file to insert into index.qmd and report.qmd respectively
scalar<character>
// default:NULL
(optional
)Path to file used to insert header YAML, in index and report files.
- report_filename
Report filename
scalar<character>
// default:"report.qmd"
(optional
)The name of the main report QMD-file used when compiling a complete report collecting all chapters in its folder (except itself). If provided, will be linked to in the index. If NULL, will generate a filename based on the report title, prefixed with "0_". To turn off, set
pdf=FALSE
.- ignore_heading_for_group
Ignore heading for group
vector<character>
// default:NULL
(optional
)Type of refined chapter_structure data for which to suppress the heading in the report output. Typically variable_name_dep, variable_name_indep, etc.
- replace_heading_for_group
Replacing heading for group
named vector<character>
// default:c(".variable_label_suffix_dep" = ".variable_name_dep")
Occasionally, one needs to replace the heading with another piece of information in the refined chapter_structure. For instance, one may want to organize output by variable_name_indep, but to display the variable_label_indep instead. Use the name for the replacement and the value for the original.
- prefix_heading_for_group, suffix_heading_for_group
Prefix and suffix headings
vector<named character>
// default:NULL
(optional
)Names are heading_groups, values are the prefixes and suffixes. Note that prefixes should end with a
\n
as headings must begin on a new line.- require_common_categories
Check common categories
scalar<logical>
// default:NULL
(optional
)Whether to check if all items share common categories.
- combined_report
Create a combined report?
scalar<logical>
// default:FALSE
(optional
)Whether to create a qmd file that merges all chapters into a combined report.
- attach_chapter_dataset
Toggle inclusion of chapter-specific datasets in qmd-files
scalar<logical>
// default:FALSE
Whether to save in each chapter folder an 'Rds'-file with the chapter-specific dataset, and load it at the top of each QMD-file.
- auxiliary_variables
Auxiliary variables to be included in datasets
vector<character>
// default:NULL
(optional
)Column names in
data
that should always be included in datasets for chapter qmd-files, ifattach_chapter_dataset=TRUE
. Not publicly available.- serialized_format
Serialized format
scalar<string>
// default:"rds"
Format for serialized data when storing chapter dataset. One of
"rds"
(default),"qs"
or"fst"
. The latter two requires the respective packages to be installed."qs"
is usually the fastest and most space efficient, but sets package dependencies on the report project.- max_path_warning_threshold
Maximum number of characters in paths warning
scalar<integer>
// default:260
(optional
)Microsoft has set an absolute limit of 260 characters for its Sharepoint/OneDrive file paths. This will mean that files with cache (hash suffixes are added) will quickly breach this limit. When set, a warning will be returned if files are found to be longer than this threshold. Also note that spaces count as three characters due to its URL-conversion: %20. To avoid test, set to Inf
- log_file
Path to log file
scalar<string>
// default:"_log.txt"
(optional
)Path to log file. Set to NULL to disable logging.
Details
Note that saros treats data as they are stored: numeric, integer, factor, ordinal, character, and datetime. Currently, only factor/ordinal and character are implemented.
Examples
# \donttest{
ex_survey_ch_structure <-
refine_chapter_overview(
chapter_overview = ex_survey_ch_overview,
data = ex_survey
)
#> `chunk_templates` is NULL. Using global defaults.
#> Refining chapter_overview into a chapter_structure ...
#> Not using the following variables in `data`: `x2_human, a_7, a_8, c_1, c_2,
#> f_uni, and resp_status`.
index_filepath <-
draft_report(
chapter_structure = ex_survey_ch_structure,
data = ex_survey,
path = tempdir()
)
# }