Type:	Package
Title:	Semi-Automatic Reporting of Ordinary Surveys
Version:	1.6.2
Maintainer:	Stephan Daus <stephus.daus@gmail.com>
Description:	Offers a systematic way for conditional reporting of figures and tables for many (and bivariate combinations of) variables, typically from survey data. Contains interactive 'ggiraph'-based (https://CRAN.R-project.org/package=ggiraph) plotting functions and data frame-based summary tables (bivariate significance tests, frequencies/proportions, unique open ended responses, etc) with many arguments for customization, and extensions possible. Uses a global options() system for neatly reducing redundant code. Also contains tools for immediate saving of objects and returning a hashed link to the object, useful for creating download links to high resolution images upon rendering in 'Quarto'. Suitable for highly customized reports, primarily intended for survey research.
Note:	Free to use for non-Norwegian institutions, otherwise see LICENSE.
License:	MIT + file LICENSE
URL:	https://nifu-no.github.io/saros/, https://github.com/NIFU-NO/saros
BugReports:	https://github.com/NIFU-NO/saros/issues
Depends:	R (≥ 4.2.0)
Imports:	cli, dplyr, forcats, fs, ggiraph, ggplot2, glue, grDevices, mschart, officer, rlang, stringi, stats, tidyr, tidyselect, utils, vctrs
Suggests:	covr, haven, labelled, pdftools, quarto, knitr, readr, scales, spelling, srvyr, survey, testthat (≥ 3.0.0), tibble, vdiffr, withr, writexl, readxl
Config/testthat/edition:	3
Encoding:	UTF-8
RoxygenNote:	7.3.3
Language:	en-US
VignetteBuilder:	quarto
Config/Needs/website:	rmarkdown
Config/testthat/parallel:	true
LazyData:	true
NeedsCompilation:	no
Packaged:	2026-04-29 23:18:22 UTC; py128
Author:	Stephan Daus [aut, cre, cph], Julia Silge [ctb] (Author of internal scale_x_reordered), David Robinson [ctb] (Author of internal scale_x_reordered), Nordic Institute for The Studies of Innovation, Research and Education (NIFU) [fnd], Kristiania University College [fnd]
Repository:	CRAN
Date/Publication:	2026-04-29 23:40:02 UTC

saros: Semi-Automatic Reporting of Ordinary Surveys

Description

Offers a systematic way for conditional reporting of figures and tables for many (and bivariate combinations of) variables, typically from survey data. Contains interactive 'ggiraph'-based (https://CRAN.R-project.org/package=ggiraph) plotting functions and data frame-based summary tables (bivariate significance tests, frequencies/proportions, unique open ended responses, etc) with many arguments for customization, and extensions possible. Uses a global options() system for neatly reducing redundant code. Also contains tools for immediate saving of objects and returning a hashed link to the object, useful for creating download links to high resolution images upon rendering in 'Quarto'. Suitable for highly customized reports, primarily intended for survey research.

Author(s)

Maintainer: Stephan Daus stephus.daus@gmail.com (ORCID) [copyright holder]

Other contributors:

• Julia Silge (Author of internal scale_x_reordered) [contributor]

• David Robinson (Author of internal scale_x_reordered) [contributor]

• Nordic Institute for The Studies of Innovation, Research and Education (NIFU) [funder]

• Kristiania University College [funder]

See Also

Useful links:

• https://nifu-no.github.io/saros/

• https://github.com/NIFU-NO/saros

• Report bugs at https://github.com/NIFU-NO/saros/issues

Obtain range of N for a given ggobj.

Description

Internal workhorse function for calculating N range from plot data

Usage

.n_rng2_impl(
  data,
  glue_template_1 = "{n}",
  glue_template_2 = "[{n[1]}-{n[2]}]"
)

Arguments

Value

Always a string.

Add response category ordering (only useful for long format cat-cat tables)

Description

Add response category ordering (only useful for long format cat-cat tables)

Usage

add_category_order(data, sort_by = NULL)

Arguments

Value

Dataset with .category_order column added

Add dependent variable ordering

Description

Add dependent variable ordering

Usage

add_dep_order(data, sort_by, descend = FALSE)

Arguments

Value

Dataset with .dep_order column added

Add independent variable category ordering

Description

Add independent variable category ordering

Usage

add_indep_order(data, sort_by = ".factor_order", descend = FALSE)

Arguments

Value

Dataset with .indep_order column added

Create sorting order variables for output dataframe

Description

This module provides centralized sorting functionality to ensure consistent ordering across all output types (tables, plots) by using explicit order columns instead of relying on factor levels that can be overridden. Apply comprehensive sorting order to survey data

Usage

add_sorting_order_vars(
  data,
  sort_dep_by = ".variable_position",
  sort_indep_by = ".factor_order",
  sort_category_by = NULL,
  descend = FALSE,
  descend_indep = FALSE
)

Arguments

Value

Dataset with added order columns: .dep_order, .indep_order, .category_order

Apply final arrangement based on order columns

Description

Apply final arrangement based on order columns

Usage

apply_final_arrangement(data)

Arguments

Value

Arranged dataset

Apply label wrapping based on plot layout

Description

Helper function to consistently wrap variable labels based on whether they appear on facet strips or x-axis, and whether inverse layout is used.

Usage

apply_label_wrapping(
  data,
  indep_length,
  inverse,
  strip_width,
  x_axis_label_width
)

Arguments

Value

Data frame with wrapped .variable_label column

Apply legacy sorting adjustments for special cases

Description

Apply legacy sorting adjustments for special cases

Usage

apply_legacy_sorting_adjustments(
  data,
  indep_names = character(0),
  translations = list()
)

Arguments

Value

Dataset with legacy adjustments applied

Arrange output data by prespecified orders

Description

Standard data arrangement for table functions

Usage

arrange_table_data(data, col_basis, indep_vars = NULL)

Arguments

Value

Arranged data frame

Apply sorting with optional descending order

Description

Unified helper to consistently handle ascending/descending sort order across all sorting functions.

Usage

arrange_with_order(data, order_col, descend = FALSE)

Arguments

Value

Arranged dataset

Attach dep_label_prefix attribute to a make_content output object

Description

Attaches the main question (i.e. the label prefix of the dep variables) as an attribute "dep_label_prefix" on the returned object. Works for ggplot, data.frame, and mschart objects. Should not be called when returning an rdocx object.

Usage

attach_dep_label_prefix(obj, main_question)

Arguments

Details

Storage location by class:

• ggplot / gg: stored on obj$data when obj$data is a data.frame, so the attribute survives further + operations. Falls back to attr(obj, ...) when obj$data is a waiver() (empty ggplot()).

• ms_barchart: stored on obj$data (consistent with ggplot).

• everything else (data.frame, tibble, …): stored on the object itself.

Value

obj, unchanged when main_question is not a non-empty string, otherwise with "dep_label_prefix" set in the appropriate location.

Auto-Detect Appropriate Output Type Based on Variable Types

Description

Internal helper function that determines the most appropriate output type based on the classes of dependent and independent variables.

Usage

auto_detect_makeme_type(data, dep, indep = NULL)

Arguments

Value

Character string with the detected type:

• "int_plot_html" for numeric/integer dependent variables

• "chr_table_html" for single character dependent variable

• "cat_plot_html" for factor/ordered dependent variables or multiple character variables

Build Custom Palette Function

Description

Creates a palette function that matches colors to factor levels based on palette_codes and priority_palette_codes.

Usage

build_custom_palette(palette_codes, fct_levels, priority_palette_codes = NULL)

Arguments

Value

A palette function that takes n (number of colors) and lvls (levels) and returns a named character vector of colors.

Calculate ordering based on a specific category value

Description

Calculate ordering based on a specific category value

Usage

calculate_category_order(data, category_value, descend = FALSE)

Arguments

Value

Numeric vector of ordering values

Calculate ordering based on a specific column value

Description

Calculate ordering based on a specific column value

Usage

calculate_column_order(data, column_name, descend = FALSE)

Arguments

Value

Numeric vector of ordering values

Calculate independent variable ordering based on a specific category value

Description

Calculate independent variable ordering based on a specific category value

Usage

calculate_indep_category_order(
  data,
  category_value,
  indep_col,
  descend_indep = FALSE
)

Arguments

Value

Numeric vector of ordering values

Calculate independent variable ordering based on a specific column value

Description

Calculate independent variable ordering based on a specific column value

Usage

calculate_indep_column_order(
  data,
  column_name,
  indep_col,
  descend_indep = FALSE
)

Arguments

Value

Numeric vector of ordering values

Calculate independent variable ordering based on position categories

Description

Calculate independent variable ordering based on position categories

Usage

calculate_indep_proportion_order(
  data,
  method,
  indep_col,
  descend_indep = FALSE
)

Arguments

Value

Numeric vector of ordering values

Calculate independent variable ordering based on multiple category values

Description

Calculate independent variable ordering based on multiple category values

Usage

calculate_indep_sum_value_order(
  data,
  category_values,
  indep_col,
  descend_indep = FALSE
)

Arguments

Value

Numeric vector of ordering values

Calculate ordering based on multiple category values

Description

Calculate ordering based on multiple category values

Usage

calculate_multiple_category_order(data, category_values, descend = FALSE)

Arguments

Value

Numeric vector of ordering values

Calculate proportion-based ordering for dependent variables

Description

Calculate proportion-based ordering for dependent variables

Usage

calculate_proportion_order(data, method, descend = FALSE)

Arguments

Value

Numeric vector of ordering values

Calculate ordering based on .sum_value (for category-based sorting)

Description

Calculate ordering based on .sum_value (for category-based sorting)

Usage

calculate_sum_value_order(data, descend = FALSE)

Arguments

Value

Numeric vector of ordering values

Check Quarto Website Folders for Missing index.qmd

Description

Scans a Quarto website project directory for folders that contain .qmd files (directly or in subfolders) but are missing an index.qmd file. Such folders often cause a malfunctioning navigation menu in the rendered Quarto website.

Folders whose names start with ⁠_⁠ or . are excluded, as these are typically Quarto internal or hidden directories.

Usage

check_quarto_website_index(path = ".", quiet = FALSE)

Arguments

Value

A character vector of folder paths (relative to path) that contain .qmd files but lack an index.qmd. Returned invisibly.

Examples

## Not run: 
# Check the current project
check_quarto_website_index()

# Check a specific directory
check_quarto_website_index("path/to/quarto-project")

## End(Not run)

Compute Full Category Levels from Unfiltered Data

Description

Internal helper function that computes the complete set of category levels from the full unfiltered dataset. This ensures consistent color assignments across all crowd groups when using mesos_var/mesos_group filtering.

Usage

compute_full_category_levels(data, dep, showNA = "ifany")

Arguments

Value

Character vector of all category levels across all dep variables, or NULL if not applicable

Count maximum wrapped lines for a character vector

Description

Simulates text wrapping and counts the maximum number of lines any label wraps to, giving exact line counts instead of estimates.

Usage

count_max_wrapped_lines(labels, width)

Arguments

Value

Integer, maximum number of wrapped lines

Universal Output Function for Crowd Plots and Tables

Description

Automatically detects the appropriate output method based on the rendering context and input type. Simplifies workflows by providing a single function that works for both Quarto/knitr rendering (HTML tabsets/tables) and officer-based DOCX generation.

Usage

crowd_output(
  plot_list,
  path = "crowd_output.docx",
  force_format = c("auto", "html", "docx"),
  ...
)

Arguments

Details

Context Detection: The function uses getOption("knitr.in.progress") to detect if code is running within a knitr/Quarto rendering context:

• In knitr/Quarto → Generates HTML tabset via crowd_plots_as_tabset()

• Outside knitr → Writes DOCX file via crowd_plots_as_docx()

This allows the same code to work in multiple contexts:

• Quarto → HTML rendering

• Quarto → DOCX rendering (still uses HTML output in document)

• R script → Officer-based DOCX generation

Input Type Detection: The function automatically detects and handles different input types:

• ggplot2 objects → Uses crowd_plots_as_tabset() or crowd_plots_as_docx()

• mschart objects → Uses crowd_plots_as_docx()

• saros_officer_plots → Uses crowd_plots_as_docx()

• data.frame/tables → Uses crowd_tables_as_tabset() or writes to DOCX

Typical Workflow:

# In a Quarto document - works for both HTML and DOCX output formats
plots <- makeme(
  data = ex_survey,
  dep = b_1:b_3,
  crowd = c("target", "others"),
  mesos_var = "f_uni",
  mesos_group = "Uni of A",
  type = if (is_rendering()) "cat_plot_html" else "cat_plot_docx"
)
crowd_output(plots)  # Auto-detects context and renders appropriately

Value

• In knitr/Quarto context: Invisibly returns NULL (side effect: prints tabset markdown)

• Outside knitr context: Invisibly returns the DOCX file path

See Also

• crowd_plots_as_tabset() for HTML tabset generation

• crowd_plots_as_docx() for DOCX file creation

• is_rendering() for context detection helper

• makeme() for creating plots with crowd parameter

Examples

## Not run: 
# Example 1: In a Quarto document (auto-detects HTML context)
plots <- makeme(
  data = ex_survey,
  dep = b_1:b_3,
  crowd = c("target", "others"),
  mesos_var = "f_uni",
  mesos_group = "Uni of A",
  type = if (is_rendering()) "cat_plot_html" else "cat_plot_docx"
)
crowd_output(plots)

# Example 2: In an R script (auto-detects non-knitr context, writes DOCX)
plots <- makeme(
  data = ex_survey,
  dep = b_1:b_3,
  crowd = c("target", "others"),
  mesos_var = "f_uni",
  mesos_group = "Uni of A",
  type = "cat_plot_docx"
)
crowd_output(plots, path = "my_report.docx")

# Example 3: Force specific format
crowd_output(plots, force_format = "docx", path = "forced_output.docx")

## End(Not run)

Write Plots to Word Document (DOCX)

Description

High-level function to write a list of mschart plots directly to a Word document file, with optional section headings and chart labels. Simplifies the workflow for generating DOCX reports from Quarto/RMarkdown by handling all officer boilerplate internally.

Usage

crowd_plots_as_docx(
  plot_list,
  path,
  docx_template = NULL,
  heading_style = "heading 2",
  prefix_style = "Normal",
  add_dep_label_prefix = TRUE,
  chart_width = NULL,
  chart_height = NULL,
  extract_metadata = TRUE
)

Arguments

Details

This function provides a simple, single-call interface for writing Word documents from saros plots, ideal for Quarto workflows where you want:

• One QMD file → One DOCX file (no chapter merging)

• Minimal code in .qmd chunks (just makeme() + crowd_plots_as_docx())

• Automatic layout handling (page dimensions, chart sizing, heading styles)

Typical Workflow:

1. Generate mschart objects with makeme(..., type = "cat_plot_docx", docx_return_object = TRUE, crowd = ...)

2. Call crowd_plots_as_docx(plots, path = "report.docx") to write the file

Empty Plot Lists: If plot_list contains no valid mschart objects, the function:

• Issues a warning via cli::cli_warn()

• Creates an empty DOCX file at the specified path

• Returns the path invisibly

Value

Invisible file path to the created DOCX file.

See Also

• crowd_plots_as_officer() for obtaining a structured plot object

• crowd_plots_as_tabset() for the Quarto/HTML equivalent

• makeme() for creating plots with crowd parameter

• officer::read_docx() for manual DOCX assembly

Examples

## Not run: 
# Generate mschart objects for Word
plots <- makeme(
  data = ex_survey,
  dep = b_1:b_3,
  crowd = c("target", "others"),
  mesos_var = "f_uni",
  mesos_group = "Uni of A",
  type = "cat_plot_docx",
  docx_return_object = TRUE
)

# Write directly to a Word file
crowd_plots_as_docx(plots, path = "survey_results.docx")

# With custom template and styling
crowd_plots_as_docx(
  plots,
  path = "styled_report.docx",
  docx_template = "my_template.docx",
  heading_style = "Heading 1",
  prefix_style = "Body Text",
  chart_width = 6,
  chart_height = 4
)

# Without prefix labels
crowd_plots_as_docx(
  plots,
  path = "minimal_report.docx",
  add_dep_label_prefix = FALSE
)

## End(Not run)

Convert List of Plots to officer-Compatible Format

Description

Prepares a named list of mschart objects for insertion into a Word document using officer. Typically used with plots generated by makeme() with crowd parameter and type = "cat_plot_docx".

Usage

crowd_plots_as_officer(plot_list, extract_metadata = TRUE)

Arguments

Details

This function validates and structures plot objects for Word document assembly. Unlike crowd_plots_as_tabset() which generates Quarto markdown directly, this function returns a structured R object that can be used programmatically with officer to build Word documents.

Typical Workflow:

1. Generate mschart objects with makeme(..., type = "cat_plot_docx", docx_return_object = TRUE, crowd = ...)

2. Pass the list to crowd_plots_as_officer() for validation and structuring

3. Use the returned object to insert plots into a Word document via officer

Metadata Extraction: When extract_metadata = TRUE, the function extracts:

• dep_label_prefix: Main question text (from get_dep_label_prefix())

• name: Plot name from the list

• Additional attributes attached to the plot object

Value

A list with class "saros_officer_plots" containing:

• plots: Named list of mschart objects ready for officer insertion

• metadata: List of metadata for each plot (if extract_metadata = TRUE), including plot names, dep_label_prefix, and other attributes; NULL if extract_metadata = FALSE

• n_plots: Integer count of valid mschart objects after filtering

See Also

• crowd_plots_as_tabset() for the Quarto/HTML equivalent

• makeme() for creating plots with crowd parameter

• get_dep_label_prefix() for retrieving main question metadata

• mschart::body_add_chart() for inserting charts into Word documents

Examples

## Not run: 
# Generate mschart objects for Word
plots <- makeme(
  data = ex_survey,
  dep = b_1:b_3,
  crowd = c("target", "others"),
  mesos_var = "f_uni",
  mesos_group = "Uni of A",
  type = "cat_plot_docx",
  docx_return_object = TRUE
)

# Prepare for officer assembly
officer_plots <- crowd_plots_as_officer(plots)

# Use in officer workflow
library(officer)
doc <- read_docx()
for (plot_name in names(officer_plots$plots)) {
  doc <- doc |>
    body_add_par(plot_name, style = "heading 2") |>
    body_add_par(officer_plots$metadata[[plot_name]]$dep_label_prefix) |>
    mschart::body_add_chart(officer_plots$plots[[plot_name]])
}
print(doc, target = "output.docx")

## End(Not run)

Convert List of Plots to Quarto Tabset

Description

Creates a Quarto tabset from a named list of ggplot2 objects, typically generated by makeme() with crowd parameter. Each plot becomes a tab with automatic height calculation and optional download links.

Usage

crowd_plots_as_tabset(
  plot_list,
  plot_type = c("cat_plot_html", "int_plot_html", "auto"),
  save = FALSE,
  fig_height = NULL,
  fig_height_int_default = 6,
  pagebreak = c("never", "auto", "always")
)

Arguments

Details

This function is designed to be called within a Quarto document code chunk. It generates markdown that creates a tabset where each non-NULL plot in plot_list appears as a separate tab.

Height Calculation:

• For "cat_plot_html": Uses fig_height_h_barchart2() which accounts for number of variables, categories, and label lengths

• For "int_plot_html": Uses fig_height_int_default (simpler plots need less sophisticated calculation)

• For "auto": Detects type by checking for .category column (categorical) vs numeric statistics columns (interval)

Requirements:

• Must be run within knitr/Quarto context

• Plots should be created with makeme()

• Plot list should have meaningful names for tab labels

Value

Invisibly returns NULL. The function's purpose is its side effect of printing Quarto markdown that creates a tabset.

See Also

• makeme() for creating plots with crowd parameter

• fig_height_h_barchart2() for categorical plot height calculation

• get_fig_title_suffix_from_ggplot() for caption generation

• girafe() for interactive plot rendering

Examples

## Not run: 
# In a Quarto document
plots <- makeme(
  data = ex_survey,
  dep = b_1:b_3,
  crowd = c("target", "others"),
  mesos_var = "f_uni",
  mesos_group = "Uni of A"
)

# Create tabset with auto-detection
crowd_plots_as_tabset(plots)

# Create tabset for interval plots
int_plots <- makeme(
  data = ex_survey,
  dep = c_1:c_2,
  indep = x1_sex,
  type = "int_plot_html",
  crowd = c("target", "others"),
  mesos_var = "f_uni",
  mesos_group = "Uni of A"
)
crowd_plots_as_tabset(int_plots, plot_type = "int_plot_html")

# Without download links
crowd_plots_as_tabset(plots, save = FALSE)

# With manual height override
crowd_plots_as_tabset(plots, fig_height = 8)

## End(Not run)

Convert List of Tables to Quarto Tabset

Description

Creates a Quarto tabset from a named list of data frames, rendering each as a table in its own tab. Designed to be called within a Quarto document code chunk with results='asis'.

Usage

crowd_tables_as_tabset(
  tbl_list,
  table_fn = knitr::kable,
  pagebreak = c("never", "auto", "always")
)

Arguments

Details

This function outputs raw Quarto markdown (level-5 headings) interleaved with printed tables. The enclosing chunk should use the Quarto tabset panel layout and results: asis.

Value

Called for its side effects (printing tabset markdown and tables). Returns NULL invisibly.

See Also

crowd_plots_as_tabset() for the plot equivalent.

Examples

## Not run: 
tbl_list <- list(
  "Group A" = head(mtcars),
  "Group B" = tail(mtcars)
)
crowd_tables_as_tabset(tbl_list)

# Use gt::gt instead
crowd_tables_as_tabset(tbl_list, table_fn = gt::gt)

## End(Not run)

Detect Ghostscript Binary on System PATH

Description

Detect Ghostscript Binary on System PATH

Usage

detect_ghostscript()

Value

String with the Ghostscript command name, or NULL if not found.

Detect Variable Types for Dependent and Independent Variables

Description

Internal helper function that examines the class of variables in the subset data to determine their types (factor, numeric, character, etc.).

Usage

detect_variable_types(subset_data, dep_crwd, indep_crwd)

Arguments

Value

List with two elements:

• dep: Character vector of classes for dependent variables

• indep: Character vector of classes for independent variables (empty if none)

Determine variable column basis

Description

Consistent logic for determining whether to use .variable_label or .variable_name

Usage

determine_variable_basis(data_summary)

Arguments

Value

String indicating column to use as basis

Escape a String for Literal Use in a Regular Expression

Description

Escape a String for Literal Use in a Regular Expression

Usage

escape_for_regex(x)

Arguments

Value

String with regex metacharacters escaped.

Escape Markdown Special Characters

Description

Escape Markdown Special Characters

Usage

escape_markdown(text)

Arguments

Value

Escaped character string safe for markdown link text

Escape Markdown Link Path

Description

Escape Markdown Link Path

Usage

escape_markdown_link(path)

Arguments

Value

Escaped path safe for markdown link URLs

Evaluate Variable Selection

Description

Internal helper function that evaluates tidyselect expressions for dependent and independent variables, returning their column positions in the data frame.

Usage

evaluate_variable_selection(data, dep, indep)

Arguments

Value

A list with two named elements:

• dep_pos: Named integer vector of column positions for dependent variables

• indep_pos: Named integer vector of column positions for independent variables

ex_survey: Mockup dataset of a survey.

Description

A dataset containing fake respondents' answers to survey questions. The first two, x_sex and x_human, are intended to be independent variables, whereas the remaining are dependent. The underscore _ in variable names separates item groups (prefix) from items (suffix) (i.e. a_1-a_9 => a + 1-9), whereas ' - ' separates the same for labels. The latter corresponds with the default in SurveyXact.

Usage

ex_survey

Format

A data frame with 100 rows and 29 variables:

x1_sex

Gender

x2_human

Is respondent human?

x3_nationality

Where is the respondent born?

a_1

Do you consent to the following? - Agreement #1

a_2

Do you consent to the following? - Agreement #2

a_3

Do you consent to the following? - Agreement #3

a_4

Do you consent to the following? - Agreement #4

a_5

Do you consent to the following? - Agreement #5

a_6

Do you consent to the following? - Agreement #6

a_7

Do you consent to the following? - Agreement #7

a_8

Do you consent to the following? - Agreement #8

a_9

Do you consent to the following? - Agreement #9

b_1

How much do you like living in - Beijing

b_2

How much do you like living in - Brussels

b_3

How much do you like living in - Budapest

c_1

How many years of experience do you have in - Company A

c_2

How many years of experience do you have in - Company B

d_1

Rate your degree of confidence doing the following - Driving

d_2

Rate your degree of confidence doing the following - Drinking

d_3

Rate your degree of confidence doing the following - Driving

d_4

Rate your degree of confidence doing the following - Dancing

e_1

How often do you do the following? - Eat

e_2

How often do you do the following? - Eavesdrop

e_3

How often do you do the following? - Exercise

e_4

How often do you do the following? - Encourage someone whom you have only recently met and who struggles with simple tasks that they cannot achieve by themselves

p_1

To what extent do you agree or disagree to the following policies - Red Party

p_2

To what extent do you agree or disagree to the following policies - Green Party

p_3

To what extent do you agree or disagree to the following policies - Yellow Party

p_4

To what extent do you agree or disagree to the following policies - Blue Party

f_uni

Which of the following universities would you prefer to study at?

open_comments

Do you have any comments to the survey?

resp_status

Response status

Extract Document Title from File

Description

Internal helper to extract title metadata from DOCX, PPTX, and PDF files.

Usage

extract_document_title(filepath)

Arguments

Value

Character string with the document title, or filename if extraction fails.

Extract Title from DOCX File

Description

Extract Title from DOCX File

Usage

extract_docx_title(filepath)

Arguments

Value

Character string with title or NULL

Extract plotting dimensions from ggplot theme

Description

Extracts the base font size and legend position from a ggplot2 object's complete theme (global theme + plot-level overrides) to improve automatic height estimation.

Usage

extract_ggplot_theme_info(plot_obj)

Arguments

Value

A list with components:

base_size

Numeric. The base text size in points from the theme.

legend_adds_height

Logical. TRUE when the legend is positioned at the bottom or top (adding vertical space), FALSE when at the sides, inside the panel, or hidden.

Extract Title from PDF File

Description

Extract Title from PDF File

Usage

extract_pdf_title(filepath)

Arguments

Value

Character string with title or NULL

Extract Title from PPTX File

Description

Extract Title from PPTX File

Usage

extract_pptx_title(filepath)

Arguments

Value

Character string with title or NULL

Estimate figure height for a horizontal bar chart

Description

This function estimates the height of a figure for a horizontal bar chart based on several parameters including the number of dependent and independent variables, number of categories, maximum characters in the labels, and legend properties.

Usage

fig_height_h_barchart(
  n_y,
  n_cats_y,
  max_chars_labels_y = 20,
  max_chars_cats_y = 20,
  n_x = NULL,
  n_cats_x = NULL,
  max_chars_labels_x = NULL,
  max_chars_cats_x = NULL,
  freq = FALSE,
  x_axis_label_width = 20,
  strip_width = 20,
  strip_angle = 0,
  main_font_size = 7,
  legend_location = c("plot", "panel"),
  n_legend_lines = NULL,
  legend_key_chars_equivalence = 5,
  multiplier_per_horizontal_line = 1,
  multiplier_per_vertical_letter = 1,
  multiplier_per_facet = 1,
  multiplier_per_bar = 1,
  multiplier_per_legend_line = 1,
  multiplier_per_plot = 1,
  fixed_constant = 0,
  margin_in_cm = 0,
  figure_width_in_cm = 14,
  max = 12,
  min = 2,
  hide_axis_text_if_single_variable = FALSE,
  multiplier_hide_axis_single_var = 0.6,
  add_n_to_dep_label = FALSE,
  add_n_to_indep_label = FALSE,
  showNA = c("ifany", "never", "always")
)

Arguments

Value

Numeric value representing the estimated height of the figure.

Examples

fig_height_h_barchart(
  n_y = 5,
  n_cats_y = 3,
  max_chars_labels_y = 20,
  max_chars_cats_y = 8,
  n_x = 1,
  n_cats_x = 4,
  max_chars_labels_x = 12,
  freq = FALSE,
  x_axis_label_width = 20,
  strip_angle = 0,
  main_font_size = 8,
  legend_location = "panel",
  n_legend_lines = 2,
  legend_key_chars_equivalence = 5,
  multiplier_per_horizontal_line = 1,
  multiplier_per_vertical_letter = .15,
  multiplier_per_facet = .95,
  multiplier_per_legend_line = 1.5,
  figure_width_in_cm = 16
)

Estimate figure height for a horizontal bar chart

Description

Taking an object from makeme(), this function estimates the height of a figure for a horizontal bar chart. Works with both ggplot2 and mschart objects.

Usage

fig_height_h_barchart2(plot_obj, ...)

fig_height_h_barchart2.ggplot(
  plot_obj,
  main_font_size = 7,
  strip_angle = 0,
  freq = FALSE,
  x_axis_label_width = 20,
  strip_width = 20,
  legend_location = c("plot", "panel"),
  n_legend_lines = NULL,
  showNA = c("ifany", "never", "always"),
  legend_key_chars_equivalence = 5,
  multiplier_per_horizontal_line = NULL,
  multiplier_per_vertical_letter = 1,
  multiplier_per_facet = 1,
  multiplier_per_legend_line = 1,
  fixed_constant = 0,
  figure_width_in_cm = 14,
  margin_in_cm = 0,
  max = 12,
  min = 1,
  multiplier_hide_axis_single_var = 0.6
)

fig_height_h_barchart2.ms_chart(
  plot_obj,
  main_font_size = 7,
  strip_angle = 0,
  freq = FALSE,
  x_axis_label_width = 20,
  strip_width = 20,
  legend_location = c("plot", "panel"),
  n_legend_lines = NULL,
  showNA = c("ifany", "never", "always"),
  legend_key_chars_equivalence = 5,
  multiplier_per_horizontal_line = NULL,
  multiplier_per_vertical_letter = 1,
  multiplier_per_facet = 1,
  multiplier_per_legend_line = 1,
  fixed_constant = 0,
  figure_width_in_cm = 14,
  margin_in_cm = 0,
  max = 12,
  min = 1,
  multiplier_hide_axis_single_var = 0.6
)

fig_height_h_barchart2.default(plot_obj, ...)

Arguments

Value

Numeric value representing the estimated height of the figure.

Examples

# With ggplot2 (cat_plot_html)
fig_height_h_barchart2(makeme(data = ex_survey, dep = b_1:b_2, indep = x1_sex))

# With mschart (cat_plot_docx)
## Not run: 
fig_height_h_barchart2(
  makeme(data = ex_survey, dep = b_1:b_2,
         type = "cat_plot_docx", docx_return_object = TRUE)
)

## End(Not run)

Find a Matching DOCX File for a PDF (Case-Insensitive)

Description

Looks in the same directory as the PDF for a .docx file with the same base name, matching case-insensitively on the extension.

Usage

find_matching_docx(pdf_path)

Arguments

Value

Path to the matching DOCX file, or NULL if not found.

Generate Appropriate Data Summary Based on Variable Types

Description

Internal helper function that routes to the appropriate data summarization function based on the detected variable types (categorical vs continuous).

Usage

generate_data_summary(
  variable_types,
  subset_data,
  dep_crwd,
  indep_crwd,
  args,
  full_category_levels = NULL,
  ...
)

Arguments

Value

Data summary object (type depends on variable types):

• For integer/numeric dep + factor/character indep: calls summarize_int_cat_data()

• For factor/character dep: calls summarize_cat_cat_data()

• For mixed types: throws error

Provide A Colour Set for A Number of Requested Colours

Description

Possibly using colour_palette_nominal if available. If not sufficient, uses a set palette from RColorBrewer.

Usage

get_colour_palette(
  data,
  col_pos,
  colour_palette_nominal = NULL,
  colour_palette_ordinal = NULL,
  colour_na = NULL,
  categories_treated_as_na = NULL,
  call = rlang::caller_env()
)

Arguments

Value

A colour set as character vector, where NA has the colour_na, and the rest are taken from colour_palette_nominal if available.

Provide A Colour Set for A Number of Requested Colours

Description

Possibly using colour_palette_nominal if available. If not sufficient, uses a set palette from RColorBrewer.

Usage

get_colour_set(
  x,
  common_data_type = "factor",
  colour_palette_nominal = NULL,
  colour_palette_ordinal = NULL,
  colour_na = NULL,
  colour_2nd_binary_cat = NULL,
  ordinal = FALSE,
  categories_treated_as_na = NULL,
  call = rlang::caller_env()
)

Arguments

Value

A colour set as character vector, where NA has the colour_na, and the rest are taken from colour_palette_nominal if available.

Determine display column based on data availability

Description

Checks if .variable_label column exists and has non-NA values to determine whether to use .variable_label or .variable_name for display.

Usage

get_data_display_column(data)

Arguments

Value

Character string indicating which column to use

Get Valid Data Labels for Figures and Tables

Description

Get Valid Data Labels for Figures and Tables

Usage

get_data_label_opts()

Value

Character vector

Determine display column for dependent variables in int_plot_html

Description

Checks if the number of dep variables matches the number of labels to determine whether to use .variable_label or .variable_name for display.

Usage

get_dep_display_column(dep_count, dep_labels)

Arguments

Value

Character string indicating which column to use

Retrieve the dep label prefix from a saros output object

Description

Retrieves the "dep_label_prefix" attribute that saros attaches to every object returned by makeme() / ⁠make_content.*()⁠. This is the main question text — the shared label prefix of all dependent variables used to produce the object.

Usage

get_dep_label_prefix(obj)

Arguments

Details

Storage location by class:

• ggplot / gg and ms_barchart: attribute is stored on obj$data (when obj$data is a data.frame) so that it survives further + operations. This function reads from obj$data first for both classes.

• data.frame and other objects: attribute stored directly on obj.

Value

A character scalar: the dep label prefix if present and non-empty, otherwise "".

Examples

p <- makeme(data = ex_survey, dep = b_1:b_3)
get_dep_label_prefix(p)

Generate Figure Title Suffix with N Range and Optional Download Links

Description

Creates a formatted suffix for figure titles that includes the sample size (N) range from a ggplot object. Optionally generates markdown download links for both the plot data and the plot image.

Usage

get_fig_title_suffix_from_ggplot(
  plot,
  save = FALSE,
  n_equals_string = "N = ",
  folder = NULL,
  file_prefix = NULL,
  file_suffixes = c(".csv", ".png"),
  link_prefixes = c("[CSV](", "[PNG]("),
  save_fns = NULL,
  sep = ", "
)

Arguments

Details

This function is particularly useful for adding informative captions to plots in reports. The N range is calculated using n_range2(), which extracts the sample size from the plot data. When save = TRUE, the function creates downloadable files using make_link():

• Plot data as CSV (via utils::write.csv)

• Plot image as PNG (via ggsaver())

The function returns an AsIs object to prevent automatic character escaping in markdown/HTML contexts.

Value

An AsIs object (using I()) containing a character string with:

• Sample size range formatted as "{n_equals_string}{range}"

• If save = TRUE: additional download links for plot data and image, separated by sep

• Empty string if plot is not a valid ggplot object or has no data

See Also

• n_range2() for extracting N range from ggplot objects

• make_link() for creating download links

• ggsaver() for saving ggplot objects

Examples

# Create a sample plot
plot <- makeme(data = ex_survey, dep = b_1:b_3)

# Get just the N range text
get_fig_title_suffix_from_ggplot(plot)

# Custom N prefix
get_fig_title_suffix_from_ggplot(plot, n_equals_string = "Sample size: ")

## Not run: 
# Generate with download links (saves files to disk)
get_fig_title_suffix_from_ggplot(plot, save = TRUE)

# Custom separator and link prefix
get_fig_title_suffix_from_ggplot(
  plot,
  save = TRUE,
  sep = " | ",
  link_prefix = "[Download PNG]("
)

## End(Not run)

Extract Fill Levels from ggplot Object

Description

Evaluates the fill aesthetic mapping in the context of the plot data to extract fill levels. Handles both simple column references (e.g., fill = cyl) and expressions (e.g., fill = factor(cyl)).

Usage

get_fill_levels(ggobj)

Arguments

Value

Character vector of fill levels, or NULL if no fill mapping exists

Get the name of the independent variable column

Description

Get the name of the independent variable column

Usage

get_indep_col_name(data)

Arguments

Value

Character string with column name, or NULL if not found

Get independent variable labels

Description

Process independent variable labels with consistent logic across table functions

Usage

get_indep_labels(dots)

Arguments

Value

Character vector of processed labels

Get all registered options for the type-argument in the makeme-function

Description

The makeme()-function take for the argument type one of several strings to indicate content type and output type. This function collects all registered alternatives. Extensions are possible, see further below.

Built-in types:

Whereas the names of the types can be arbitrary, a pattern is pursued in the built-in types. Prefix indicates what dependent data type it is intended for

"cat"

Categorical (ordinal and nominal) data.

"chr"

Open ended responses and other character data.

"int"

Integer and numeric data.

Suffix indicates output

"html"

Interactive html, usually what you want for Quarto, as Quarto can usually convert to other formats when needed

"docx"

However, Quarto's and Pandoc's docx-support is currently still limited, for instance as vector graphics are converted to raster graphics for docx output. Hence, saros offers some types that outputs into MS Chart vector graphics. Note that this is experimental and not actively developed.

"pdf"

This is basically just a shortcut for "html" with interactive=FALSE

Usage

get_makeme_types()

Value

Character vector

Further details about some of the built-in types:

"cat_plot_"

A Likert style plot for groups of categorical variables sharing the same categories.

"cat_table_"

A Likert style table.

"chr_table_"

A single-column table listing unique open ended responses.

"sigtest_table_"

See below

sigtest_table_\*: Make Table with All Combinations of Univariate/Bivariate Significance Tests Based on Variable Types

Although there are hundreds of significance tests for associations between two variables, depending upon the distributions, variables types and assumptions, most fall into a smaller set of popular tests. This function runs for all combinations of dependent and independent variables in data, with a suitable test (but not the only possible) for the combination. Also supports univariate tests, where the assumptions are that of a mean of zero for continuous variables or all equal proportions for binary/categorical.

This function does not allow any adjustments - use the original underlying functions for that (chisq.test, t.test, etc.)

Expanding with custom types

makeme() calls the generic make_content(), which uses the S3-method system to dispatch to the relevant method (i.e., paste0("make_content.", type)). makeme forwards all its arguments to make_content, with the following exceptions:

1. dep and indep are converted from dplyr::dplyr_tidy_select()-syntax to simple character vectors, for simplifying building your own functions.

2. data_summary is attached, which contains many useful pieces of info for many (categorical) displays.

Examples

get_makeme_types()

Helper function to extract raw variable labels from the data

Description

Helper function to extract raw variable labels from the data

Usage

get_raw_labels(data, col_pos = NULL, return_as_list = FALSE)

Arguments

Value

List or character vector

Get standard column renaming function

Description

Standardized column renaming logic for table functions

Usage

get_standard_column_renamer(
  main_question = "",
  use_header = FALSE,
  column_mappings = NULL
)

Arguments

Value

Function for renaming columns

Get target categories for positional sorting

Description

Uses subset_vector to determine which categories to include based on positional methods like .top, .bottom, .upper, .lower, etc.

Usage

get_target_categories(data, method)

Arguments

Value

Character vector of target category names

Wrapper Function for ggplot2::ggsave() with Palette Support

Description

Saves ggplot2 objects with automatic palette application from global settings. Inherits palette settings from girafe() global options, ensuring saved plots match the appearance of interactive plots.

Usage

ggsaver(
  plot,
  filename,
  palette_codes = NULL,
  priority_palette_codes = NULL,
  label_wrap_width = 80,
  ncol = NULL,
  byrow = TRUE,
  ...
)

Arguments

Details

This function extends ggplot2::ggsave() by applying colour palettes before saving, ensuring consistency between interactive plots (via girafe()) and saved static images. Palette settings are inherited from global settings set via global_settings_set() for the "girafe" function.

If palette_codes is provided (either directly or via global settings), the function applies the same palette transformation that girafe() uses for interactive plots.

Value

No return value, called for side effects (saves plot to file)

See Also

• girafe() for interactive plots with palette support

• global_settings_set() for setting default palettes

• ggplot2::ggsave() for the underlying save function

Examples

library(ggplot2)
my_plot <- ggplot(data=mtcars, aes(x=hp, y=mpg, fill=factor(cyl))) + geom_point()

## Not run: 
# Save with default settings
ggsaver(my_plot, tempfile(fileext = ".png"))

# Set global palette and save
global_settings_set(
  fn_name = "girafe",
  new = list(palette_codes = list(c("red", "blue", "green")))
)
ggsaver(my_plot, tempfile(fileext = ".png"))

# Override global palette for specific save
ggsaver(
  my_plot,
  tempfile(fileext = ".png"),
  palette_codes = list(c("purple", "orange", "yellow"))
)

## End(Not run)

Pull global plotting settings before displaying plot

Description

This function extends ggiraph::girafe by allowing colour palettes to be globally specified.

Usage

girafe(
  ggobj,
  ...,
  char_limit = 200,
  label_wrap_width = 80,
  interactive = TRUE,
  palette_codes = NULL,
  priority_palette_codes = NULL,
  ncol = NULL,
  byrow = TRUE,
  colour_2nd_binary_cat = NULL,
  checked = NULL,
  not_checked = NULL,
  width_svg = NULL,
  height_svg = NULL,
  pointsize = 12
)

Arguments

Value

If interactive, only side-effect of generating ggiraph-plot. If interactive=FALSE, returns modified ggobj.

Examples

plot <- makeme(data = ex_survey, dep = b_1)
girafe(plot)

Get Global Options for saros-functions

Description

Get Global Options for saros-functions

Usage

global_settings_get(fn_name = "makeme")

Arguments

Value

List with options in R

Examples

global_settings_get()

Reset Global Options for saros-functions

Description

Reset Global Options for saros-functions

Usage

global_settings_reset(fn_name = "makeme", quiet = FALSE)

Arguments

Value

Invisibly returned list of old and new values.

Examples

global_settings_reset()

Get Global Options for saros-functions

Description

Get Global Options for saros-functions

Usage

global_settings_set(
  new,
  fn_name = "makeme",
  quiet = FALSE,
  null_deletes = FALSE
)

Arguments

Value

Invisibly returned list of old and new values.

Examples

global_settings_set(new=list(digits=2))

Identify Suitable Font Given Background Hex Colour

Description

Uses the W3C relative luminance formula (WCAG 2.0) to determine contrast.

Usage

hex_bw(hex_code, na_colour = "#ffffff")

Arguments

Value

Colours in hex-format, either black or white.

Validate and Initialize Arguments

Description

Internal helper function that finalizes the arguments list by adding resolved variable names and normalizing multi-value arguments.

Usage

initialize_arguments(data, dep_pos, indep_pos, args)

Arguments

Value

Modified args list with additional elements:

• data: The input data frame

• dep: Character vector of dependent variable names (from dep_pos)

• indep: Character vector of independent variable names (from indep_pos)

• Normalized single-value arguments (showNA, data_label, type)

Initialize Crowd-Based Filtering Data Structures

Description

Internal helper function that sets up the data structures needed for crowd-based filtering and processing of variables and categories.

Usage

initialize_crowd_filtering(crowd, args)

Arguments

Details

For each crowd, this function calls keep_cols() and keep_indep_cats() to determine which variables and categories should be retained based on the various hiding criteria (NA values, sample sizes, etc.).

Value

List with three named elements:

• kept_cols_list: Named list of kept column information for each crowd

• omitted_cols_list: Named list of omitted variables for each crowd

• kept_indep_cats_list: Named list of kept independent categories for each crowd

Insert Text from a Data Frame by Chunk Name

Description

Looks up a text string from a data frame based on a chunk name and position (before/after). Optionally expands knitr templating syntax ({{...}}) found in the text.

Usage

insert_text(data, chunk, before = TRUE, error_on_empty = NULL, enabled = TRUE)

Arguments

Details

The function filters data for rows matching the given chunk and before values. If exactly one row matches, its text column is returned. If the text contains knitr templating delimiters (⁠{{⁠), it is expanded with knitr::knit_expand().

Value

An I()-wrapped character string. If no match is found and error_on_empty is NULL, an empty AsIs character vector.

Examples

## Not run: 
texts <- data.frame(
  chunk = c("intro", "intro"),
  before = c(TRUE, FALSE),
  text = c("Before the chunk.", "After the chunk.")
)
insert_text(texts, "intro", before = TRUE)
insert_text(texts, "intro", before = FALSE)

## End(Not run)

Are All Colours in Vector Valid Colours

Description

As title says. From: (https://stackoverflow.com/a/13290832/3315962)

Usage

is_colour(x)

Arguments

Value

Logical, or error.

Check if ⁠\\newpage⁠ emission should be suppressed

Description

Returns TRUE when the current rendering context should not emit ⁠\\newpage⁠ between content blocks. This covers HTML-based formats (where page breaks are meaningless), Typst (where ⁠\\newpage⁠ is converted to ⁠#pagebreak()⁠ which errors inside containers), and officer contexts (where page breaks are handled differently).

Usage

is_html_output_or_officer()

Details

Uses knitr::is_html_output() when knitr is in progress (covers revealjs, slidy, and other HTML-based Pandoc formats). Also returns TRUE for Typst, since ⁠#pagebreak()⁠ fails inside containers and the Quarto pagebreak shortcode lacks native Typst support. Outside of knitr (officer context), returns TRUE so that ⁠\\newpage⁠ is not emitted by default.

Value

Logical scalar.

Detect if data is from int_plot_html

Description

Checks if a data frame has the structure expected from int_plot_html output, which uses .value column instead of .category column.

Usage

is_int_plot_html(data)

Arguments

Value

Logical indicating if this is int_plot_html format

Detect if Running in knitr/Quarto Rendering Context

Description

Helper function to detect if code is running within a knitr/Quarto rendering context. Useful for creating unified code that works in both interactive R sessions and when rendering documents.

Usage

is_rendering()

Details

This function checks getOption("knitr.in.progress") which is set by knitr during document rendering. This works for:

• Quarto documents (all output formats: HTML, DOCX, PDF, etc.)

• R Markdown documents

• Any knitr-based rendering systems

Returns FALSE when running in:

• Interactive R sessions (RStudio console, R terminal)

• R scripts executed outside knitr

• Shiny applications (unless explicitly using knitr)

Value

Logical. TRUE if rendering a document, FALSE otherwise.

See Also

crowd_output() for automatic context-aware output generation

Examples

# Check if rendering a document
if (is_rendering()) {
  message("Rendering a document with knitr/Quarto")
} else {
  message("Running in regular R session")
}

# Use for conditional logic
plot_type <- if (is_rendering()) "cat_plot_html" else "cat_plot_docx"

Is x A String?

Description

Returns TRUE if object is a character of length 1.

Usage

is_string(x)

Arguments

Value

Logical value.

Method for Creating Saros Contents

Description

Takes the same arguments as makeme, except that dep and indep in make_content are character vectors, for ease of user-customized function programming.

Usage

make_content(type, ...)

Arguments

Value

The returned object class depends on the type. type="*_table_html" always returns a tibble. type="*_plot_html" always returns a ggplot. type="*_docx" always returns a rdocx object if path=NULL, or has side-effect of writing docx file to disk if path is set.

Create Markdown Links to Files with Document Titles

Description

Scans a folder for files matching a pattern and generates a markdown list with links to each file. The link text is extracted from the document's title metadata (for DOCX, PPTX, PDF files) or uses the filename as fallback.

Usage

make_file_links(
  folder = ".",
  pattern = "",
  bullet_style = "-",
  recurse = FALSE,
  relative_links = TRUE
)

Arguments

Details

The function attempts to extract document titles from file metadata:

• DOCX files: Extracts title from document properties (requires officer package)

• PPTX files: Extracts title from presentation properties (requires officer package)

• PDF files: Extracts title from PDF metadata (requires pdftools package)

If title extraction fails or the file type is unsupported, the filename (without extension) is used as the link text.

The function preserves the order of files as returned by fs::dir_ls(), which typically sorts alphabetically.

Value

A character string containing a markdown-formatted list of links. Each line contains a bullet point and a link with the document title as link text. Returns empty string if no files found.

Optional Packages

The pdftools package is optional (in Suggests) and only needed for PDF title extraction.

Examples

## Not run: 
# Create links to all PowerPoint files in a folder
make_file_links(folder = "presentations", pattern = "\\.pptx$")

# Create links to PDF reports with numbered list
make_file_links(
  folder = "reports",
  pattern = "^report_.*\\.pdf$",
  bullet_style = "1."
)

# Recursively find all Office documents
make_file_links(
  folder = "documents",
  pattern = "\\.(docx|pptx)$",
  recurse = TRUE
)

## End(Not run)

Save data to a file and return a Markdown link

Description

The file is automatically named by a hash of the object, removing the need to come up with unique file names inside a Quarto report. This has the added benefit of reducing storage needs if the objects needing linking to are identical, and all are stored in the same folder. It also allows the user to download multiple files without worrying about accidentally overwriting them.

Usage

make_link(
  data,
  folder = NULL,
  file_prefix = NULL,
  file_suffix = ".csv",
  save_fn = utils::write.csv,
  link_prefix = "[download figure data](",
  link_suffix = ")",
  ...
)

Arguments

Value

String.

Examples

make_link(mtcars, folder = tempdir())

Save data to a file and return a Markdown link

Description

The file is automatically named by a hash of the object, removing the need to come up with unique file names inside a Quarto report. This has the added benefit of reducing storage needs if the objects needing linking to are identical, and all are stored in the same folder. It also allows the user to download multiple files without worrying about accidentally overwriting them.

Usage

## Default S3 method:
make_link(
  data,
  ...,
  folder = NULL,
  file_prefix = NULL,
  file_suffix = ".csv",
  save_fn = utils::write.csv,
  link_prefix = "[download figure data](",
  link_suffix = ")"
)

Arguments

Value

String.

Examples

make_link(mtcars, folder = tempdir())

Save data to a file and return a Markdown link

Description

The file is automatically named by a hash of the object, removing the need to come up with unique file names inside a Quarto report. This has the added benefit of reducing storage needs if the objects needing linking to are identical, and all are stored in the same folder. It also allows the user to download multiple files without worrying about accidentally overwriting them.

Usage

## S3 method for class 'list'
make_link(
  data,
  ...,
  folder = NULL,
  file_prefix = NULL,
  file_suffix = ".csv",
  save_fn = utils::write.csv,
  link_prefix = "[download figure data](",
  link_suffix = ")",
  separator_list_items = ". "
)

Arguments

Embed Interactive Plot of Various Kinds Using Tidyselect Syntax

Description

This function allows embedding of interactive or static plots based on various types of data using tidyselect syntax for variable selection.

Usage

makeme(
  data,
  dep = tidyselect::everything(),
  indep = NULL,
  type = c("auto", "cat_plot_html", "int_plot_html", "cat_table_html", "int_table_html",
    "sigtest_table_html", "cat_plot_docx", "int_plot_docx", "cat_table_docx",
    "chr_table_docx"),
  ...,
  require_common_categories = TRUE,
  crowd = c("all"),
  mesos_var = NULL,
  mesos_group = NULL,
  simplify_output = TRUE,
  hide_for_crowd_if_all_na = TRUE,
  hide_for_crowd_if_valid_n_below = 0,
  hide_for_crowd_if_category_k_below = 2,
  hide_for_crowd_if_category_n_below = 0,
  hide_for_crowd_if_cell_n_below = 0,
  hide_for_all_crowds_if_hidden_for_crowd = NULL,
  hide_indep_cat_for_all_crowds_if_hidden_for_crowd = FALSE,
  add_n_to_dep_label = FALSE,
  add_n_to_indep_label = FALSE,
  add_n_to_label = FALSE,
  add_n_to_category = FALSE,
  totals = FALSE,
  categories_treated_as_na = NULL,
  label_separator = " - ",
  error_on_duplicates = TRUE,
  showNA = c("ifany", "always", "never"),
  data_label = c("percentage_bare", "percentage", "proportion", "count", "mean",
    "median"),
  data_label_position = c("center", "bottom", "top", "above"),
  html_interactive = TRUE,
  hide_axis_text_if_single_variable = TRUE,
  hide_label_if_prop_below = 0.01,
  inverse = FALSE,
  vertical = FALSE,
  digits = 0,
  data_label_decimal_symbol = ".",
  x_axis_label_width = 25,
  strip_width = 25,
  sort_dep_by = ".variable_position",
  sort_indep_by = ".factor_order",
  sort_by = NULL,
  descend = TRUE,
  descend_indep = FALSE,
  labels_always_at_top = NULL,
  labels_always_at_bottom = NULL,
  table_wide = TRUE,
  table_main_question_as_header = FALSE,
  n_categories_limit = 12,
  translations = list(last_sep = " and ", table_heading_N = "Total (N)",
    table_heading_data_label = "%", add_n_to_dep_label_prefix = " (N = ",
    add_n_to_dep_label_suffix = ")", add_n_to_indep_label_prefix = " (N = ",
    add_n_to_indep_label_suffix = ")", add_n_to_label_prefix = " (N = ",
    add_n_to_label_suffix = ")", add_n_to_category_prefix = " (N = [",
    add_n_to_category_infix = ",", add_n_to_category_suffix = "])", by_total =
    "Everyone", sigtest_variable_header_1 = "Var 1", sigtest_variable_header_2 = "Var 2",
    crowd_all = "All", 
     crowd_target = "Target", crowd_others = "Others"),
  plot_height = 15,
  colour_palette = NULL,
  colour_2nd_binary_cat = "#ffffff",
  colour_na = "grey",
  label_font_size = 9,
  main_font_size = 9,
  strip_font_size = 6,
  legend_font_size = 6,
  font_family = "sans",
  path = NULL,
  docx_template = NULL,
  docx_return_object = TRUE
)

Arguments

Value

ggplot-object, optionally an extended ggplot object with ggiraph features.

Examples

makeme(
  data = ex_survey,
  dep = b_1:b_2
)
makeme(
  data = ex_survey,
  dep = b_1:b_3, indep = c(x1_sex, x2_human),
  type = "sigtest_table_html"
)
makeme(
  data = ex_survey,
  dep = p_1:p_4, indep = x2_human,
  type = "cat_table_html"
)
makeme(
  data = ex_survey,
  dep = c_1:c_2, indep = x1_sex,
  type = "int_table_html"
)
makeme(
  data = ex_survey,
  dep = b_1:b_2,
  crowd = c("target", "others"),
  mesos_var = "f_uni",
  mesos_group = "Uni of A"
)

Provides a range (or single value) for N in data, given dep and indep

Description

Provides a range (or single value) for N in data, given dep and indep

Usage

n_range(
  data,
  dep,
  indep = NULL,
  mesos_var = NULL,
  mesos_group = NULL,
  glue_template_1 = "{n}",
  glue_template_2 = "[{n[1]}-{n[2]}]"
)

Arguments

Value

String.

Examples

n_range(data = ex_survey, dep = b_1:b_3, indep = x1_sex)

Provides a range (or single value) for N in a plot object from makeme()

Description

Takes a plot object from makeme() and returns the sample size (N) range as a formatted string. Works with both ggplot2 objects and mschart objects.

Usage

n_range2(plot_obj, ...)

n_range2.ggplot(
  plot_obj,
  glue_template_1 = "{n}",
  glue_template_2 = "[{n[1]}-{n[2]}]"
)

n_range2.ms_chart(
  plot_obj,
  glue_template_1 = "{n}",
  glue_template_2 = "[{n[1]}-{n[2]}]"
)

n_range2.default(plot_obj, ...)

Arguments

Value

String.

Examples

# With ggplot2 (cat_plot_html)
n_range2(makeme(data = ex_survey, dep = b_1:b_3))

# With mschart (cat_plot_docx)
## Not run: 
n_range2(
  makeme(data = ex_survey, dep = b_1:b_3,
         type = "cat_plot_docx", docx_return_object = TRUE)
)

## End(Not run)

Obtain range of N for a given data set and other settings.

Description

Obtain range of N for a given data set and other settings.

Usage

n_rng(
  data,
  dep,
  indep = NULL,
  crowd = "all",
  mesos_var = NULL,
  mesos_group = NULL,
  glue_template_1 = "{n}",
  glue_template_2 = "[{n[1]}-{n[2]}]"
)

Arguments

Value

Always a string.

Normalize Multi-Choice Arguments to Single Values

Description

Internal helper function that ensures makeme arguments that might be vectors are normalized to single values by taking the first element.

Usage

normalize_makeme_arguments(args, data = NULL)

Arguments

Value

Modified args list with normalized single-value arguments:

• showNA: First element of showNA vector

• data_label: First element of data_label vector

• data_label_position: First element of data_label_position vector

• type: Auto-detected type if "auto", otherwise first element of evaluated type expression

Detect the Current Output Format

Description

Returns the output format of the current rendering context. When called inside a Quarto/knitr document, delegates to knitr::pandoc_to(). When called outside of Quarto (e.g. in an officer-based script), returns "officer".

Usage

output_format()

Value

A character string: "html", "docx", "typst", "officer", or another format reported by knitr::pandoc_to().

Examples

## Not run: 
output_format()

## End(Not run)

Post-process Makeme Data (Legacy)

Description

Legacy function that combines both factor level processing and binary category color processing. Use the individual functions for new code.

Usage

post_process_makeme_data(
  data,
  indep = NULL,
  showNA = "never",
  colour_2nd_binary_cat = NULL
)

Arguments

Value

Modified data frame

Print method for saros_officer_plots

Description

Print method for saros_officer_plots

Usage

## S3 method for class 'saros_officer_plots'
print(x, ...)

Arguments

Value

Invisibly returns x

Process All Crowds and Generate Output

Description

Internal helper function that iterates through all crowd identifiers and generates the appropriate output for each crowd.

Usage

process_all_crowds(
  args,
  omitted_cols_list,
  kept_indep_cats_list,
  data,
  mesos_var,
  mesos_group,
  ...
)

Arguments

Value

Named list of crowd outputs:

• Each element corresponds to one crowd identifier

• Content depends on the specific makeme type requested

• May contain plots, tables, or other analysis objects

Process Binary Category Colors

Description

Reverses the .category variable for binary categories when a special color condition is met. This is specific to categorical plot functionality.

Usage

process_binary_category_colors(
  data,
  showNA = "never",
  colour_2nd_binary_cat = NULL
)

Arguments

Value

Modified data frame with potentially reversed .category levels

Process categorical data for showNA settings

Description

Handle NA categories based on showNA parameter for categorical tables

Usage

process_categorical_na(data, dots)

Arguments

Value

Processed data frame

Process Data for a Single Crowd

Description

Internal helper function that handles the complete processing pipeline for a single crowd, from data filtering to final output generation.

Usage

process_crowd_data(
  crwd,
  args,
  omitted_cols_list,
  kept_indep_cats_list,
  data,
  mesos_var,
  mesos_group,
  full_category_levels = NULL,
  ...
)

Arguments

Details

Complete processing pipeline:

• Calculates omitted variables for the crowd

• Filters data by crowd membership and variable exclusions

• Applies independent category filtering if enabled

• Detects variable types and generates data summary

• Performs validation and post-processing

• Generates final output via make_content()

Value

Final output object for the crowd, or NULL if no data remains:

• Plot, table, or other analysis object depending on type

• NULL if crowd has no valid data after filtering

Process Crowd Settings

Description

Internal helper function that reorders the crowd array to ensure priority crowds (specified in hide_for_all_crowds_if_hidden_for_crowd) are processed first.

Usage

process_crowd_settings(args)

Arguments

Value

Modified args list with reordered crowd vector:

• Priority crowds (in hide_for_all_crowds_if_hidden_for_crowd) first

• Remaining crowds after

• This ensures global hiding logic is applied correctly

Process Independent Categories for Global Hiding Logic

Description

Internal helper function that applies global hiding logic to independent variable categories based on the hide_for_all_crowds_if_hidden_for_crowd setting.

Usage

process_global_indep_categories(
  kept_indep_cats_list,
  hide_for_all_crowds_if_hidden_for_crowd
)

Arguments

Value

Modified kept_indep_cats_list with global hiding logic applied:

• For crowds not in hide_for_all_crowds_if_hidden_for_crowd: only categories that were kept in the priority crowds are retained

• For priority crowds: original category lists are preserved

Process Independent Variable Factor Levels

Description

Reverses factor levels for independent variables, but only for unordered factors. Preserves the natural ordering of ordered factors.

Usage

process_indep_factor_levels(data, indep = NULL)

Arguments

Value

Modified data frame with reversed factor levels for unordered factors

Process main question and extract suffixes

Description

Handle label separation and suffix extraction for table functions

Usage

process_main_question_and_suffixes(data, dots, col_basis)

Arguments

Value

List with processed data, main_question, and updated col_basis

Process Output Results

Description

Internal helper function that performs final processing of makeme output, including crowd renaming, NULL removal, and output simplification.

Usage

process_output_results(out, args)

Arguments

Value

Processed output in final form:

• Crowds renamed according to translations if provided

• NULL results removed

• Single element extracted if simplify_output=TRUE and length=1

• Empty data.frame returned if no valid results

• Otherwise returns the full named list

Process a Single PDF for Post-Render Title Enrichment

Description

Process a Single PDF for Post-Render Title Enrichment

Usage

process_single_pdf_post_render(pdf_path, gs_bin)

Arguments

Value

Invisible NULL.

Process data with standard table operations

Description

Apply column selection, renaming, and independent variable handling

Usage

process_table_data(
  data,
  col_basis,
  indep_vars = NULL,
  indep_label = character(),
  main_question = "",
  use_header = FALSE,
  stat_columns = NULL,
  column_mappings = NULL
)

Arguments

Value

Processed data frame

Quarto Post-Render: Enrich PDF Files with DOCX Titles

Description

A post-render function for Quarto projects that processes rendered PDF output files. For each PDF, it checks if a corresponding DOCX file with the same base name exists, extracts the title from the DOCX document properties, sets it as the PDF metadata title, and updates the link text in the accompanying index.html.

Usage

quarto_pdf_post_render(
  output_files = strsplit(Sys.getenv("QUARTO_PROJECT_OUTPUT_FILES"), "\n")[[1L]]
)

Arguments

Details

To use as a Quarto post-render script, add to ⁠_quarto.yml⁠:

project:
  post-render:
    - "Rscript -e 'saros::quarto_pdf_post_render()'"

Processing steps for each .pdf file:

1. Checks if a .docx with the same base name exists in the same directory

2. Extracts the title from the DOCX document properties (via officer)

3. Sets the extracted title as the PDF file's metadata title (requires Ghostscript)

4. Locates index.html in the same directory as the PDF

5. Replaces the ⁠<a>⁠ link text for that PDF with the extracted title

Value

Invisible NULL. Called for side effects.

System Requirements

Setting PDF metadata title requires Ghostscript to be installed and available on the system PATH:

• Linux/macOS: gs

• Windows: gswin64c or gswin32c

If Ghostscript is not found, a warning is issued and only the HTML link text update is performed.

See Also

extract_docx_title() for the DOCX title extraction logic.

Examples

## Not run: 
# Called automatically by Quarto post-render, or manually:
quarto_pdf_post_render(c("_site/report/report.pdf"))

## End(Not run)

Read Quarto Post-Render Input from stdin

Description

Parses the JSON array of output file paths that Quarto passes to post-render scripts via stdin.

Usage

read_quarto_post_render_input()

Value

Character vector of file paths.

Rename Crowd Outputs

Description

Internal helper function that renames crowd identifiers in the output based on provided translations.

Usage

rename_crowd_outputs(out, translations)

Arguments

Value

Modified out list with crowd names translated:

• Names changed according to translations with crowd prefix pattern

• Only string translations are applied

• Untranslated crowds retain original names

Reorder Crowd Array Based on Hide Settings

Description

Internal helper function that reorders the crowd array to prioritize crowds specified in hide_for_all_crowds_if_hidden_for_crowd, ensuring they are processed first to determine variable exclusions early.

Usage

reorder_crowd_array(crowd, hide_for_all_crowds_if_hidden_for_crowd)

Arguments

Value

Character vector with reordered crowd identifiers:

• Priority crowds first (those in hide_for_all_crowds_if_hidden_for_crowd)

• Remaining crowds after

Code-snippets copied and modified from tidytext-package https://github.com/juliasilge/tidytext/blob/main/R/reorder_within.R

Description

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

Usage

reorder_within(x, by, within, fun = mean, sep = "___", ...)

Arguments

Details

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Source

"Original: Ordering categories within ggplot2 Facets" by Tyler Rinker: https://trinkerrstuff.wordpress.com/2016/12/23/ordering-categories-within-ggplot2-facets/ Based on https://opensource.org/licenses/MIT Copyright (c) 2017, Julia Silge and David Robinson

Resolve Category Colors for Charts

Description

Centralizes color resolution logic for both HTML and DOCX charts. Handles checkbox detection, level reordering, and priority palette setup.

Usage

resolve_category_colors(cat_levels, girafe_settings)

Arguments

Value

List with:

• checkbox: Logical indicating if this is a checkbox plot

• cat_levels: Character vector (reordered if checkbox)

• priority_palette_codes: Named character vector for priority colors

• colour_palette: Named character vector of resolved colors

Resolve Variable Overlaps Between Dependent and Independent Variables

Description

Internal helper function that handles cases where variables are selected for both dependent and independent roles. Automatically removes overlapping variables from the dependent list and provides user feedback.

Usage

resolve_variable_overlaps(dep, indep)

Arguments

Details

If overlapping variables are found:

• Informs user about the overlap via cli::cli_inform()

• Removes overlapping variables from dep vector

• Throws error if no dependent variables remain after removal

Value

Character vector of dependent variable names with overlaps removed

Round numeric statistics

Description

Apply rounding to numeric statistical columns

Usage

round_numeric_stats(data, digits)

Arguments

Value

Data frame with rounded numeric columns

Wrap a file-writing expression with informative error handling

Description

Catches errors from file-writing operations and re-throws with actionable diagnostics (permissions, long OneDrive/SharePoint paths, etc.).

Usage

safe_file_write(expr, path, call = rlang::caller_env())

Arguments

Value

The result of expr, invisibly.

Set factor levels based on order columns (for backward compatibility)

Description

Set factor levels based on order columns (for backward compatibility)

Usage

set_factor_levels_from_order(data)

Arguments

Value

Dataset with factor levels set according to order

Set PDF Metadata Title Using Ghostscript

Description

Overwrites the PDF file with an updated version containing the specified title in its document information dictionary. Uses a temporary PostScript pdfmark file to avoid shell escaping issues.

Usage

set_pdf_metadata_title(pdf_path, title, gs_bin)

Arguments

Value

Invisible logical; TRUE on success, FALSE on failure.

Setup and Validate Makeme Arguments

Description

Internal helper function that performs final argument setup and validation before processing. Consolidates variable resolution, normalization, and validation.

Usage

setup_and_validate_makeme_args(args, data, dep_pos, indep_pos, indep)

Arguments

Value

Modified and validated args list ready for processing:

• Variable names resolved from positions

• Overlaps between dep and indep resolved

• Multi-choice arguments normalized

• All validation checks passed

• Crowd array reordered for optimal processing

Setup table data from dots

Description

Common setup logic for table functions including data extraction and early return

Usage

setup_table_data(dots)

Arguments

Value

List with data and should_return flag

Shift labels_always_at

Description

Shift labels_always_at

Usage

shift_labels_always_at(data, labels_always_at = NULL, after = Inf)

Arguments

Value

Dataset with data$.variable_label adjusted

Apply string wrapping to variables (character or factor)

Description

A utility function that applies string wrapping to both character and factor variables, preserving factor structure while wrapping the labels.

Usage

strip_wrap_var(x, width = Inf)

Arguments

Value

Modified variable with wrapped text

Given Ordered Integer Vector, Return Requested Set.

Description

Useful for identifying which categories are to be collected.

Usage

subset_vector(
  vec,
  set = c(".top", ".upper", ".mid_upper", ".lower", ".mid_lower", ".bottom", ".spread"),
  spread_n = NULL,
  sort = FALSE
)

Arguments

Value

Selected set of vector.

Summarize a survey dataset for use in tables and graphs

Description

Summarize a survey dataset for use in tables and graphs

Usage

summarize_cat_cat_data(
  data,
  dep = colnames(data),
  indep = NULL,
  ...,
  showNA = c("ifany", "always", "never"),
  totals = FALSE,
  sort_by = ".upper",
  sort_dep_by = NULL,
  sort_indep_by = ".factor_order",
  data_label = c("percentage_bare", "percentage", "proportion", "count", "mean",
    "median"),
  digits = 0,
  add_n_to_dep_label = FALSE,
  add_n_to_indep_label = FALSE,
  add_n_to_label = FALSE,
  add_n_to_category = FALSE,
  hide_label_if_prop_below = 0.01,
  data_label_decimal_symbol = ".",
  categories_treated_as_na = NULL,
  label_separator = NULL,
  descend = FALSE,
  descend_indep = FALSE,
  labels_always_at_bottom = NULL,
  labels_always_at_top = NULL,
  translations = list(),
  full_category_levels = NULL,
  call = rlang::caller_env()
)

Arguments

Value

Dataset with the columns: .variable_name, .variable_label, .category, .count, .count_se, .count_per_dep, .count_per_indep_group, .proportion, .proportion_se, .mean, .mean_se, .median, indep-variable(s), .data_label, .comb_categories, .sum_value, .variable_label_prefix

Extract Text Summary from Categorical Mesos Plots

Description

Generates text summaries comparing two groups from categorical mesos plot data. The function identifies meaningful differences between groups based on proportions of respondents selecting specific categories and produces narrative text descriptions.

Usage

txt_from_cat_mesos_plots(
  plots,
  min_prop_diff = 0.1,
  n_highest_categories = 1,
  flip_to_lowest_categories = FALSE,
  checked = NULL,
  not_checked = NULL,
  digits = 2,
  selected_categories_last_split = " or ",
  fallback_string = character(),
  reverse = FALSE,
  glue_str_pos =
    c(paste0("For {var}, the target group has a higher proportion of respondents ",
    "({group_1}) than all others ({group_2}) who answered {selected_categories}."),
    paste0("More respondents answered {selected_categories} for {var} in the ",
    "target group ({group_1}) than in other groups ({group_2})."),
    paste0("The statement {var} shows {selected_categories} responses are more ",
    "common in the target group ({group_1}) compared to others ({group_2}).")),
  glue_str_neg =
    c(paste0("For {var}, the target group has a lower proportion of respondents ",
    "({group_1}) than all others ({group_2}) who answered {selected_categories}."),
    paste0("Fewer respondents answered {selected_categories} for {var} in the ",
    "target group ({group_1}) than in other groups ({group_2})."),
    paste0("The statement {var} shows {selected_categories} responses are less ",
    "common in the target group ({group_1}) compared to others ({group_2})."))
)

Arguments

Details

The function compares proportions between two groups for each variable in the plot data. One template is randomly selected from the provided vectors for variety in output text.

Checkbox (checked/not_checked) variables: When checked and not_checked are both strings, any variable whose categories exactly match that pair is treated as a checkbox variable. For such variables the comparison is always made on the checked category, regardless of flip_to_lowest_categories. This mirrors the visual convention in the bar chart where the checked category is rendered in colour on the left — the semantically meaningful side — even though its .category_order may not be the highest. If checked/not_checked are NULL, the function tries to auto-detect them from global_settings_get("girafe")$checked / ⁠$not_checked⁠; if those are also NULL, checkbox handling is disabled.

Value

A character vector of text summaries, one per variable with meaningful differences. Returns empty character vector if no plots provided or no meaningful differences found.

Examples

## Not run: 
# Create sample plot data
plot_data_1 <- data.frame(
  .variable_label = rep("Job satisfaction", 3),
  .category = factor(c("Low", "Medium", "High"), levels = c("Low", "Medium", "High")),
  .category_order = 1:3,
  .proportion = c(0.2, 0.3, 0.5)
)

plot_data_2 <- data.frame(
  .variable_label = rep("Job satisfaction", 3),
  .category = factor(c("Low", "Medium", "High"), levels = c("Low", "Medium", "High")),
  .category_order = 1:3,
  .proportion = c(0.3, 0.4, 0.3)
)

plots <- list(
  list(data = plot_data_1),
  list(data = plot_data_2)
)

# Generate text summaries
txt_from_cat_mesos_plots(plots, min_prop_diff = 0.10)

# Compare lowest categories instead
txt_from_cat_mesos_plots(
  plots,
  flip_to_lowest_categories = TRUE,
  min_prop_diff = 0.05
)

## End(Not run)

Update Link Text for a PDF in an HTML File

Description

Finds ⁠<a>⁠ elements whose href points to the given PDF filename and replaces their inner text with the specified title.

Usage

update_html_pdf_link_text(html_path, pdf_filename, title)

Arguments

Value

Invisible logical; TRUE if replacements were made, FALSE otherwise.

Validate boolean parameter

Description

Validate boolean parameter

Usage

validate_bool(x, call = rlang::caller_env(), arg = rlang::caller_arg(x))

Create boolean validation rule

Description

Create boolean validation rule

Usage

validate_bool_rule()

Create character vector validation rule

Description

Create character vector validation rule

Usage

validate_character_vector_rule(null_allowed = FALSE)

Arguments

Validate double/numeric parameter

Description

Validate double/numeric parameter

Usage

validate_double(
  x,
  min = -Inf,
  max = Inf,
  null_allowed = FALSE,
  call = rlang::caller_env(),
  arg = rlang::caller_arg(x)
)

Arguments

Create double validation rule

Description

Create double validation rule

Usage

validate_double_rule(min = -Inf, max = Inf, null_allowed = FALSE)

Arguments

Validate integerish parameter

Description

Validate integerish parameter

Usage

validate_integerish(
  x,
  min = -Inf,
  max = Inf,
  null_allowed = FALSE,
  call = rlang::caller_env(),
  arg = rlang::caller_arg(x)
)

Create integerish validation rule

Description

Create integerish validation rule

Usage

validate_integerish_rule(min = -Inf, max = Inf, null_allowed = FALSE)

Arguments

Validate Palette Parameters

Description

Validates palette-related parameters used by girafe() and ggsaver(). Ensures type safety and provides clear error messages for invalid inputs.

Usage

validate_palette_params(
  palette_codes = NULL,
  priority_palette_codes = NULL,
  label_wrap_width = NULL,
  ncol = NULL,
  byrow = NULL,
  call = rlang::caller_env()
)

Arguments

Value

NULL (called for side effects - validation)

Validate multiple parameters at once

Description

Validate multiple parameters at once

Usage

validate_params(params, spec, call = rlang::caller_env())

Arguments

Validate single dependent variable requirement

Description

Common validation pattern for functions that require exactly one dependent variable.

Usage

validate_single_dep_var(dep, function_name)

Arguments

Value

Nothing if valid, throws error if invalid

Validate that category-based sort references categories present in data

Description

Fails fast with an informative error when sort_by names one or more categories that do not exist in the .category column of data.

Usage

validate_sort_category(sort_by, data, call = rlang::caller_env())

Arguments

Value

TRUE invisibly if valid.

Validate that a column-based sort references an existing column

Description

Fails fast with an informative error when sort_by names a column (from the allowed whitelist) that is not present in data. Only performs validation for scalar sort_by; non-scalar values (e.g. category vectors) are skipped since they are validated by validate_sort_category() instead.

Usage

validate_sort_column(
  sort_by,
  data,
  allowed = .saros.env$allowed_dep_sort_columns,
  call = rlang::caller_env()
)

Arguments

Value

TRUE invisibly if valid.

Validate string parameter

Description

Validate string parameter

Usage

validate_string(
  x,
  null_allowed = FALSE,
  call = rlang::caller_env(),
  arg = rlang::caller_arg(x)
)

Arguments

Create string validation rule

Description

Create string validation rule

Usage

validate_string_rule(null_allowed = FALSE)

Arguments

Perform Type-Specific Validation Checks

Description

Internal helper function that validates arguments based on the specific output type requested. Different types have different constraints.

Usage

validate_type_specific_constraints(args, data, indep, dep_pos)

Arguments

Details

Current type-specific validations:

• chr_table_html: Requires exactly one dependent variable

Value

NULL (function used for side effects - validation errors)

Validate Variable Type Compatibility with Requested Output Type

Description

Checks that the dependent variable types are compatible with the requested output type. For example, categorical types (cat_plot_*, cat_table_*) require factor/ordered/character variables, not numeric/integer.

Usage

validate_type_variable_compatibility(type, dep_types, dep_names)

Arguments

Value

NULL (function used for side effects - validation errors)