Package 'Saqrmisc'

Description

Computes row totals across specified columns and adds them as a new column.

Usage

add_total(data, cols = NULL, name = "total", na.rm = TRUE)

Arguments

Value

The original data frame with an added total column.

Examples

## Not run: 
df <- data.frame(id = 1:3, a = c(1,2,3), b = c(4,5,6), c = c(7,8,9))

# All numeric columns
add_total(df)

# Specific columns by name
add_total(df, cols = c("a", "b"))

# Columns by index range
add_total(df, cols = 2:4)

# From column 2 to end
add_total(df, cols = 2)

# Custom name
add_total(df, cols = c("a", "b"), name = "sum_ab")

## End(Not run)

Description

Returns one of the result's tables as a plain data.frame, so callers never have to reach into the object. For a stratified fit (one produced with by =), what = "strata" gives one row per stratum with its own test, effect size and multiplicity-corrected p-value.

Usage

## S3 method for class 'mosaic_analysis'
as.data.frame(
  x,
  row.names = NULL,
  optional = FALSE,
  what = c("summary", "table", "residuals", "strata", "overall"),
  ...
)

Arguments

Value

A data.frame. For what = "strata", one row per stratum with columns stratum, n, test, statistic, df, p_value, p_adjusted, cramers_v, effect_size and n_cells_beyond_2. For what = "residuals" on a stratified fit, one row per stratum x cell.

Examples

set.seed(1)
d <- data.frame(
  a = sample(c("X", "Y", "Z"), 400, replace = TRUE),
  b = sample(c("P", "Q"), 400, replace = TRUE),
  g = sample(c("g1", "g2"), 400, replace = TRUE)
)
fit <- mosaic_analysis(d, "a", "b", by = "g", min_count = 5, verbose = FALSE)
as.data.frame(fit, what = "strata")
as.data.frame(fit, what = "overall")

Description

Automatically detects numeric and categorical variables in a data frame and generates appropriate descriptive statistics tables for each type. Numeric variables get summary statistics (mean, SD, etc.) and categorical variables get frequency tables.

Usage

auto_describe(
  data,
  group_by = NULL,
  numeric_stats = c("n", "mean", "sd", "median", "min", "max"),
  digits = 2,
  exclude = NULL,
  force_categorical = NULL,
  title_numeric = "Numeric Variables",
  title_categorical = "Categorical Variables",
  theme = "default",
  format = "gt",
  print = TRUE
)

Arguments

Value

A list with:

• numeric: Descriptive table for numeric variables (or NULL if none)

• categorical: List of frequency tables for categorical variables

• variable_types: Data frame showing detected variable types

Examples

## Not run: 
# Automatic description of all variables
data <- data.frame(
  age = rnorm(100, 35, 10),
  score = rnorm(100, 75, 15),
  gender = sample(c("M", "F"), 100, replace = TRUE),
  education = sample(c("HS", "BA", "MA", "PhD"), 100, replace = TRUE)
)

# Describe all variables automatically
results <- auto_describe(data)

# With grouping
results <- auto_describe(data, group_by = "gender")

# Access individual tables
results$numeric
results$categorical$education

## End(Not run)

Description

Creates comprehensive frequency tables for categorical variables with counts, percentages, and optional cross-tabulation. Supports chi-square tests for associations and outputs beautifully formatted gt tables.

Usage

categorical_table(
  data,
  var,
  by = NULL,
  group_by = NULL,
  percentages = NULL,
  show_n = TRUE,
  show_total = TRUE,
  show_missing = FALSE,
  show_header = TRUE,
  chi_square = TRUE,
  fisher = FALSE,
  cramers_v = TRUE,
  digits = 1,
  sort_by = "none",
  labels = NULL,
  title = NULL,
  subtitle = NULL,
  format = c("gt", "plain", "markdown", "latex", "kable"),
  theme = "default",
  combine = TRUE,
  interpret = FALSE,
  ...
)

Arguments

Value

A gt table object (default) or data frame with frequencies and percentages. For cross-tabulations with chi_square = TRUE, includes test statistics.

See Also

descriptive_table for numeric variable summaries mosaic_analysis for mosaic plot visualization with chi-square tests

Examples

## Not run: 
# ============================================================
# EXAMPLE 1: Single Variable Frequency Table
# ============================================================
data <- data.frame(
  gender = sample(c("Male", "Female", "Other"), 200, replace = TRUE,
                  prob = c(0.45, 0.45, 0.10)),
  education = sample(c("High School", "Bachelor", "Master", "PhD"), 200,
                     replace = TRUE, prob = c(0.3, 0.4, 0.2, 0.1)),
  country = sample(c("USA", "UK", "Germany"), 200, replace = TRUE)
)

# Basic frequency table
categorical_table(data, var = "gender")

# With sorting by frequency
categorical_table(data, var = "education", sort_by = "frequency")

# ============================================================
# EXAMPLE 2: Cross-Tabulation (Two Variables)
# ============================================================
categorical_table(
  data = data,
  var = "gender",
  by = "education",
  chi_square = TRUE,
  cramers_v = TRUE
)

# ============================================================
# EXAMPLE 3: Stratified Analysis
# ============================================================
categorical_table(
  data = data,
  var = "gender",
  by = "education",
  group_by = "country"
)

# ============================================================
# EXAMPLE 4: Custom Labels and Formatting
# ============================================================
categorical_table(
  data = data,
  var = education,
  labels = c(
    "High School" = "Secondary Education",
    "Bachelor" = "Bachelor's Degree",
    "Master" = "Master's Degree",
    "PhD" = "Doctorate"
  ),
  title = "Educational Attainment",
  subtitle = "Sample Distribution",
  theme = "colorful"
)

# ============================================================
# EXAMPLE 5: Show Row and Column Percentages
# ============================================================
categorical_table(
  data = data,
  var = gender,
  by = education,
  percentages = c("row", "col"),
  combine = FALSE
)

## End(Not run)

Description

Centers numeric variables by subtracting the mean. Supports group-wise centering for multilevel/nested data. Works with dplyr mutate/across.

Usage

center(data, Vars, suffix = "_c", group_by = NULL)

Arguments

Value

Data frame with centered variables added, or vector if input is vector.

Examples

## Not run: 
# Simple mean centering
df <- center(mtcars, Vars = c("mpg", "hp"))

# Group-mean centering
df <- center(mtcars, Vars = "mpg", group_by = "cyl")

# With dplyr
library(dplyr)
mtcars %>% mutate(mpg_c = center_vec(mpg))
mtcars %>% mutate(across(c(mpg, hp), center_vec, .names = "{.col}_c"))

# Group-wise with dplyr
mtcars %>% group_by(cyl) %>% mutate(mpg_c = center_vec(mpg))

## End(Not run)

Description

Vectorized centering function for use with dplyr mutate and across. For group-wise centering, use dplyr::group_by() before mutate().

Usage

center_vec(x, na.rm = TRUE)

Arguments

Value

Centered numeric vector.

Examples

## Not run: 
library(dplyr)

# Single variable
mtcars %>% mutate(mpg_c = center_vec(mpg))

# Multiple variables
mtcars %>% mutate(across(c(mpg, hp, wt), center_vec, .names = "{.col}_c"))

# Group-wise centering
mtcars %>% group_by(cyl) %>% mutate(mpg_c = center_vec(mpg))

## End(Not run)

Description

Fits latent profile models with the latents package and keeps the candidate with the lowest BIC. Every combination of n_profiles and models is fitted by latents::enumerate_lpa(); a single combination is simply a grid of one.

The result is a latents fit, so its verbs apply directly: as.data.frame(fit) for profile means, latents::diagnostics(fit) for classification quality, latents::get_results(fit, what) for any table.

Usage

clustering(
  data,
  vars,
  n_profiles = NULL,
  n_clusters = NULL,
  models = "VVI",
  scaling = c("standardize", "center", "minmax", "none"),
  n_starts = 10L,
  seed = NULL,
  na_action = c("omit", "fail"),
  verbose = TRUE
)

Arguments

Value

An object of class c("saqr_clustering", "multilpa"): the selected latents fit, fitted to the scaled data. Methods: print(), summary() (one row per candidate), fitted() (the input data with profile assignments), plot().

Errors

Raises saqrmisc_bad_input for unknown models, non-numeric or constant vars, missing values under na_action = "fail", or fewer than 10 complete rows; saqrmisc_no_converged when no candidate converged.

References

Vermunt, J. K. (2003). Multilevel latent class models. Sociological Methodology, 33, 213-239.

See Also

plot_clustering(), latents::enumerate_lpa()

Examples

set.seed(1)
vars <- c("Sepal.Length", "Sepal.Width", "Petal.Length", "Petal.Width")
fit <- clustering(iris, vars, n_profiles = 2:4, models = c("EEE", "VVI"))
fit
summary(fit)
as.data.frame(fit)
fitted(fit)
plot(fit)

Description

The figures plot_clustering() can draw. Any type, any group, or "all" can be passed as its type.

Usage

clustering_plot_types()

Value

A data.frame with one row per plot type and columns type, group ("clusters", "diagnostics" or "selection") and description.

Examples

clustering_plot_types()

Description

A comprehensive function for comparing groups using publication-ready visualizations and statistical tests. Creates 'ggbetweenstats' plots from the ggstatsplot package with automatic test selection based on the number of groups:

For 2 groups: t-test (parametric) or Mann-Whitney U (nonparametric). For 3+ groups: ANOVA (parametric) or Kruskal-Wallis (nonparametric) with post-hoc pairwise comparisons. Also supports Bayesian analysis, equivalence testing (TOST), and stratified analyses using repeat_category.

Usage

compare_groups(
  data,
  category,
  Vars = NULL,
  category_sep = " | ",
  repeat_category = NULL,
  compare_by = NULL,
  compare_mode = c("between", "within"),
  repeat_combine = TRUE,
  repeat_levels = NULL,
  plots = TRUE,
  plot_style = c("points", "boxplot", "bar", "violin", "ggstatsplot"),
  table = TRUE,
  type = "auto",
  bayesian = FALSE,
  equivalence = FALSE,
  equivalence_bounds = c(-0.5, 0.5),
  nonparametric = FALSE,
  p_adjust_method = "fdr",
  posthoc = TRUE,
  posthoc_method = "games-howell",
  posthoc_table = FALSE,
  posthoc_format = c("wide", "long", "both"),
  pairwise_display = "significant",
  pivot = FALSE,
  pivot_by = c("category", "repeat_category"),
  pivot_stat = c("mean", "mean_sd", "median", "n"),
  pivot_stars = TRUE,
  pivot_split_level = TRUE,
  min_threshold = 0.05,
  min_subcategory = 5,
  colors = NULL,
  verbose = TRUE,
  combined_table = TRUE,
  format = c("gt", "plain", "markdown", "latex", "kable"),
  show_header = TRUE,
  interpret = FALSE,
  ...
)

Arguments

Value

A list with class "comparison_results" containing: plots (named list of ggplot objects), grid_plot (combined plot grid if multiple variables), summary_table (formatted gt table), and summary_data (data frame with raw statistics). For stratified analysis (with repeat_category), returns a named list where each element corresponds to a level of repeat_category. When pivot = TRUE, additional elements are returned:

• pivot_table: gt table with groups as columns and factor levels as rows

• posthoc_pivot_wide: Post-hoc comparisons in wide format (if posthoc_table = TRUE)

• posthoc_pivot_long: Post-hoc comparisons in long format (if posthoc_format = "long" or "both")

See Also

ggbetweenstats for the underlying plot function

Examples

## Not run: 
# ============================================================
# EXAMPLE 1: Basic Two-Group Comparison (t-test)
# ============================================================
data <- data.frame(
  gender = rep(c("Male", "Female"), each = 50),
  score = c(rnorm(50, mean = 100, sd = 15),
            rnorm(50, mean = 105, sd = 15))
)

results <- compare_groups(
  data = data,
  category = "gender",
  Vars = c("score")
)

# View the plot
results$plots$gender_vs_score

# View summary statistics
results$summary_data

# ============================================================
# EXAMPLE 2: Three-Group Comparison (ANOVA with post-hoc)
# ============================================================
data <- data.frame(
  country = rep(c("USA", "UK", "Germany"), each = 40),
  score1 = c(rnorm(40, 75, 10), rnorm(40, 70, 11), rnorm(40, 85, 9)),
  score2 = c(rnorm(40, 50, 8), rnorm(40, 55, 9), rnorm(40, 48, 7))
)

results <- compare_groups(
  data = data,
  category = "country",
  Vars = c("score1", "score2"),
  posthoc = TRUE,
  posthoc_method = "tukey",
  pairwise_display = "all"
)

# View post-hoc pairwise comparisons
results$summary_data$posthoc_results[[1]]

# Print full ANOVA report
cat(results$summary_data$anova_report[1])

# ============================================================
# EXAMPLE 3: Bayesian Analysis
# ============================================================
results <- compare_groups(
  data = data,
  category = "country",
  Vars = c("score1"),
  bayesian = TRUE
)

# View Bayes Factors
results$summary_data[, c("country", "mean", "bf10", "bf_interpretation")]

# ============================================================
# EXAMPLE 4: Nonparametric Tests
# ============================================================
results <- compare_groups(
  data = data,
  category = "country",
  Vars = c("score1"),
  nonparametric = TRUE  # Uses Kruskal-Wallis + pairwise Wilcoxon
)

# ============================================================
# EXAMPLE 5: Stratified Analysis (separate tests per subgroup)
# ============================================================
data <- data.frame(
  country = rep(c("USA", "UK", "Germany"), each = 60),
  gender = rep(c("Male", "Female"), times = 90),
  score = rnorm(180, mean = 100, sd = 15)
)

# Compare gender WITHIN each country
results <- compare_groups(
  data = data,
  category = "gender",
  Vars = c("score"),
  repeat_category = "country"
)

# Access results by country
results$USA$summary_data
results$UK$plots$gender_vs_score
results$Germany$summary_table

# ============================================================
# EXAMPLE 6: Equivalence Testing (TOST)
# ============================================================
results <- compare_groups(
  data = data,
  category = "gender",
  Vars = c("score"),
  equivalence = TRUE,
  equivalence_bounds = c(-0.3, 0.3)  # Small effect bounds
)

# Check equivalence conclusions
results$summary_data[, c("gender", "mean", "equivalence_conclusion")]

# ============================================================
# EXAMPLE 7: Combined/Interaction Groups
# ============================================================
data <- data.frame(
  strength = rep(c("Strong", "Weak"), each = 60),
  gender = rep(c("Male", "Female"), times = 60),
  score = rnorm(120, mean = 100, sd = 15)
)

# Pass multiple variables to category for interaction groups
results <- compare_groups(
  data = data,
  category = c("strength", "gender"),  # Creates "Strong | Male", "Strong | Female", etc.
  Vars = c("score")
)

# Custom separator
results <- compare_groups(
  data = data,
  category = c("strength", "gender"),
  category_sep = " x ",  # Creates "Strong x Male", etc.
  Vars = c("score")
)

# ============================================================
# EXAMPLE 8: Pivoted Table (groups as columns)
# ============================================================
# LLM comparison data
data <- data.frame(
  Support_level = c(rnorm(100, 4, 1), rnorm(100, 6.5, 1), rnorm(100, 4.8, 1)),
  pronoun = rep(c("he/him", "she/her", "they/them"), each = 100),
  LA_activity = rep(c("Negative", "Positive"), 150),
  llm = rep(c("GPT", "Mistral", "Qwen"), each = 100)
)

# Basic pivot - groups become columns
results <- compare_groups(
  data = data,
  category = "llm",                    # Becomes columns: GPT | Mistral | Qwen
  Vars = "Support_level",
  repeat_category = "pronoun",         # Rows: he/him, she/her, they/them
  pivot = TRUE                         # Enable pivot mode
)

# Access the pivot table
results$pivot_table

# ============================================================
# EXAMPLE 9: Pivot with Mean and SD
# ============================================================
results <- compare_groups(
  data = data,
  category = "llm",
  Vars = "Support_level",
  repeat_category = c("pronoun", "LA_activity"),
  pivot = TRUE,
  pivot_stat = "mean_sd"              # Shows "4.32 (1.21)"
)

# ============================================================
# EXAMPLE 10: Pivot with Post-hoc Comparisons Table
# ============================================================
results <- compare_groups(
  data = data,
  category = "llm",
  Vars = "Support_level",
  repeat_category = "pronoun",
  pivot = TRUE,
  posthoc = TRUE,
  posthoc_table = TRUE,               # Include post-hoc table
  posthoc_format = "wide"             # "wide", "long", or "both"
)

# Access tables
results$pivot_table              # Main pivoted means table
results$posthoc_pivot_wide       # Post-hoc comparisons (wide format)

# ============================================================
# EXAMPLE 11: Different P-value Adjustment Methods
# ============================================================
# Available methods: "none", "bonferroni", "holm", "hochberg",
#                   "hommel", "BH", "BY", "fdr" (default)
results <- compare_groups(
  data = data,
  category = "llm",
  Vars = "Support_level",
  repeat_category = "pronoun",
  pivot = TRUE,
  p_adjust_method = "bonferroni"
)

## End(Not run)

Description

Performs Network Comparison Test (NCT) to compare network structure and global strength between two groups.

Usage

compare_networks(results, groups, it = 1000, test = "both", verbose = TRUE)

Arguments

Value

A list containing NCT results with p-values for network structure and global strength differences.

Examples

## Not run: 
# First estimate grouped networks
grouped_results <- estimate_grouped_networks(df, Vars, GroupVar = "group")

# Then compare two groups
comparison <- compare_networks(
  grouped_results,
  groups = c("GroupA", "GroupB"),
  it = 500
)

## End(Not run)

Description

Converts long-form or wide-form sequence data into useful formats for analysis, such as frequency tables, one-hot encodings, or edge lists (for network analysis).

Usage

convert_sequences(
  data,
  seq_cols = NULL,
  id_col = NULL,
  format = c("frequency", "onehot", "edgelist", "follows"),
  na_values = NULL
)

Arguments

Value

A data frame structured according to the requested format:

• 'frequency': Wide format with action counts per ID

• 'onehot': Wide format with binary indicators per ID

• 'edgelist': Long format with columns: id, from, to

• 'follows': Long format with columns: id, act, follows

Examples

## Not run: 
# Example sequence data
seq_data <- data.frame(
  id = 1:3,
  t1 = c("A", "B", "A"),
  t2 = c("B", "A", "C"),
  t3 = c("C", "C", "A"),
  t4 = c("A", "*", "B")  # "*" is TraMineR missing
)

# Frequency table
convert_sequences(seq_data, format = "frequency")

# One-hot encoding
convert_sequences(seq_data, format = "onehot")

# Edge list for network analysis
convert_sequences(seq_data, format = "edgelist")

# What follows what
convert_sequences(seq_data, format = "follows")

## End(Not run)

Description

Creates a formatted correlation matrix with significance stars, optional confidence intervals, and heatmap visualization. Supports bivariate (zero-order), partial, and semi-partial correlations.

Usage

correlation_matrix(
  data,
  Vars = NULL,
  type = c("bivariate", "partial", "semi-partial"),
  method = c("pearson", "spearman", "kendall"),
  triangle = c("lower", "upper", "full"),
  diagonal = c("dash", "one", "names"),
  show_n = FALSE,
  show_ci = FALSE,
  show_p = FALSE,
  p_adjust = c("none", "bonferroni", "holm", "fdr"),
  stars = TRUE,
  heatmap = FALSE,
  digits = 2,
  title = NULL,
  use = c("pairwise", "complete"),
  format = c("gt", "plain", "markdown", "latex", "kable"),
  show_header = TRUE,
  interpret = FALSE,
  ...
)

Arguments

Value

A list containing: table (gt table with formatted correlations), correlation_matrix (numeric matrix), p_matrix (matrix of p-values), n_matrix (pairwise sample sizes), and heatmap (ggplot if requested).

Examples

## Not run: 
# Basic correlation matrix
correlation_matrix(
  data = mtcars,
  Vars = c("mpg", "cyl", "disp", "hp")
)

# Partial correlations (controlling for other variables)
correlation_matrix(
  data = mtcars,
  Vars = c("mpg", "cyl", "disp", "hp"),
  type = "partial",
  title = "Partial Correlations"
)

# Semi-partial correlations
correlation_matrix(
  data = mtcars,
  Vars = c("mpg", "cyl", "disp", "hp"),
  type = "semi-partial"
)

# With confidence intervals and heatmap
correlation_matrix(
  data = mtcars,
  Vars = c("mpg", "cyl", "disp", "hp"),
  show_ci = TRUE,
  heatmap = TRUE,
  title = "Motor Trend Car Correlations"
)

# Spearman correlations with Bonferroni correction
correlation_matrix(
  data = mtcars,
  Vars = c("mpg", "cyl", "disp"),
  method = "spearman",
  p_adjust = "bonferroni"
)

## End(Not run)

Description

Creates a comprehensive long-format correlation table showing all pairwise correlations with full statistics including r, confidence intervals, test statistics, degrees of freedom, p-values, and sample sizes. Supports multilevel/repeated measures correlations for nested data.

Usage

correlations(
  data,
  Vars = NULL,
  type = c("bivariate", "partial", "semi-partial"),
  method = c("pearson", "spearman", "kendall"),
  p_adjust = c("none", "bonferroni", "holm", "fdr"),
  ci_level = 0.95,
  min_r = NULL,
  sig_only = FALSE,
  multilevel = FALSE,
  id = NULL,
  between = FALSE,
  group_by = NULL,
  include = NULL,
  exclude = NULL,
  auto_consolidate = TRUE,
  digits = 3,
  title = NULL,
  format = c("gt", "plain", "markdown", "latex", "kable"),
  show_header = TRUE,
  interpret = FALSE,
  ...
)

Arguments

Details

When multilevel = TRUE, the function calculates within-cluster correlations by group-mean centering variables before computing correlations. This removes between-cluster variance and estimates the pooled within-cluster association, appropriate for repeated measures or hierarchically nested data.

The degrees of freedom for multilevel correlations are adjusted as: df = n_observations - n_clusters - 1

Value

A list containing: table (formatted output), data (raw statistics), display (formatted display data frame), n_pairs, n_significant, consolidated (values moved to subtitle), between_data (if multilevel).

Examples

## Not run: 
# Correlate all numeric variables in data frame
correlations(mtcars)

# Full correlation table with specific variables
correlations(mtcars, Vars = c("mpg", "cyl", "disp", "hp", "wt"))

# Only strong correlations
correlations(mtcars, Vars = c("mpg", "cyl", "disp", "hp"), min_r = 0.5)

# Partial correlations with Bonferroni correction
correlations(mtcars, Vars = c("mpg", "cyl", "disp", "hp"),
             type = "partial", p_adjust = "bonferroni")

# Only significant correlations
correlations(mtcars, Vars = c("mpg", "cyl", "disp", "hp", "wt"),
             sig_only = TRUE)

# Multilevel correlations (within-person)
correlations(longitudinal_data, Vars = c("anxiety", "depression", "stress"),
             multilevel = TRUE, id = "participant_id")

# Multilevel with between-cluster correlations
correlations(longitudinal_data, Vars = c("anxiety", "depression"),
             multilevel = TRUE, id = "participant_id", between = TRUE)

# Correlations by group (stratified)
correlations(mtcars, Vars = c("mpg", "hp", "wt"), group_by = "cyl")

# Correlations by group with significance filter
correlations(mtcars, Vars = c("mpg", "hp", "wt", "disp"),
             group_by = "am", sig_only = TRUE)

# Include only specific statistics
correlations(mtcars, Vars = c("mpg", "hp", "wt"),
             include = c("r", "ci", "p", "sig"))

# Exclude statistics you don't need
correlations(mtcars, Vars = c("mpg", "hp", "wt"),
             exclude = c("stat", "df"))

# Disable auto-consolidation (always show df and n columns)
correlations(mtcars, Vars = c("mpg", "hp", "wt"),
             auto_consolidate = FALSE)

## End(Not run)

Description

Converts long-format event data to a frequency table with counts per ID. Useful for transforming event logs, clickstream data, or any repeated measures into a wide format suitable for analysis.

Usage

counts(data, id = NULL, event = NULL, na_values = NULL)

Arguments

Value

A data frame with one row per unique ID combination and columns for each unique event value containing counts.

Examples

## Not run: 
# Event log data
events <- data.frame(
  student = c(1, 1, 1, 2, 2, 2, 3, 3),
  action = c("login", "view", "submit", "login", "view", "view", "login", "submit")
)

# Count events per student
counts(events, id = "student", event = "action")

# Multiple ID columns
events2 <- data.frame(
  student = c(1, 1, 1, 1, 2, 2),
  course = c("A", "A", "B", "B", "A", "A"),
  action = c("view", "submit", "view", "view", "view", "submit")
)

counts(events2, id = c("student", "course"), event = "action")

## End(Not run)

Description

Provides a comprehensive snapshot of a dataset including variable types, missing data percentages, unique values, and basic statistics.

Usage

data_overview(data, Vars = NULL, max_levels = 10, digits = 2)

Arguments

Value

A gt table with dataset overview.

Examples

## Not run: 
data_overview(mtcars)
data_overview(iris, Vars = c("Sepal.Length", "Species"))

## End(Not run)

Description

Creates a comprehensive, publication-ready table of descriptive statistics for numeric variables. Supports stratification by grouping variables and outputs beautifully formatted gt tables.

Usage

descriptive_table(
  data,
  Vars = NULL,
  group_by = NULL,
  stats = c("n", "mean", "sd", "median", "min", "max"),
  digits = 2,
  labels = NULL,
  title = "Descriptive Statistics",
  subtitle = NULL,
  overall = FALSE,
  transpose = FALSE,
  format = c("gt", "plain", "markdown", "latex", "kable"),
  show_header = TRUE,
  theme = "default",
  compare = FALSE,
  bold_highest = NULL,
  sig_color = "red",
  interpret = FALSE,
  ...
)

Arguments

Value

A saqr_result object containing:

• table: The formatted gt table (or other format if specified)

• data: Raw data frame with computed statistics

• markdown: Markdown version of the table for AI interpretation

• type: "descriptive"

• variables: Variables analyzed

• statistics: Statistics computed

• n: Total sample size

When printed, displays the formatted table. Use result$markdown to get a text version suitable for pass.

Exporting Tables

The gt output can be exported using gtsave(): HTML (.html), Word (.docx), PDF (.pdf), or PNG (.png). Example: gtsave(table, "descriptives.html").

See Also

gt for gt table customization

Examples

## Not run: 
# ============================================================
# EXAMPLE 1: Basic Descriptive Statistics
# ============================================================
data <- data.frame(
  age = rnorm(100, mean = 35, sd = 10),
  score = rnorm(100, mean = 75, sd = 15),
  income = rnorm(100, mean = 50000, sd = 15000)
)

# Default statistics (n, mean, sd, median, min, max)
descriptive_table(data, Vars = c("age", "score", "income"))

# ============================================================
# EXAMPLE 2: Custom Statistics Selection
# ============================================================
descriptive_table(
  data = data,
  Vars = c("age", "score"),
  stats = c("n", "mean", "sd", "se", "median", "iqr", "skewness", "kurtosis")
)

# ============================================================
# EXAMPLE 3: Stratified by Group
# ============================================================
data$gender <- sample(c("Male", "Female"), 100, replace = TRUE)

descriptive_table(
  data = data,
  Vars = c("age", "score"),
  group_by = gender,
  overall = TRUE  # Include overall statistics
)

# ============================================================
# EXAMPLE 4: Custom Labels and Title
# ============================================================
descriptive_table(
  data = data,
  Vars = c("age", "score", "income"),
  labels = c(
    age = "Age (years)",
    score = "Test Score",
    income = "Annual Income ($)"
  ),
  title = "Sample Characteristics",
  subtitle = "N = 100 participants"
)

# ============================================================
# EXAMPLE 5: Export to Data Frame
# ============================================================
df <- descriptive_table(
  data = data,
  Vars = c("age", "score"),
  format = "data.frame"
)
print(df)

# ============================================================
# EXAMPLE 6: Different Themes
# ============================================================
descriptive_table(data, Vars = c("age", "score"), theme = "minimal")
descriptive_table(data, Vars = c("age", "score"), theme = "dark")
descriptive_table(data, Vars = c("age", "score"), theme = "colorful")

## End(Not run)

Description

Estimates networks for different groups within a data frame, using 'estimate_single_network' internally. Produces separate network visualizations and metrics for each group.

Usage

estimate_grouped_networks(
  df,
  Vars = NULL,
  GroupVar,
  layout = "circle",
  color = DEFAULT_NODE_COLOR,
  default = "EBICglasso",
  var_types = NULL,
  qgraph_args = list(),
  network_args = list(),
  verbose = TRUE,
  min_group_size = 30
)

Arguments

Value

A list of class "grouped_network_analysis" containing:

• networks: List of network objects per group

• network_matrices: List of adjacency matrices per group

• predictions: List of prediction results per group

• centralities: List of centrality measures per group

• qgraphs: List of qgraph plot objects per group

• group_sizes: Sample sizes per group

• failed_groups: Groups that failed estimation

Examples

## Not run: 
# Estimate networks by group
results <- estimate_grouped_networks(
  df = my_data,
  Vars = c("var1", "var2", "var3", "var4"),
  GroupVar = "group"
)

# Access results for specific group
results$networks$GroupA
results$predictions$GroupA

# Compare networks
compare_networks(results, groups = c("GroupA", "GroupB"))

## End(Not run)

Description

Estimates a single psychological network from a data frame using regularized partial correlations (via bootnet) and Mixed Graphical Models (via mgm). Provides network visualization with predictability metrics (R-squared pie charts).

Usage

estimate_single_network(
  df,
  Vars = NULL,
  layout = "circle",
  color = DEFAULT_NODE_COLOR,
  title = "Between-person network",
  default = "EBICglasso",
  var_types = NULL,
  qgraph_args = list(),
  network_args = list(),
  verbose = TRUE,
  compute_centrality = TRUE
)

Arguments

Value

A list of class "network_analysis" containing:

• network_object: Full network object from bootnet

• network_matrix: Adjacency/weight matrix

• prediction: MGM prediction results (R2, RMSE)

• centrality: Centrality measures (if compute_centrality = TRUE)

• qgraph: The qgraph plot object

• var_types: Variable types used for MGM

Examples

## Not run: 
# Basic usage
result <- estimate_single_network(
  df = my_data,
  Vars = c("var1", "var2", "var3", "var4", "var5")
)

# Access network matrix
result$network_matrix

# View predictability
result$prediction

# View centrality
result$centrality

# Custom settings
result <- estimate_single_network(
  df = my_data,
  Vars = c("var1", "var2", "var3"),
  layout = "spring",
  default = "ggmModSelect",
  var_types = c("g", "g", "c"),  # Manual type specification
  verbose = FALSE
)

## End(Not run)

Description

Input Data with Profile Assignments

Usage

## S3 method for class 'saqr_clustering'
fitted(object, ...)

Arguments

Value

The data frame passed to [clustering()], one row per input row, with 'profile' (modal assignment), 'uncertainty' and one 'posterior_profile_<k>' column per profile added. Rows dropped for missing values carry 'NA' in the added columns.

Description

Vectorized function to detect outliers for use with dplyr. For group-wise detection, use dplyr::group_by() before mutate().

Usage

is_outlier(
  x,
  method = c("zscore", "iqr", "percentile"),
  threshold = NULL,
  na.rm = TRUE
)

Arguments

Value

Logical vector indicating outliers.

Examples

## Not run: 
library(dplyr)

# Flag outliers beyond 2 SD
mtcars %>% mutate(hp_outlier = is_outlier(hp, method = "zscore", threshold = 2))

# Flag outliers at 5th/95th percentile
mtcars %>% mutate(hp_outlier = is_outlier(hp, method = "percentile", threshold = 0.05))

# Group-wise outlier detection
mtcars %>% group_by(cyl) %>% mutate(hp_outlier = is_outlier(hp))

## End(Not run)

Description

Opens an interactive Shiny application for mosaic_analysis. Upload a CSV (or use the built-in demo), pick two categorical variables, and explore the chi-square / Fisher test, Cramer's V effect size, standardized residuals, and the shaded mosaic plot. Every mosaic_analysis() option is exposed in the sidebar.

Requires the shiny and DT packages.

Usage

launch_app(...)

Arguments

Value

Called for its side effect (launches the app). No return value.

Examples

if (interactive()) {
  launch_app()
}

Description

Provides comprehensive missing data analysis including patterns, Little's MCAR test, and visualizations.

Usage

missing_analysis(
  data,
  Vars = NULL,
  pattern_plot = TRUE,
  mcar_test = TRUE,
  correlations = FALSE,
  digits = 2
)

Arguments

Value

A list containing:

• summary: gt table with missing data summary

• patterns: Data frame of missing patterns

• mcar: MCAR test results (if requested)

• plot: Missing pattern plot (if requested)

Examples

## Not run: 
# Create data with missing values
df <- mtcars
df$mpg[c(1, 5, 10)] <- NA
df$hp[c(2, 5, 15)] <- NA

missing_analysis(df)

## End(Not run)

Description

This function conducts a complete mosaic plot analysis for two categorical variables. It includes filtering by minimum count, chi-square testing (with optional Fisher's exact test), calculation of Cramer's V with effect size interpretation, and generation of a detailed summary table with observed/expected counts and residuals.

Usage

mosaic_analysis(
  data,
  var1,
  var2,
  by = NULL,
  min_count = 10,
  fontsize = 8,
  title = "",
  var1_label = NULL,
  var2_label = NULL,
  show_varnames = FALSE,
  plot_style = c("flat", "classic"),
  tile_label = c("count", "percent", "count_percent", "residual", "category", "none"),
  col_label_side = c("top", "bottom", "both", "none"),
  row_label_side = c("left", "right", "both", "none"),
  col_label_angle = 0,
  row_label_angle = 0,
  show_legend = TRUE,
  legend_position = "right",
  legend_size = 0.7,
  legend_title = "Std.\nresidual",
  label_size = 3.5,
  show_percentages = TRUE,
  percentage_base = "total",
  use_fisher = FALSE,
  by_label = NULL,
  min_stratum_n = 30,
  p_adjust = "BH",
  facet_ncol = NULL,
  facet_show_n = TRUE,
  seed = NULL,
  verbose = TRUE,
  save_plot = NULL,
  interpret = FALSE,
  ...
)

Arguments

Value

A list of class "mosaic_analysis" containing:

• plot: The mosaic plot object

• consolidated_table: Tibble with observed, expected counts and percentages

• residuals: Data frame of standardized Pearson residuals

• chi_test: Chi-square test results (or Fisher's test if use_fisher=TRUE)

• cramers_v: Cramer's V effect size value

• cramers_v_interpretation: Effect size interpretation (negligible/small/medium/large)

• stats_summary: Tibble summarizing all statistical results

• filtered_data: The filtered data used for analysis

• original_n: Original sample size before filtering

• filtered_n: Sample size after filtering

• removed_categories: List of categories removed due to min_count

When by is supplied the object additionally gains class "mosaic_stratified" and the fields strata_summary (one row per stratum: n, test, statistic, df, raw and adjusted p, Cramer's V, effect size, and the number of cells beyond |2|), strata_residuals (one row per stratum x cell), strata_table, and overall_summary (the pooled test beside the Cochran-Mantel-Haenszel test of association conditional on the stratifier). Reach these with as.data.frame, e.g. as.data.frame(fit, what = "strata").

Examples

# Create example data
set.seed(123)
example_data <- data.frame(
  gender = sample(c("Male", "Female"), 200, replace = TRUE),
  education = sample(c("High School", "Bachelor", "Master", "PhD"), 200,
                     replace = TRUE, prob = c(0.3, 0.4, 0.2, 0.1))
)

# Basic usage with quoted variable names
results <- mosaic_analysis(example_data, "gender", "education")

# Access results
results$cramers_v
results$cramers_v_interpretation
results$stats_summary


# With row percentages and custom labels
results <- mosaic_analysis(
  example_data, "gender", "education",
  min_count = 5,
  var1_label = "Gender",
  var2_label = "Education Level",
  percentage_base = "row"
)

# Using Fisher's exact test for small samples
results <- mosaic_analysis(
  example_data, "gender", "education",
  use_fisher = TRUE,
  verbose = FALSE
)

# Stratify (facet) on a third variable: one mosaic and one test per region,
# with p-values corrected across strata.
example_data$region <- sample(c("North", "South"), 200, replace = TRUE)
by_region <- mosaic_analysis(
  example_data, "gender", "education",
  by = "region", min_count = 5, min_stratum_n = 20, verbose = FALSE
)
as.data.frame(by_region, what = "strata")
as.data.frame(by_region, what = "overall")

Description

Tests and visualizes normality assumptions for numeric variables using Shapiro-Wilk test, skewness, kurtosis, and Q-Q plots.

Usage

normality_check(data, Vars, tests = TRUE, plots = TRUE, digits = 3)

Arguments

Value

A list containing:

• table: A gt table with normality statistics

• plots: Q-Q plots (if requested)

• results: Data frame with all statistics

Examples

## Not run: 
normality_check(mtcars, Vars = c("mpg", "hp", "wt"))

## End(Not run)

Description

Detects univariate and multivariate outliers using various methods including z-score (2SD, 3SD, etc.), IQR, percentile, or Mahalanobis distance.

Usage

outlier_check(
  data,
  Vars,
  method = c("zscore", "iqr", "percentile", "mahalanobis"),
  threshold = NULL,
  flag = TRUE,
  plot = TRUE
)

Arguments

Value

A list containing:

• summary: gt table with outlier summary

• data: Data frame with outlier flags (if flag = TRUE)

• outlier_indices: Row indices of outliers

• plot: Visualization (if requested)

Examples

## Not run: 
# Z-score with 3 SD threshold
outlier_check(mtcars, Vars = c("mpg", "hp"), method = "zscore", threshold = 3)

# Z-score with 2 SD threshold (more conservative)
outlier_check(mtcars, Vars = c("mpg", "hp"), method = "zscore", threshold = 2)

# IQR method
outlier_check(mtcars, Vars = c("mpg", "hp"), method = "iqr", threshold = 1.5)

# Percentile method (1st and 99th percentile)
outlier_check(mtcars, Vars = c("mpg", "hp"), method = "percentile", threshold = 0.01)

# Percentile method (5th and 95th percentile)
outlier_check(mtcars, Vars = c("mpg", "hp"), method = "percentile", threshold = 0.05)

# Mahalanobis distance (multivariate)
outlier_check(mtcars, Vars = c("mpg", "hp", "wt"), method = "mahalanobis")

## End(Not run)

Description

Pipes any R output (test results, model summaries, tables) to an AI model for scientific interpretation. Perfect for getting publication-ready interpretations of statistical results.

Usage

pass(
  x,
  prompt = NULL,
  append_prompt = NULL,
  action = c("write", "interpret", "explain", "summarize", "critique", "suggest"),
  style = c("scientific", "simple", "detailed", "brief"),
  output = c("text", "markdown", "md", "latex", "html"),
  provider = c("openai", "anthropic", "gemini", "openrouter"),
  model = NULL,
  base_url = NULL,
  api_key = NULL,
  context = NULL,
  system_message = NULL,
  auto_local = TRUE,
  copy = FALSE,
  quiet = FALSE
)

Arguments

Details

On first use, you'll be prompted to enter your API key. The key is stored in your R environment for the session. To persist it, add to your .Renviron: “' ANTHROPIC_API_KEY=your-key-here # or OPENAI_API_KEY=your-key-here “'

Value

Character string with the AI interpretation (invisibly). Also prints the interpretation.

Examples

## Not run: 
# Basic usage - pipe test results
t.test(mpg ~ am, data = mtcars) |> pass()

# With context
cor.test(mtcars$mpg, mtcars$hp) |>
  pass(context = "Studying fuel efficiency in 1974 automobiles")

# Different actions
lm(mpg ~ wt + hp, data = mtcars) |> summary() |> pass(action = "write")
chisq.test(mtcars$cyl, mtcars$am) |> pass(action = "explain", style = "simple")

# Get LaTeX output for paper
aov(mpg ~ factor(cyl), data = mtcars) |> summary() |>
  pass(action = "write", output = "latex")

# Critique an analysis
lm(mpg ~ ., data = mtcars) |> summary() |> pass(action = "critique")

# Custom prompt (REPLACES default - specific request to the AI)
my_results |> pass(prompt = "Focus only on the interaction effects")

# Add to default prompt (keeps "write methods/results" + your addition)
my_results |> pass(append_prompt = "Also mention limitations of the sample size")
my_results |> pass(action = "write", append_prompt = "Include a brief discussion section")

# Custom context (about your study)
t.test(score ~ group, data = mydata) |>
  pass(context = "RCT comparing drug vs placebo, N=200 patients with diabetes")

# Custom system message (instructions for the AI)
my_results |> pass(system_message = "Focus on clinical implications and effect sizes")

# Combine all customizations
lm(outcome ~ treatment * age, data = mydata) |> summary() |>
  pass(
    action = "write",
    context = "Phase 3 clinical trial for hypertension medication",
    system_message = "Emphasize clinical significance over statistical significance",
    prompt = "Pay special attention to the treatment-age interaction"
  )

## End(Not run)

Description

Builds figures of a clustering() result with latents, as ggplot objects. type takes any mix of plot types and groups:

• "clusters": "profiles", "bars", "heatmap", "raincloud", "parallel", "pairs", "sizes".

• "diagnostics": "entropy", "posteriors", "avepp".

• "selection": "enumeration" (information criteria across the candidates) and "tree" (how profiles split as more are added); both need more than one candidate.

• "all": every type above.

Usage

plot_clustering(results, type = "clusters", ...)

Arguments

Value

One type: a ggplot object. Several: a saqr_plots list of ggplot objects named by type, which draws every one when printed. Print, save with ggplot2::ggsave(), or restyle with + ggplot2::theme().

Errors

Raises saqrmisc_bad_input when results is not a clustering() result and saqrmisc_bad_type for an unknown type. A selection view that needs more candidates than were fitted is skipped with a message.

See Also

clustering(), clustering_plot_types()

Examples

set.seed(1)
vars <- c("Sepal.Length", "Sepal.Width", "Petal.Length", "Petal.Width")
fit <- clustering(iris, vars, n_profiles = 2:4, models = "EEE")
plot_clustering(fit, type = "profiles")
plot_clustering(fit, type = "diagnostics")
plot_clustering(fit, type = c("pairs", "tree"))

Description

Re-renders the mosaic plot from a fitted mosaic_analysis object using the stored contingency table and residuals, so styling can be changed without re-running the statistical test. Any styling argument accepted by mosaic_analysis (e.g. plot_style, tile_label, col_label_side, legend_size) can be overridden via ...; unspecified arguments keep the values from the original call.

Usage

## S3 method for class 'mosaic_analysis'
plot(x, ...)

Arguments

Value

Invisibly, the plot object (a ggplot for the flat style). Called for its side effect of drawing the plot.

Examples

set.seed(1)
d <- data.frame(
  a = sample(c("X", "Y", "Z"), 200, replace = TRUE),
  b = sample(c("P", "Q"), 200, replace = TRUE)
)
res <- mosaic_analysis(d, "a", "b", min_count = 5, verbose = FALSE)

plot(res, tile_label = "percent", legend_size = 0.4)
plot(res, plot_style = "classic")

Description

Plot Method for Clustering Results

Usage

## S3 method for class 'saqr_clustering'
plot(x, type = "clusters", ...)

Arguments

Value

As [plot_clustering()]: a ggplot object, or a 'saqr_plots' list.

Description

Print method for grouped_network_analysis objects

Usage

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

Arguments

Description

Print method for html tables

Usage

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

Arguments

Description

Print method for latex tables

Usage

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

Arguments

Description

Print method for markdown tables

Usage

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

Arguments

Description

Print method for mosaic_analysis objects

Usage

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

Arguments

Description

Print method for stratified mosaic_analysis objects

Usage

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

Arguments

Value

Invisibly, x. Called for its side effect of printing.

Description

Print method for network_analysis objects

Usage

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

Arguments

Description

Print a Clustering Result

Usage

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

Arguments

Value

'x', invisibly.

Description

Print Several Clustering Plots

Usage

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

Arguments

Value

'x', invisibly. Called for the side effect of drawing each plot.

Description

Print method for saqr_result

Usage

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

Arguments

Description

Imputes missing values using various methods including mean, median, mode, or custom values.

Usage

replace_missing(
  data,
  Vars,
  method = c("mean", "median", "mode", "zero", "min", "max", "value"),
  value = NULL,
  group_by = NULL,
  suffix = NULL
)

Arguments

Value

Data frame with imputed values.

Examples

## Not run: 
df <- mtcars
df$mpg[c(1, 5, 10)] <- NA

# Replace with mean
df_imputed <- replace_missing(df, Vars = "mpg", method = "mean")

# Replace with median, create new column
df_imputed <- replace_missing(df, Vars = "mpg", method = "median", suffix = "_imp")

# Group-wise mean imputation
df_imputed <- replace_missing(df, Vars = "mpg", method = "mean", group_by = "cyl")

## End(Not run)

Description

Replaces detected outliers with specified values such as NA, mean, median, or winsorized values. Supports multiple detection methods.

Usage

replace_outliers(
  data,
  Vars,
  detect = c("zscore", "iqr", "percentile"),
  threshold = NULL,
  replace_with = c("NA", "mean", "median", "winsorize", "boundary"),
  suffix = NULL
)

Arguments

Details

Detection methods:

• "zscore": Values beyond threshold SDs from mean. Common thresholds: 2, 2.5, 3, 3.29

• "iqr": Values beyond Q1/Q3 +/- threshold*IQR. Common thresholds: 1.5, 3

• "percentile": Values below or above percentile cutoffs. E.g., 0.01 = 1st/99th, 0.05 = 5th/95th

Replacement methods:

• "NA": Set outliers to NA

• "mean": Replace with mean of non-outliers

• "median": Replace with median of non-outliers

• "winsorize": Cap at threshold boundary

• "boundary": Replace with nearest non-outlier value

Value

Data frame with outliers replaced.

Examples

## Not run: 
df <- mtcars

# Replace outliers beyond 2 SD with NA
df_clean <- replace_outliers(df, Vars = "hp",
                             detect = "zscore", threshold = 2,
                             replace_with = "NA")

# Winsorize at 3 SD
df_clean <- replace_outliers(df, Vars = "hp",
                             detect = "zscore", threshold = 3,
                             replace_with = "winsorize")

# Replace outliers at 5th/95th percentile with median
df_clean <- replace_outliers(df, Vars = "hp",
                             detect = "percentile", threshold = 0.05,
                             replace_with = "median")

# IQR-based winsorization
df_clean <- replace_outliers(df, Vars = c("mpg", "hp"),
                             detect = "iqr", replace_with = "winsorize")

## End(Not run)

Description

Reverse codes numeric variables, commonly used for Likert scales where some items are negatively worded. Uses the formula: reversed = (max + min) - original.

Usage

reverse_code(data, Vars, min = NULL, max = NULL, suffix = "_r")

Arguments

Details

The reverse coding formula is: reversed = (max + min) - original

For a 1-5 Likert scale:

• 1 becomes 5

• 2 becomes 4

• 3 stays 3

• 4 becomes 2

• 5 becomes 1

If min/max are not specified, they are detected from the data. For Likert scales, it's recommended to explicitly specify min and max to ensure correct reversal even if extreme values are not present in the data.

Value

Data frame with reverse coded variables added.

Examples

## Not run: 
# Create sample Likert data
df <- data.frame(
  item1 = c(1, 2, 3, 4, 5),
  item2 = c(5, 4, 3, 2, 1),  # reverse-worded
  item3 = c(2, 3, 4, 3, 2)
)

# Reverse code with automatic detection
df <- reverse_code(df, Vars = "item2")

# Reverse code with explicit scale (1-5 Likert)
df <- reverse_code(df, Vars = "item2", min = 1, max = 5)

# Reverse code multiple items
df <- reverse_code(df, Vars = c("item2", "item3"), min = 1, max = 5)

# 0-10 scale
df <- reverse_code(df, Vars = "item2", min = 0, max = 10)

## End(Not run)

Description

Vectorized reverse coding for use with dplyr mutate and across.

Usage

reverse_code_vec(x, min = NULL, max = NULL, na.rm = TRUE)

Arguments

Details

The reverse coding formula is: reversed = (max + min) - original

For Likert scales, always specify min and max explicitly to ensure correct reversal even when extreme values are not present in the data.

Value

Reverse coded numeric vector.

Examples

## Not run: 
library(dplyr)

df <- data.frame(
  item1 = c(1, 2, 3, 4, 5),
  item2 = c(5, 4, 3, 2, 1),
  item3 = c(2, 3, 4, 3, 2)
)

# Reverse single variable (auto-detect scale)
df %>% mutate(item2_r = reverse_code_vec(item2))

# Reverse with explicit 1-5 scale
df %>% mutate(item2_r = reverse_code_vec(item2, min = 1, max = 5))

# Reverse multiple variables
df %>% mutate(across(c(item2, item3), ~reverse_code_vec(.x, min = 1, max = 5), .names = "{.col}_r"))

# 0-10 scale
df %>% mutate(item2_r = reverse_code_vec(item2, min = 0, max = 10))

# 1-7 Likert scale
df %>% mutate(item2_r = reverse_code_vec(item2, min = 1, max = 7))

## End(Not run)

Description

Creates a standardized result object for Saqrmisc functions that includes both the original data and a clean markdown representation for AI interpretation.

Usage

saqr_result(data = NULL, table = NULL, type = "analysis", markdown = NULL, ...)

Arguments

Value

A list with class "saqr_result" containing data, table, markdown, and other components

Description

Scales numeric variables by dividing by standard deviation or rescaling to a specified range. Supports group-wise scaling.

Usage

scale_vars(
  data,
  Vars,
  method = c("sd", "range"),
  range = c(0, 1),
  suffix = "_s",
  group_by = NULL
)

Arguments

Value

Data frame with scaled variables added.

Examples

## Not run: 
# Scale by SD
df <- scale_vars(mtcars, Vars = c("mpg", "hp"), method = "sd")

# Min-max scaling (0-1)
df <- scale_vars(mtcars, Vars = "mpg", method = "range")

# Scale to 1-10 range
df <- scale_vars(mtcars, Vars = "mpg", method = "range", range = c(1, 10))

# Group-wise scaling
df <- scale_vars(mtcars, Vars = "mpg", method = "sd", group_by = "cyl")

## End(Not run)

Description

Vectorized scaling function for use with dplyr mutate and across. For group-wise scaling, use dplyr::group_by() before mutate().

Usage

scale_vec(x, method = c("sd", "range"), range = c(0, 1), na.rm = TRUE)

Arguments

Value

Scaled numeric vector.

Examples

## Not run: 
library(dplyr)

# Scale by SD
mtcars %>% mutate(mpg_s = scale_vec(mpg, method = "sd"))

# Scale to 1-10
mtcars %>% mutate(mpg_s = scale_vec(mpg, method = "range", range = c(1, 10)))

# Multiple variables to 0-100
mtcars %>% mutate(across(c(mpg, hp), ~scale_vec(.x, method = "range", range = c(0, 100))))

# Group-wise scaling
mtcars %>% group_by(cyl) %>% mutate(mpg_s = scale_vec(mpg, method = "sd"))

## End(Not run)

Description

Set your API key and optional default settings for the current R session. Settings are stored as R options and used as defaults by 'pass()'.

Usage

set_api_key(
  key,
  provider = c("openai", "anthropic", "gemini", "openrouter"),
  model = NULL,
  ...
)

Arguments

Value

Invisibly returns TRUE.

Examples

## Not run: 
# Just set the key
set_api_key("sk-...", "openai")

# Set key and default model
set_api_key("sk-...", "openai", model = "gpt-4o")

# Set key with custom base URL (for Azure OpenAI, etc.)
set_api_key("sk-...", "openai", model = "gpt-4", base_url = "https://my-azure.openai.azure.com")

## End(Not run)

Description

Convenience alias for 'set_api_key(key, "anthropic", ...)'.

Usage

set_claude_key(key, model = NULL, ...)

Arguments

Examples

## Not run: 
set_claude_key("sk-ant-...")
set_claude_key("sk-ant-...", model = "claude-sonnet-4-20250514")

## End(Not run)

Description

Convenience alias for 'set_api_key(key, "gemini", ...)'.

Usage

set_gemini_key(key, model = NULL, ...)

Arguments

Examples

## Not run: 
set_gemini_key("AIza...")
set_gemini_key("AIza...", model = "gemini-2.5-pro")

## End(Not run)

Description

Convenience alias for 'set_api_key(key, "openai", ...)'.

Usage

set_openai_key(key, model = NULL, ...)

Arguments

Examples

## Not run: 
set_openai_key("sk-...")
set_openai_key("sk-...", model = "gpt-4o")
set_openai_key("sk-...", model = "gpt-4", base_url = "https://my-azure.openai.azure.com")

## End(Not run)

Description

Convenience alias for 'set_api_key(key, "openrouter", ...)'.

Usage

set_openrouter_key(key, model = NULL, ...)

Arguments

Examples

## Not run: 
set_openrouter_key("sk-or-...")
set_openrouter_key("sk-or-...", model = "openai/gpt-4o")

## End(Not run)

Description

Standardizes numeric variables to z-scores (mean = 0, SD = 1). Supports group-wise standardization for multilevel/nested data.

Usage

standardize(data, Vars, suffix = "_z", group_by = NULL)

Arguments

Value

Data frame with standardized variables added.

Examples

## Not run: 
# Simple standardization
df <- standardize(mtcars, Vars = c("mpg", "hp"))

# Group-wise standardization
df <- standardize(mtcars, Vars = "mpg", group_by = "cyl")

## End(Not run)

Description

Vectorized standardization function for use with dplyr mutate and across. For group-wise standardization, use dplyr::group_by() before mutate().

Usage

standardize_vec(x, na.rm = TRUE)

Arguments

Value

Standardized numeric vector (mean = 0, SD = 1).

Examples

## Not run: 
library(dplyr)

# Single variable
mtcars %>% mutate(mpg_z = standardize_vec(mpg))

# Multiple variables
mtcars %>% mutate(across(c(mpg, hp, wt), standardize_vec, .names = "{.col}_z"))

# Group-wise standardization
mtcars %>% group_by(cyl) %>% mutate(mpg_z = standardize_vec(mpg))

## End(Not run)

Description

Summary method for mosaic_analysis objects

Usage

## S3 method for class 'mosaic_analysis'
summary(object, ...)

Arguments

Description

Summary method for stratified mosaic_analysis objects

Usage

## S3 method for class 'mosaic_stratified'
summary(object, ...)

Arguments

Value

Invisibly, the per-stratum summary data.frame.

Description

Summary method for network_analysis objects

Usage

## S3 method for class 'network_analysis'
summary(object, ...)

Arguments

Description

Compare the Candidate Models of a Clustering Result

Usage

## S3 method for class 'saqr_clustering'
summary(object, ...)

Arguments

Value

A data.frame with one row per candidate (profiles x covariance model): 'n_profiles', 'model', 'log_likelihood', 'n_parameters', 'aic', 'bic', 'icl', 'entropy' (relative), 'converged', 'boundary', 'delta_bic' (distance from the selected model) and 'selected'.

Description

Extracts the underlying data frame from various table objects including gt tables, kable objects, and matrices.

Usage

to_dataframe(x, digits = NULL)

Arguments

Value

A data frame.

Examples

## Not run: 
# Extract data from a gt table
library(gt)
gt_table <- gt(mtcars[1:5, 1:3])
df <- to_dataframe(gt_table)

# Works with matrices too
mat <- matrix(1:6, nrow = 2)
to_dataframe(mat)

## End(Not run)