Skip to contents

Automatically Draft a Quarto Report

Source: R/draft_report.R
draft_report.Rd

The draft_report() function is the main function, and the only necessary user interface, to create semi-automated (draft) reports. It does not need to be the first step, however, as one might want to store and read in arguments for the function with the read_yaml_params()-function first. After the report files has been drafted with draft_report(), you can edit, render, and ultimately publish these as usual with Quarto features in RStudio. The index.qmd will be the main output file containing "includes" to other chapters.

Usage

draft_report(
  data,
  chapter_overview,
  ...,
  path = "testreport",
  title = "Report",
  authors = NULL,
  mesos_report = FALSE,
  mesos_var = NULL,
  label_separator = " - ",
  name_separator = NULL,
  report_yaml_file = NULL,
  chapter_yaml_file = NULL,
  qmd_start_section_filepath = NULL,
  qmd_end_section_filepath = NULL,
  index_filename = "index.qmd",
  groupby = c("chapter", ".variable_label_prefix", ".element_name"),
  element_names = c("uni_cat_text", "uni_cat_prop_plot", "uni_cat_freq_plot",
    "uni_cat_table", "uni_chr_table", "uni_sigtest", "hline", "bi_catcat_prop_plot",
    "bi_catcat_freq_plot", "bi_catcat_prop_plot2", "bi_catcat_freq_plot2",
    "bi_catcat_table", "bi_sigtest"),
  sort_by = ".upper",
  data_label = saros::get_data_label_opts(),
  always_show_bi_for_by = c(),
  categories_treated_as_na = c(),
  variables_always_at_top = c(),
  variables_always_at_bottom = c(),
  return_raw = TRUE,
  panel_tabset_mesos = TRUE,
  showNA = c("never", "always", "ifany"),
  totals = FALSE,
  hide_label_if_prop_below = 0.01,
  hide_bi_entry_if_sig_above = 1,
  hide_test_if_n_below = 10,
  hide_chr_for_others = TRUE,
  label_font_size = 8,
  main_font_size = 8,
  x_axis_label_width = 20,
  plot_height_multiplier = NA_real_,
  plot_height_fixed_constant = NA_real_,
  plot_height_max = 20,
  plot_height_min = 1.5,
  png_scale = 1.2,
  png_width = 14,
  png_height = 16,
  vertical_height = 12,
  max_width_obj = 90,
  max_width_file = 64,
  font_family = "sans",
  open_after_drafting = FALSE,
  vertical = FALSE,
  mesos_first = TRUE,
  single_y_bivariate_elements = FALSE,
  descend = TRUE,
  require_common_categories = TRUE,
  flexi = TRUE,
  colour_palette = NULL,
  colour_na = "gray90",
  colour_2nd_binary_cat = NULL,
  digits = 1,
  data_label_decimal_symbol = ".",
  reps = 1000,
  information = c(".variable_label", ".category", ".count", ".count_se", ".proportion",
    ".proportion_se", ".mean", ".mean_se", ".data_label", ".comb_categories",
    ".sum_value"),
  contents = c("intro", "not_used_category", "mode_max", "value_max", "value_min",
    "value_diff", "mean_max", "mean_min", "mean_diff", "median_max", "median_min",
    "median_diff", "variance_max", "variance_min"),
  include_numbers = TRUE,
  n_top_bottom = 1,
  translations = list(last_sep = " and ", intro_prefix =
    "We will now look at the questions asked regarding ", intro_suffix = "",
    mode_max_onfix = " on ", mode_max_prefix = "The most common responses were ",
    mode_max_suffix = "", not_used_prefix =
    "The following response categories were not used: ", not_used_suffix = "",
    value_max_prefix = "", value_max_infix =
    " {?is/are} the {dots$n_top_bottom} item{?s} where the most responded ",
    value_max_suffix = "", value_min_prefix = "", value_min_infix =
    " {?is/are} the {dots$n_top_bottom} item{?s} where the fewest responded ", 
    
    value_min_suffix = "", mean_onfix = "M = ", mean_max_prefix =
    "They have highest mean on ", mean_max_suffix = "", mean_min_prefix =
    "They have lowest mean on ", mean_min_suffix = "", median_onfix = "Median = ",
    median_max_prefix = "They have highest median on ", median_max_suffix = "",
    median_min_prefix = "They have lowest median on ", median_min_suffix = "",
    intro_by_prefix = "We will now look at the questions asked regarding ",
    intro_by_infix = " broken down by ", intro_by_suffix = "", by_breakdown = " by ", 
  
      n_equal_prefix = " (N = ", n_equal_suffix = ")", table_heading_N = "Total (N)",
    by_total = "Everyone", sigtest_prefix = "Significance testing of ", sigtest_suffix =
    "", mesos_group_prefix = " Group: ", mesos_group_suffix = "", mesos_label_all_others
    = "Others", empty_chunk_text = "\nText\n", flexi_input_chapter = "Chapter(s):",
    flexi_input_dep = "Dependent variable(s):", flexi_input_indep =
    "Independent variable:", flexi_input_mesos_group = "Filter:", flexi_figure_type =
    "Figure type:", flexi_data_label = "Summary to display", 
     flexi_showNA =
    "Show NA (Missing)", flexi_sort_by = "Sort by", flexi_totals = "Totals", flexi_digits
    = "Digits after decimal", flexi_table = "Table", flexi_figure = "Figure",
    flexi_cols_variable_name = "Variable name", flexi_cols_variable_label =
    "Variable label", flexi_cols_category = "Response category", flexi_cols_count = "N",
    flexi_cols_count_se = "SE(N)", flexi_cols_proportion = "Proportion",
    flexi_cols_proportion_se = "SE(Proportion)", flexi_cols_mean = "Mean",
    flexi_cols_mean_se = "SE(Mean)", 
     flexi_cols_data_label = "Data label",
    flexi_cols_comb_categories = "Combined categories", flexi_cols_sum_value =
    "Sum of data label across combined categories", flexi_validate =
    "Error: Columns must have some categories in common.", flexi_settings = "Settings",
    flexi_basic_settings = "Basic", flexi_advanced_settings = "Advanced",
    flexi_input_indep_none = "<none>", flexi_figure_type_proportion = "Proportion",
    flexi_figure_type_frequency = "Frequency", flexi_hide_label_if_prop_below =
    "Hide label if proportion below:")
)

Arguments

data

Survey data

obj:<data.frame>|obj:<tbl_df> // Required

A data frame (or a srvyr-object) with the columns specified in the chapter_overview 'dep_cat', etc columns.

chapter_overview

What goes in each chapter

obj:<data.frame>|obj:<tbl_df> // Required

Data 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

<dynamic-dots>

Arguments forwarded to the corresponding functions that create the elements.

path

Output path

scalar<character> // default: NULL (optional)

Path to save all output.

title

Title of report

scalar<character> // default: NULL (optional)

Added automatically to YAML-header of index.qmd-file.

authors

Authors of entire report

vector<character> // default: NULL (optional)

If NULL, infers from chapter_overview$authors, and collates for entire report.

mesos_report

Whether to produce reports per mesos group

scalar<logical> // default: FALSE If false, returns a regular single report.

mesos_var

Variable in ´data´ indicating groups to tailor reports for

scalar<character> // default: NULL (optional)

Column name in data indicating the groups for which mesos reports will be produced.

label_separator

Variable label separator

scalar<character> // default: NULL (optional)

String to split labels on main question and sub-items.

name_separator

Variable name separator

scalar<character> // default: NULL (optional)

String to split column names in data between main question and sub-items

report_yaml_file

Path to YAML-file to insert into index.qmd

scalar<character> // default: NULL (optional)

Path to file used to insert header YAML, in report.

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.

qmd_start_section_filepath, 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 qmds.

index_filename

Index filename

scalar<character> // default: "index.qmd" (optional)

The name of the main index Quarto file (and its subfolder) used to collect all the chapters.

groupby

Grouping columns

vector<character> // default: NULL (optional)

Column names used for identifying chapters and sections.

element_names

Elements to be reported

vector<character> // default: NULL (optional)

Elements to be reported for all sets (batteries) of y-variables.

sort_by

What to sort output by

vector<character> // default: NULL (optional)

Sort output (and collapse if requested).

  • ".top"The proportion for the highest category available in the variable.

  • ".upper"The sum of the proportions for the categories above the middle category.

  • ".mid_upper"The sum of the proportions for the categories including and above the middle category.

  • ".mid_lower"The sum of the proportions for the categories including and below the middle category.

  • ".lower"The sum of the proportions for the categories below the middle category.

  • ".bottom"The proportions for the lowest category available in the variable.

  • ".variable_label"Sort by the variable labels.

  • ".id"Sort by the variable names.

  • ".by_group"The groups of the by argument.

  • Character vector of category labels to sum together.

data_label

Data label

scalar<character> // default: "proportion" (optional)

One of "proportion", "percentage", "percentage_bare", "count", "mean", or "median".

always_show_bi_for_by

Always show bivariate for by-variable

vector<character> // default: NULL (optional)

Specific combinations with a by-variable where bivariates should always be shown.

categories_treated_as_na

NA categories

vector<character> // default: NULL (optional)

Categories that should be treated as NA.

variables_always_at_top, variables_always_at_bottom

Top/bottom variables

vector<character> // default: NULL (optional)

Column names in data that should always be placed at the top or bottom of figures/tables.

return_raw

NOT IN USE

scalar<integer> // default: FALSE

Whether to return the raw static element.

panel_tabset_mesos

mesos panel tabset

scalar<logical> // default: TRUE (optional)

Whether in mesos reports the comparison group should be displayed as a Quarto panel tabset (TRUE), or above each other (FALSE).

showNA

Show/hide NA in categorical variables

scalar<logical> // default: NULL (optional)

Whether to show NA in categorical variables (one of c("ifany", "always", "never")).

totals

Include totals

scalar<logical> // default: FALSE (optional)

Whether to include totals in the output.

hide_label_if_prop_below

Hide label threshold

scalar<numeric> // default: NULL (optional)

Whether to hide label if below this value. NOTE: Future versions will likely distinguish between element_types.

hide_bi_entry_if_sig_above

p-value threshold for hiding bivariate entry

scalar<double> // default: 1 (optional)

Whether to hide bivariate entry if significance is above this value. Defaults to showing all.

hide_test_if_n_below

Threshold n for hiding significance test

scalar<integer> // default: 0 (optional)

If N is below this value, p-value will not be shown.

hide_chr_for_others

Hide open response displays for others

scalar<logical> // default: TRUE (optional)

For mesos reports using the element "chr_table", open responses are displayed for also the entire sample (FALSE) or only for the mesos group to ensure data privacy (TRUE).

label_font_size

Data labels font size

scalar<integer> // default: 10 (optional)

Font size for data labels.

main_font_size

Main font size

scalar<integer> // default: 12 (optional)

Font size for all other text.

x_axis_label_width

X-axis label width of plots

scalar<integer> // default: 20 (optional)

Width of the labels used for the categorical column names.

plot_height_multiplier

Height multiplier

scalar<double> // default: 1

Height in cm per chart entry, for all static plots.

plot_height_fixed_constant

Height constant addition

scalar<double> // default: 0

Fixed height in cm to add to all static plots.

plot_height_max

Maximum plot height

scalar<double> // default: 10 (optional)

Maximum height for the plot.

plot_height_min

Minimum plot height

scalar<double> // default: 2 (optional)

Minimum height for the plot.

png_scale

PNG scale

scalar<double> // default: 1 (optional)

Scale factor for PNG output.

png_width, png_height

PNG width and height

scalar<double> // default: 12 (optional)

Width for PNG output.

vertical_height

Vertical height

scalar<double> // default: NULL (optional)

Height for vertical layout of plot? NEEDS CHECKING

max_width_obj

Maximum object width

scalar<integer> // default: NULL (optional)

Maximum width for object names in the Quarto script. In particular useful when having label as part of the structure.

max_width_file

Maximum filename width

scalar<integer> // default: NULL (optional)

Maximum width for any filename. Due to OneDrive having a max path of about 400 characters, this can quickly be exceeded with a long path base path, long file names if using labels as part of structure, and hashing with Quarto's cache: true feature. This argument truncates the filenames.

font_family

Font family

scalar<character> // default: "sans" (optional)

Word font family. See officer::fp_text.

open_after_drafting

Whether to open index.qmd

scalar<logical> // default: FALSE (optional)

Whether to open the main output file (index.qmd) after completion.

vertical

Orientation of plots

scalar<logical> // default: FALSE (optional)

If FALSE (default), then horizontal plots.

mesos_first

mesos first

scalar<logical> // default: FALSE (optional)

Whether to place the mesos group element before or after the entire sample.

single_y_bivariate_elements

Single Y bivariate elements

scalar<logical> // default: TRUE (optional)

Whether to display bivariates with a single dependent variable. NEEDS CHECKING.

descend

Sorting order

scalar<logical> // default: FALSE (optional)

Reverse sorting of sort_by.

require_common_categories

Check common categories

scalar<logical> // default: NULL (optional)

Whether to check if all items share common categories.

flexi

Create page with user-editable categorical plots and tables

scalar<logical> // default: FALSE (optional)

Whether to include totals in the output.

colour_palette

Colour palette

vector<character> // default: NULL (optional)

Must contain at least the number of unique values (including missing) in the data set.

colour_na

Colour for NA category

scalar<character> // default: NULL (optional)

Colour as a single string for NA values.

colour_2nd_binary_cat

Colour for second binary category

scalar<character> // default: "#ffffff" (optional)

Colour for second category in binary variables. Often useful to hide this.

digits

Decimal places

scalar<integer> // default: 0L (optional)

Number of decimal places.

data_label_decimal_symbol

Decimal symbol

scalar<character> // default: "." (optional)

Decimal marker, some might prefer a comma ',' or something else entirely. NOTE: Future version will likely postpone formatting this until gt(), kable(), etc.

reps

Number of permutations

scalar<integer> // default: 100 (optional)

Number of permutations to be performed in bootstrap significance tests.

information

Pre-computed information

scalar<character> // default: NULL (optional)

Which pre-computed information for each variable-category to display.

contents

Text interpretations

vector<character> // default: all available (optional)

The type of text interpretations to return.

include_numbers

Include numbers

scalar<logical> // default: NULL (optional)

Whether or not to include the actual numbers in parentheses.

n_top_bottom

Top and bottom entries to report

scalar<integer> // default: NULL (optional)

The number of top and bottom entries to report.

translations

Translations

list // default: saros:::.saros.env$defaults$translations (optional)

Named list of strings for translations.

Value

Path to index qmd-file. If not specified in the yaml_path file, will default to index.qmd.

Details

This function requires at a minimum a dataset (data frame and tibbles are supported so far). Note that saros treats data as they are stored: numeric, integer, factor, ordinal, character, and datetime. Currently, only factor/ordinal and character are implemented. Second, the chapter_overview must be specified, also as a (small) data frame, with at least the character columns 'chapter' and 'dep', where the first names the output chapters, and the 'dep'-column contain comma-separated (alternatively using tidyselect-syntax) columns in the data which are to be treated as dependent variables. See chapter_overview for more options.

Examples

# \donttest{
draft_report(
    chapter_overview = ex_survey_ch_overview,
    data = ex_survey1,
    path = tempdir())
#> Refining chapter_overview...
#> Generating report ...
#> Generating chapter 2 Ambivalence
#> Generating report ...

#> Generating chapter 3 Big mysteries
#> Generating report ...

#> Generating chapter 4 Confidence
#> Generating report ...

#> Generating report ...
#> 
#> 34.472 0.243 34.874 0 0
#> /tmp/RtmpC6LeHP/index.qmd
# }