A grouped tibble. If not grouped, will give a warning and continue with rowwise processing, which is unlikely what you want.

The raw data, with matching column names as in chapter_structure$.variable_name_dep.

Glue templates.

String, name of new variable to attach. Defaults to ".n_range"

String, path from where to copy the contents, and where to copy them to.

Flag. Defaults to FALSE.

Flag. Defaults to FALSE. If TRUE, only copies folders.

String, path to where to create the project files

String. Path to the YAML file that defines the folder structure. Defaults to system.file("templates", "_project_structure_en.yaml").

String. One of c("none", "max_local", "max_global").

Flag. Whether to inherit numbering from parent folder.

String. Replace separators between words in folder names. Defaults to NULL.

String. Defaults to word_separator.

String. Separator between numbering part and name.

String. One of c("asis", "sentence", "lower", "upper", "title", "snake").

named character vector. Each name in this vector will be replaced with its "{{value}}" in the structure_path file

Boolean. Defaults to TRUE in initialize_saros_project(), FALSE in create_directory_structure().

Boolean. Defaults to FALSE.

Data.frame/tibble with (at least) emails and usernames

String, name of email column

String, name of username column in email_data_frame

Path to a local .htpasswd file containing username:password header and : as separator.

Flag, defaults to FALSE. Whether usernames existing in password file but not email file will result in warnings.

String, subject line and email body respectively. Supports glue syntax referring to columns found in the email data frame or password file.

Dynamic dots forwarded to quarto::quarto_render

String, path to where to place R placeholder files. If NULL, will not create any.

String, path to where to find CSV-field containing the columns folder_name, folder_scope, file_name, file_scope. If NULL, defaults to system.file("templates", "r_files.csv")).

Flag. Whether to add files marked as 1 (or TRUE) in the optional column. Defaults to TRUE.

Flag. Whether to add value from column 'file_scope' to beginning of each file. Default to TRUE.

String to add before file_scope. Defaults to "### "

Flag. Whether to create README file in each folder with the folder_scope column cell in r_files_source_path. Defaults to FALSE.

String. Replace separators between words in folder names. Defaults to NULL.

String. One of c("asis", "sentence", "lower", "upper", "title", "snake").

String. One of c("none", "max_local", "max_global").

Flag. Whether to inherit numbering from parent folder.

String. Defaults to word_separator.

String. Separator between numbering part and name.

URL to zip file, as string.

String, where to store zip-file. Defaults to a temporary location.

Character vector of files in zip-file to include. See zip::unzip().

String, directory to where to store the unzipped files.

Flag, whether to ask user if conflicting files should be overwritten, if any. Defaults to TRUE.

Flag, whether to overwrite files in out_path. Defaults to FALSE.

Flag or string. If FALSE (default), does nothing. If TRUE (requires rstudioapi-pkg), opens an assumed .Rproj-file in out_path after copying, or gives warning if not found. Alternatively, a string (path) can be provided. Defaults to file.path(out_path, ".Rproj") if such exists. Set to NULL or FALSE to ignore.

Flag. Whether to open new project in a new RStudio session. Defaults to TRUE.

Survey data

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

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

What goes into each chapter and sub-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.

Output path

⁠scalar<character>⁠ // default: tempdir() (optional)

Path to save all output. Defaults to a temporary directory.

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).

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.

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

⁠scalar<character>⁠ // default: "index" (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.

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

⁠scalar<character>⁠ // default: "report" (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.

Whether report.qmd includes {{< include 'chapter.qmd' >}}

⁠scalar<logical>⁠ // default: FALSE

Useful to have in mesos reports. However, bear in mind that including other qmd files with conflicting YAML-headers might be risky.

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.

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 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.

Check common categories

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

Whether to check if all items share common categories.

Create a combined report?

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

Whether to create a qmd file that merges all chapters into a combined report.

Toggle whether to make qmd-files

⁠scalar<logical>⁠ // default: TRUE

Sometimes it is useful to only create chapter_dataset files if these have been updated, without having to overwrite the qmd files.

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 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, if attach_chapter_dataset=TRUE. Not publicly available.

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.

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

Prefix string for all qmd filenames

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

For mesos setup it might be useful to set these files (and related sub-folders) with an underscore (filename_prefix = "_") in front as other stub files will include these main qmd files.

String attached to beginning of data-file and data-object

⁠scalar<string>⁠ // default: "data_"

Strings around files in report.qmd

⁠scalar<string>⁠ // default: "\{\{< include " and " >\}\}"

The prefix and suffix for each of the chapters being included in the report.qmd file if report_includes_files = TRUE.

Path to log file

⁠scalar<string>⁠ // default: "_log.txt" (optional)

Path to log file. Set to NULL to disable logging.

Character vector of file/folder names

Maximum character length

Flag, whether a hyphen - is acceptable.

String, replacement for illegal characters and spaces.

Flag, whether output should be valid as R object name.

Flag, whether to force all characters to lower.

Flag, whether all should be unique.

What goes into each chapter and sub-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.

Survey data

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

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

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).

Output path

⁠scalar<character>⁠ // default: tempdir() (optional)

Path to save all output. Defaults to a temporary directory.

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.

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 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.

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.

Toggle whether to make qmd-files

⁠scalar<logical>⁠ // default: TRUE

Sometimes it is useful to only create chapter_dataset files if these have been updated, without having to overwrite the qmd files.

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 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, if attach_chapter_dataset=TRUE. Not publicly available.

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.

Prefix string for all qmd filenames

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

For mesos setup it might be useful to set these files (and related sub-folders) with an underscore (filename_prefix = "_") in front as other stub files will include these main qmd files.

String attached to beginning of data-file and data-object

⁠scalar<string>⁠ // default: "data_"

String, where to write qmd-file.

String, bare name of qmd-file. Default: "report". If NULL, generates a sanitized version of the title. If both filename and title are NULL, errors.

A string containing the filepath to a yaml-file to be inserted at top of qmd-file.

String, filepath to a qmd-file inserted at start and end of file.

What goes into each chapter and sub-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.

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.

Character. If applied, will construct list of links to files with said output_filename.

Internal call argument. Not to be fiddled with by the user.

String. The path to the directory whose structure needs to be captured.

String. The path where the YAML file will be saved.

Boolean. Whether to remove numeric prefixes and any resulting leading non-alphanumeric characters from folder names. Defaults to FALSE.

Positive integer.

Dataset

Optional, character vector of column names or integer vector of positions

Flag, whether to return as list or character vector

String. The path to the parent directory.

Boolean. Whether to count existing folders for numbering.

String. Original folder name.

String. One of c("asis", "sentence", "lower", "upper", "title", "snake").

String.

Character vector, named.

digit

One of "none" (no zero-leading prefix), "max_global" (counts with leading zeroes matching the maximally observed items in any of the subfolders), "max_local" (same as max_global, but only considering the current folder of the item)

Integer. The fixed width of the counting.

String, path to parent folder.

String, or NA. If not NA, adds the parent_numbering to the left side of the counter.

String, separates the parent number from the child number, if parent_numbering is not NA.

Flag. Whether to consider existing folders when counting. Defaults to FALSE.

String, path to where to create the project files

String. Path to the YAML file that defines the folder structure. Defaults to system.file("templates", "_project_structure_en.yaml").

String. One of c("none", "max_local", "max_global").

Flag. Whether to inherit numbering from parent folder.

String. Replace separators between words in folder names. Defaults to NULL.

String. Separator between numbering part and name.

named character vector. Each name in this vector will be replaced with its "{{value}}" in the structure_path file

String. Defaults to word_separator.

String. One of c("asis", "sentence", "lower", "upper", "title", "snake").

Boolean. Defaults to FALSE.

String, path to where to place R placeholder files. If NULL, will not create any.

String, path to where to find CSV-field containing the columns folder_name, folder_scope, file_name, file_scope. If NULL, defaults to system.file("templates", "r_files.csv")).

Flag. Whether to add files marked as 1 (or TRUE) in the optional column. Defaults to TRUE.

Flag. Whether to add value from column 'file_scope' to beginning of each file. Default to TRUE.

String to add before file_scope. Defaults to "### "

Flag. Whether to create README file in each folder with the folder_scope column cell in r_files_source_path. Defaults to FALSE.

Boolean. Defaults to TRUE in initialize_saros_project(), FALSE in create_directory_structure().

Overview of chapter section

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

Data frame (or tibble, possibly grouped). Must contain column 'dep' with similar items. See draft_report().

Vector of groups

⁠vector<character>⁠ // default: NULL (Optional)

Internal usage.

Object

⁠scalar<character>⁠ // Required. default: settings.yaml

What goes into each chapter and sub-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.

Survey data

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

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

Chunk templates

⁠obj:<data.frame>|obj:<tbl_df>|NULL⁠ // default: NULL (optional)

Must contain columns name (user-specified unique name for the template), template (the chunk template as {glue}-specification, variable_type_dep and optionally variable_type_indep. The latter two are list-columns of prototype vectors specifying which data the template will be applied to. Can optionally contain columns whose names match the default options for the function. These will then override the default function-wide options for the specific template.

Variable label separator

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

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

Variable name separator

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

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

Single y bivariates if indep-cats above ...

⁠scalar<integer>⁠ // default: 3 (optional)

Figures and tables for bivariates can become very long if the independent variable has many categories. This argument specifies the number of indep categories above which only single y bivariates should be shown.

Single y bivariates if dep-vars above ...

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

Figures and tables for bivariates can become very long if there are many dependent variables in a battery/question matrix. This argument specifies the number of dep variables above which only single y bivariates should be shown. Set to 0 to always show single y bivariates.

Always show bivariate for indep-variable

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

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

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 result if N below

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

Whether to hide result if N for a given dataset is below this value. NOTE: Exceptions will be made to chr_table and chr_plot as these are typically exempted in the first place. This might change in the future with a separate argument.

Hide variable from outputs if containing all NA

⁠scalar<boolean>⁠ // default: TRUE (optional)

Whether to remove variables if all values are NA.

Keep dep-indep if no overlap

⁠scalar<boolean>⁠ // default: FALSE (optional)

Whether to keep dep-indep rows if there is no overlap.

Grouping columns

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

Column names used for identifying chapters and sections.

Grouping columns

⁠vector<character>⁠ or ⁠named vector<logical>⁠ // default: NULL (optional)

Column names used for sorting section within each organize_by group. If character vector, will assume all are to be arranged in ascending order. If a named logical vector, FALSE will indicate ascending, TRUE descending. Defaults to sorting in ascending order (alphabetical) for commonly needed variable name/label info, and in descending order for chunk_templates as one typically wants univariates before bivariates.

Whether to place NAs first when sorting

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

Default ascending and descending sorting with dplyr::arrange() is to place NAs at the end. This would have placed univariates at the end, etc. Thus, saros places NAs first in the section. Set this to FALSE to override.

Maximum object width

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

Maximum width for names of objects (in R/Python environment), chunks (#| label: ) and optional files. Note, will always replace variable labels with variable names, to avoid very long file names. Note for filenames: 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. Thus consider restricting max_width_file to lower than what you optimally would have wished for.

Maximum clean folder name length

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

Whereas max_width_file truncates the file name, this argument truncates the folder name. It will not impact the report or chapter names in website, only the folders.

Separator string

⁠scalar<character>⁠ // default: "_" (optional)

Separator to use between grouping variables. Defaults to underscore for object names and hyphen for chunk labels and file names.

Prefix string for all qmd filenames

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

For mesos setup it might be useful to set these files (and related sub-folders) with an underscore (filename_prefix = "_") in front as other stub files will include these main qmd files.

Dynamic dots

<dynamic-dots>

Arguments forwarded to the corresponding functions that create the elements.

Whether to display progress message

⁠scalar<logical>⁠ // default: TRUE

Mostly useful when hide_bi_entry_if_sig_above < 1

Name for the variable_group_dep column

⁠scalar<string>⁠ // default: ".variable_group_dep"

This column is used to group variables that are part of the same bivariate analysis.

Set a prefix to more easily find it in your labels

⁠scalar<string>⁠ // default: NULL

By default, the .variable_group column is just integers. If you wish to use this as part of your object/label/filename numbering scheme, a number by itself will not be very informative. Hence you could set a prefix such as "Group" to distinguish this column from other columns in the chapter_structure.

⁠scalar<string>⁠ // default: ⁠"{n}" and "[{n[1]}, {n[2]}]⁠ (optional)

Glue templates for the n_range columns to be created.

Path to log file

⁠scalar<string>⁠ // default: "_log.txt" (optional)

Path to log file. Set to NULL to disable logging.

String, path to where your html-files are located. Defaults to "_site"

Character vector of regex patterns to search for. Defaults to c("report\.pdf", "report\.docx")

Optional character vector of report files (qmd). Can be obtained within a project by Sys.getenv("QUARTO_PROJECT_OUTPUT_FILES")

If no files are given, a path to the root folder of the local "site".

Path to where report files can be (recursively) found.

Path to _site

Paths to where _extensions and _images folders can be found and copied to wherever needed

If TRUE, will collect warnings if a file fails to render or be copied. If FALSE (default), will stop the rendering process.

Additional arguments passed to quarto::render()

String. Folder where site will be located if using FTP-server. Needed for .htaccess-files.

String. Local folder for website, typically "_site".

String, relative path from basepath to the folder where the restricted folders are located. (E.g. the "mesos"-folder)

Flag. Whether to provide warning or error if paths do not exist.

String. Path to main file containing all usernames and passwords formatted with a colon between username and password.

Data frame. If NULL (default), will use folder names as usernames. Otherwise, a data frame with two columns: "folder" and "username" where "folder" is the name of the folder and "username" is the username for that folder.

Character vector. Usernames in local_main_htpasswd_path which always have access to folder

Integer, number of rounds in the bcrypt algorithm. The higher the more time consuming and harder to brute-force.

Boolean, if TRUE (default) will create new users and add them to local_main_password_path. See also password_input.

String, either "prompt" which asks the user for input. Alternatively, a number stored as string for a generated random password of said length: "8", "10", "12", "16"

Character vector. "netlify" will create _headers file used for Netlify. "apache" will create .htaccess and .htpasswd files used for general FTP-servers.

String, path to where the _metadata.yml, stub QMD-files and their subfolders are created.

String, optional name of a subfolder of the mesos_var folder in where to place all mesos_group folders.

Character vector of files used as templates for the mesos stubs.

List of single-column data frames where each variable is a mesos variable, optionally with a variable label indicating its pretty name. The values in each variable are the mesos groups. NA is silently ignored.

Character vector of files for which titles should be set. Optional but recommended.

Optional strings, any regex pattern to search and replace in the qmd-files. If NULL, will ignore it.

String. Experimental feature for allowing Rmarkdown, not yet tested.

String or NULL. If a string will add title and subtitle fields to the _metadata.yml-files in the deepest child folders. The title is the mesos_group. The subtitle is a concatenation of the folder name of the main_directory and the mesos_var label.

String for the include section of the stub qmd files.

⁠scalar<character>⁠ // Required. default: settings.yaml

⁠vector<character>⁠ // Optional. default: c("data", "...", "dep", "indep", "chapter_structure", "chapter_overview")

A character vector of argument (names) not to be written to file.