Package 'mariposa'

Description

ancova() tests whether group means differ after controlling for one or more continuous covariates. It performs a factorial ANCOVA using Type III Sum of Squares, matching SPSS UNIANOVA output with the WITH keyword.

Think of it as:

• An ANOVA that removes the effect of confounding variables first

• Testing group differences on "adjusted" means

• Combining regression (covariates) and ANOVA (factors) in one model

The test tells you:

• Whether each factor has a significant effect AFTER controlling for covariates

• The relationship between each covariate and the outcome

• Effect sizes for factors and covariates (partial eta squared)

• Estimated marginal means (group means adjusted for covariates)

Usage

ancova(data, dv, between, covariate, weights = NULL, ss_type = 3)

Arguments

Details

Understanding the Results

Adjusted Means (Estimated Marginal Means): These are the group means after statistically removing the effect of the covariate(s). They answer: "What would the group means be if all groups had the same covariate values?"

Covariate Effects: The covariate row in the ANOVA table shows whether the covariate significantly predicts the DV after adjusting for the factors.

Factor Effects: These show whether the factor affects the DV after controlling for the covariate. This is the primary test of interest.

Partial Eta Squared (Effect Size):

• Less than 0.01: Negligible

• 0.01 to 0.06: Small

• 0.06 to 0.14: Medium

• 0.14 or greater: Large

When to Use This

Use ANCOVA when:

• You have group comparisons (ANOVA) but want to control for a confound

• Your covariate is continuous and linearly related to the DV

• You want to increase statistical power by removing known variance sources

• The covariate's relationship with the DV is the same across groups (homogeneity of regression slopes assumption)

Value

An object of class "ancova" containing:

anova_table

Tibble with Source, SS, df, MS, F, p, Partial Eta Squared

parameter_estimates

Tibble with regression coefficients (B, SE, t, p, CI, partial eta squared) in SPSS coding: one row per category, the last category of each factor is the reference and reported as a redundant 0 (redundant = TRUE)

descriptives

Tibble with unadjusted cell means, SDs, and Ns

estimated_marginal_means

Tibble with adjusted cell means (covariates at grand mean)

emm_main_effects

For 2+ factors: named list of tibbles with the adjusted main-effect means (unweighted average of the cell means, as SPSS /EMMEANS=TABLES(factor)); NULL for one factor

levene_test

Tibble with Levene's test of equality of error variances (f, df1, df2, p): as in SPSS UNIANOVA, a one-way ANOVA of the absolute residuals of the ANCOVA model across the cells of the design. Also available as levene_test(result).

r_squared

R-squared and Adjusted R-squared

model

The underlying lm model object

call_info

List with metadata (dv, factors, covariates, weighted, etc.)

Use summary() for the full SPSS-style output with toggleable sections. For data grouped with group_by(), one ANCOVA is computed per group: the tables carry the group keys as leading columns and group_results holds the complete result of each group (NULL, with a warning, for a group that cannot be analysed).

References

Huitema, B. E. (2011). The Analysis of Covariance and Alternatives (2nd ed.). Wiley.

IBM Corp. (2023). IBM SPSS Statistics 29 Algorithms. IBM Corporation.

See Also

factorial_anova for ANOVA without covariates.

linear_regression for regression analysis.

oneway_anova for single-factor ANOVA.

summary.ancova for detailed output with toggleable sections.

Other hypothesis_tests: binomial_test(), chi_square(), chisq_gof(), factorial_anova(), fisher_test(), friedman_test(), kruskal_wallis(), mann_whitney(), mcnemar_test(), oneway_anova(), t_test(), wilcoxon_test()

Examples

# Load required packages and data
library(dplyr)
data(survey_data)

# One-way ANCOVA: income by education, controlling for age
survey_data %>%
  ancova(dv = income, between = c(education), covariate = c(age))

# Two-way ANCOVA with weights
survey_data %>%
  ancova(dv = income, between = c(gender, education),
         covariate = c(age), weights = sampling_weight)

# Multiple covariates
survey_data %>%
  ancova(dv = income, between = c(education),
         covariate = c(age, political_orientation))

# --- Three-layer output ---
result <- ancova(survey_data, dv = income, between = c(education),
                 covariate = c(age))
result              # compact overview
summary(result)     # full detailed output with all sections
summary(result, marginal_means = FALSE)  # hide estimated marginal means

Description

For listwise + ungrouped results, dispatches to stats::anova.lm (sequential Type-I sum of squares per term). For the SPSS-style overall-model ANOVA table, use object$anova_table.

Usage

## S3 method for class 'linear_regression'
anova(object, ...)

Arguments

Value

An anova table (sequential Type-I sums of squares), as returned by stats::anova.lm.

Description

For ungrouped results, dispatches to stats::anova.glm (sequential deviance per term). For the SPSS-style omnibus chi-square test, use object$omnibus_test.

Usage

## S3 method for class 'logistic_regression'
anova(object, ...)

Arguments

Value

An anova table (sequential analysis of deviance per term), as returned by stats::anova.glm.

Description

Turns the result of any mariposa analysis into a plain data frame that can be saved with utils::write.csv(), combined with dplyr::bind_rows() or used for plotting. tibble::as_tibble() works the same way (it calls as.data.frame()), write_xlsx() writes the table (plus the secondary tables SPSS shows next to it) to Excel, and with the broom package loaded, broom::tidy() returns the table with broom's column names.

Usage

## S3 method for class 'ancova'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

## S3 method for class 'binomial_test'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

## S3 method for class 'chi_square'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

## S3 method for class 'chisq_gof'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

## S3 method for class 'codebook'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

## S3 method for class 'crosstab'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

## S3 method for class 'describe'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

## S3 method for class 'dunn_test'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

## S3 method for class 'efa'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

## S3 method for class 'factorial_anova'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

## S3 method for class 'fisher_test'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

## S3 method for class 'frequency'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

## S3 method for class 'friedman_test'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

## S3 method for class 'kendall_tau'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

## S3 method for class 'kruskal_wallis'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

## S3 method for class 'levene_test'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

## S3 method for class 'linear_regression'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

## S3 method for class 'logistic_regression'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

## S3 method for class 'mann_whitney'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

## S3 method for class 'marginal_effects'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

## S3 method for class 'mcnemar_test'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

## S3 method for class 'multiple_response'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

## S3 method for class 'normality_test'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

## S3 method for class 'oneway_anova'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

## S3 method for class 'pairwise_wilcoxon'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

## S3 method for class 'partial_cor'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

## S3 method for class 'pearson_cor'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

## S3 method for class 'reliability'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

## S3 method for class 'scheffe_test'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

## S3 method for class 'spearman_rho'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

## S3 method for class 't_test'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

## S3 method for class 'tukey_test'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

## S3 method for class 'w_iqr'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

## S3 method for class 'w_kurtosis'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

## S3 method for class 'w_mean'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

## S3 method for class 'w_median'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

## S3 method for class 'w_modus'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

## S3 method for class 'w_quantile'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

## S3 method for class 'w_range'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

## S3 method for class 'w_sd'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

## S3 method for class 'w_se'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

## S3 method for class 'w_skew'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

## S3 method for class 'w_var'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

## S3 method for class 'wilcoxon_test'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

Arguments

Details

broom::tidy() (available once broom is loaded) renames the common columns to broom's conventions: statistic, p.value, parameter (or num.df/den.df for F tests), estimate, conf.low, conf.high, std.error, adj.p.value (post-hoc tests), term (ANOVA tables), plus method and, where it applies, alternative. normality_test() results are tidied to one row per variable and test. The regressions keep their own tidy(), glance() and augment() methods.

Value

A plain data.frame (no list-columns, no row names) holding the main result table:

• one row per variable (per test) for tests and descriptive statistics, with the columns of x$results; group-level details stored as list-columns are flattened into columns (for example group1, group2, mean1, mean2 for t_test()) or dropped (the observed/expected tables of chi_square());

• one row per pair for correlations and post-hoc tests;

• one row per term for ANOVA tables and regression coefficients, and one row per item for efa() loadings;

• one row per cell for crosstab() and per category for frequency() (summary rows dropped, a missing column flags missing values);

• one row per scale for reliability().

For grouped analyses (dplyr::group_by()) the grouping variables are the leading columns; labelled grouping variables show their value labels.

See Also

write_xlsx() for Excel export of results.

Examples

tt <- t_test(survey_data, age, income, group = gender)
as.data.frame(tt)

# Grouped analyses get the grouping variables as leading columns
survey_data |>
  dplyr::group_by(region) |>
  describe(age, income) |>
  as.data.frame()

# One row per cell of a crosstab
as.data.frame(crosstab(survey_data, gender, region))

# Save as CSV or convert to a tibble
csv <- tempfile(fileext = ".csv")
utils::write.csv(as.data.frame(tt), csv, row.names = FALSE)
tibble::as_tibble(chi_square(survey_data, gender, region))
unlink(csv)

# broom-style columns
if (requireNamespace("broom", quietly = TRUE)) {
  broom::tidy(oneway_anova(survey_data, age, group = education))
}

Description

binomial_test() tests whether the observed proportion of a binary variable differs from a hypothesized proportion. It uses the exact binomial test, making it valid for any sample size.

Think of it as:

• Testing whether a coin is fair (proportion of heads = 50 percent)

• Checking if your sample's gender ratio matches the population

• Verifying if satisfaction rates meet a target proportion

The test tells you:

• Whether the observed proportion differs significantly from the expected

• The exact p-value (based on the binomial distribution)

• A confidence interval for the true proportion

Usage

binomial_test(data, ..., p = 0.5, weights = NULL, conf.level = 0.95)

Arguments

Details

Understanding the Results

P-value: If p < 0.05, the proportion differs significantly from the test proportion

• p < 0.001: Very strong evidence the proportion differs

• p < 0.01: Strong evidence the proportion differs

• p < 0.05: Moderate evidence the proportion differs

• p > 0.05: No significant difference from expected proportion

Observed Proportion: The actual proportion in your data. Compare this with the test proportion to see the direction of any difference.

Confidence Interval: The range likely to contain the true population proportion. If the test proportion falls outside this range, the result is significant.

When to Use This

Use the binomial test when:

• You want to compare an observed proportion to a known value

• Your variable has exactly 2 categories

• You need an exact test (not relying on normal approximation)

• Sample size is small (where chi-square may not be reliable)

Relationship to Other Tests

• For testing association between two categorical variables: Use chi_square() instead

• For comparing proportions between groups: Use chi-square or z-test for proportions

• For larger samples with normal approximation: results will be very similar to a one-sample z-test for proportions

Group 1 and one-tailed tests

As in SPSS NPAR TESTS /BINOMIAL, Group 1 is the category of the first valid case in the data (per group with group_by()), and p is its hypothesized proportion. For p = 0.5 the p-value is two-tailed. For any other p SPSS reports a one-tailed p-value in the direction of the observed proportion ("the proportion of cases in the first group < p"); binomial_test() does the same. To test the other category, put a case of it first or use 1 - p.

Weighted variants

SPSS NPAR TESTS ignores WEIGHT BY, so weighted results have no SPSS reference. The weighted variant is an R-only frequency-weight extension that reduces exactly to the unweighted test when all weights equal 1 (enforced by an internal invariance suite); see vignette("spss-compatibility") for validation status.

Value

Test results showing whether the proportion differs from expected, including:

• Category counts and observed proportions

• Test proportion (null hypothesis)

• Exact p-value (two-tailed for p = 0.5, otherwise one-tailed; column alternative: "two.sided", "less" or "greater")

• Confidence interval for the true proportion of Group 1 (Clopper-Pearson)

References

Conover, W. J. (1999). Practical nonparametric statistics (3rd ed.). John Wiley & Sons.

See Also

binom.test for the base R exact binomial test.

chi_square for testing associations between categorical variables.

Other hypothesis_tests: ancova(), chi_square(), chisq_gof(), factorial_anova(), fisher_test(), friedman_test(), kruskal_wallis(), mann_whitney(), mcnemar_test(), oneway_anova(), t_test(), wilcoxon_test()

Examples

# Load required packages and data
library(dplyr)
data(survey_data)

# Test whether gender split is 50/50
survey_data %>%
  binomial_test(gender, p = 0.50)

# Test whether East region proportion is 50%
survey_data %>%
  binomial_test(region, p = 0.50)

# Multiple variables at once
survey_data %>%
  binomial_test(gender, region, p = 0.50)

# Weighted analysis
survey_data %>%
  binomial_test(gender, p = 0.50, weights = sampling_weight)

# Grouped analysis (separate test per region)
survey_data %>%
  group_by(region) %>%
  binomial_test(gender, p = 0.50)

Description

Centers variables by subtracting the mean. When used on a grouped data frame (via dplyr::group_by()), this becomes group-mean centering — the R equivalent of separate centering within each group.

Usage

center(data, ..., weights = NULL, suffix = NULL, na.rm = TRUE)

Arguments

Details

Grand-Mean vs. Group-Mean Centering

• Grand-mean centering (ungrouped): Subtracts the overall mean. A centered value of 0 means the respondent is at the sample average.

• Group-mean centering (grouped): Subtracts the group mean. Useful in multilevel models to separate within-group and between-group effects. This replaces sjmisc's separate de_mean() function.

Weighted Centering

When weights is provided, the weighted mean is used for centering. This accounts for survey design in the centering computation.

Missing Values

The result is a plain numeric variable (value labels are dropped, the variable label is kept with " (centered)" appended). Missing values of imported data, including their SPSS missing types, become plain NA, as in an SPSS COMPUTE.

Value

If data is a vector, a centered numeric vector. If data is a data frame, the modified data frame (invisibly).

See Also

std() for full standardization (centering + scaling)

Other transform: std()

Examples

library(dplyr)
data(survey_data)

# Grand-mean centering
data <- center(survey_data, income, age, suffix = "_c")

# Weighted centering
data <- center(survey_data, income, age,
               weights = sampling_weight, suffix = "_c")

# Group-mean centering (replaces sjmisc::de_mean)
data <- survey_data %>%
  group_by(region) %>%
  center(income, age, suffix = "_gmc")

Description

chi_square() helps you discover if two categorical variables are related or independent. For example, is education level related to voting preference? Or are they independent of each other?

The test tells you:

• Whether the relationship is statistically significant

• How strong the relationship is (effect sizes)

• What patterns exist in your data

Usage

chi_square(data, ..., weights = NULL, correct = FALSE)

Arguments

Details

Understanding the Results

P-value: If p < 0.05, the variables are likely related (not independent)

• p < 0.001: Very strong evidence of relationship

• p < 0.01: Strong evidence of relationship

• p < 0.05: Moderate evidence of relationship

• p >= 0.05: No significant relationship found

Effect Sizes (How strong is the relationship?):

• Cramer's V: Works for any table size (0 = no relationship, 1 = perfect relationship)

  • < 0.1: Negligible relationship

  • 0.1-0.3: Small relationship

  • 0.3-0.5: Medium relationship

  • 0.5 or higher: Large relationship

• Phi: sqrt(chi-squared / N). Reported for every table, as SPSS does; in a 2x2 table it equals Cramer's V, in larger tables it can exceed 1 (use Cramer's V there)

• Gamma: For two ordinal variables (-1 to +1, shows the direction of the relationship). Shown by summary() only when both variables are ordered factors or numeric; for nominal variables its sign depends on the arbitrary category order. goodman_gamma() always computes it.

When to Use This

Use chi-squared test when:

• Both variables are categorical (gender, region, education level, etc.)

• You want to know if they're related or independent

• You have at least 5 observations in most cells

Reading the Frequency Tables

• Observed: What you actually found in your data

• Expected: What you'd expect if variables were independent

• Large differences suggest a relationship exists

Tips for Success

• Check that most cells have at least 5 observations

• Use weights for population estimates

• Look at both significance (p-value) and strength (effect sizes)

• Consider using crosstab() for detailed percentage breakdowns

Value

Test results showing whether the variables are related, including:

• Chi-squared statistic and p-value

• Observed vs expected frequencies

• Effect sizes to measure relationship strength Use summary() for the full SPSS-style output with toggleable sections.

References

Pearson, K. (1900). On the criterion that a given system of deviations from the probable in the case of a correlated system of variables is such that it can be reasonably supposed to have arisen from random sampling. Philosophical Magazine, 50(302), 157–175.

Cramer, H. (1946). Mathematical Methods of Statistics. Princeton University Press.

IBM Corp. (2023). IBM SPSS Statistics 29 Algorithms. IBM Corporation.

See Also

chisq.test for the base R chi-squared test.

crosstab for detailed cross-tabulation tables.

frequency for single-variable frequency tables.

summary.chi_square for detailed output with toggleable sections.

Other hypothesis_tests: ancova(), binomial_test(), chisq_gof(), factorial_anova(), fisher_test(), friedman_test(), kruskal_wallis(), mann_whitney(), mcnemar_test(), oneway_anova(), t_test(), wilcoxon_test()

Examples

# Load required packages and data
library(dplyr)
data(survey_data)

# Basic chi-squared test for independence
survey_data %>% chi_square(gender, region)

# With weights
survey_data %>% chi_square(gender, education, weights = sampling_weight)

# Grouped analysis
survey_data %>% 
  group_by(region) %>% 
  chi_square(gender, employment)

# With continuity correction
survey_data %>% chi_square(gender, region, correct = TRUE)

# --- Three-layer output ---
result <- chi_square(survey_data, gender, education)
result              # compact one-line overview
summary(result)     # full detailed output with all sections
summary(result, cross_tabulation = FALSE)  # hide cross-tabulation

Description

chisq_gof() tests whether observed frequencies of a categorical variable match expected frequencies. By default, it tests against equal proportions (uniform distribution). You can also specify custom expected proportions.

Think of it as:

• Testing whether categories are equally distributed

• Comparing observed distribution to a theoretical distribution

• The one-sample version of the chi-square test

The test tells you:

• Whether observed frequencies differ from expected frequencies

• How strong the deviation is (chi-square statistic)

• A frequency table with observed, expected, and residual counts

Usage

chisq_gof(data, ..., expected = NULL, weights = NULL)

Arguments

Details

Understanding the Results

P-value: If p < 0.05, the distribution differs from expected

• p < 0.001: Very strong evidence the distribution differs

• p < 0.01: Strong evidence the distribution differs

• p < 0.05: Moderate evidence the distribution differs

• p >= 0.05: No significant deviation from expected distribution

Residuals: The difference between observed and expected counts. Large positive residuals indicate a category has more cases than expected; large negative residuals indicate fewer cases than expected.

When to Use This

Use this test when:

• You want to check whether a categorical variable follows a specific distribution

• You want to test if categories are equally distributed (uniform)

• You have a single categorical variable and a hypothesised distribution

The Chi-Square Goodness-of-Fit Statistic

$\chi^2 = \sum \frac{(O_i - E_i)^2}{E_i}$

where O_i = observed frequency, E_i = expected frequency.

Degrees of freedom = number of categories - 1.

Relationship to Other Tests

• For testing association between two categorical variables: Use chi_square() instead

• For testing a single binary proportion: Use binomial_test() instead

• For small samples where expected frequencies are below 5: Use fisher_test() instead

SPSS Equivalent

SPSS: NPAR TESTS /CHISQUARE=variable /EXPECTED=EQUAL or: NPAR TESTS /CHISQUARE=variable /EXPECTED=50 30 20

Value

Test results showing whether observed frequencies match expected, including:

• Chi-square statistic (chi_squared) and p-value for each variable

• Degrees of freedom

• Frequency table with observed, expected, and residual counts (frequencies; expected counts and residuals unrounded, printed with one decimal like SPSS; for grouped data one long table with the group columns and Variable)

• Sample size (N)

References

Pearson, K. (1900). On the criterion that a given system of deviations from the probable in the case of a correlated system of variables is such that it can be reasonably supposed to have arisen from random sampling. Philosophical Magazine, 50(302), 157-175.

See Also

chi_square for chi-square test of independence (two variables).

binomial_test for testing a single proportion.

Other hypothesis_tests: ancova(), binomial_test(), chi_square(), factorial_anova(), fisher_test(), friedman_test(), kruskal_wallis(), mann_whitney(), mcnemar_test(), oneway_anova(), t_test(), wilcoxon_test()

Examples

# Load required packages and data
library(dplyr)
data(survey_data)

# Test whether gender is equally distributed
survey_data %>%
  chisq_gof(gender)

# Test multiple variables at once
survey_data %>%
  chisq_gof(gender, region, education)

# Custom expected proportions
survey_data %>%
  chisq_gof(interview_mode, expected = c(0.5, 0.3, 0.2))

# With weights
survey_data %>%
  chisq_gof(gender, weights = sampling_weight)

# Grouped analysis
survey_data %>%
  group_by(region) %>%
  chisq_gof(education)

Description

codebook() creates an interactive HTML data dictionary that opens in the RStudio Viewer. It shows you everything about your dataset at a glance: variable names, types, labels, the empirical values found in the data, value labels, and frequency counts.

Think of it as a professional "cheat sheet" for your dataset – especially useful when working with labelled survey data imported from SPSS, Stata, or SAS.

Usage

codebook(
  data,
  ...,
  weights = NULL,
  show_id = TRUE,
  show_type = TRUE,
  show_labels = TRUE,
  show_values = TRUE,
  show_freq = TRUE,
  show_na = TRUE,
  show_unused = FALSE,
  max_values = 10,
  max_len = 50,
  sort_by_name = FALSE,
  file = NULL,
  view = interactive()
)

Arguments

Details

What the Codebook Shows

For each variable, the codebook displays (depending on options):

• ID: Column position in the dataset

• Name: Variable name (in monospace font)

• Type: Data type (numeric, factor, ordered factor, haven_labelled, etc.)

• Label: Variable label (from SPSS/Stata/SAS imports or manual assignment)

• Values: The empirical values found in the data

• Value Labels: Labels assigned to those values (if any)

• Freq.: Frequency count for each value

When to Use This

Use codebook() when you:

• First receive a new dataset and want to understand its structure

• Work with labelled data (SPSS, Stata, SAS) and need to see all value labels

• Want to document your dataset for colleagues or publications

• Need to quickly see value distributions across variables

In R Markdown and Quarto

A chunk containing codebook(data) embeds the HTML codebook in HTML output (its styles only apply to the codebook, not to the rest of the document); PDF and Word output show the compact console overview. Use write_xlsx() for an Excel version of the codebook.

Value

A list of class "codebook". Printing it shows a compact console overview; in a knitted HTML document (R Markdown, Quarto) the full HTML codebook is embedded, in other formats the overview is shown. The list contains:

codebook

Tibble with one row per variable and all metadata

data_info

List with dataset-level information (name, nrow, ncol, etc.)

html

The generated HTML as an htmltools object

weights

Name of the weight variable, or NULL

options

List of all display options

frequencies

Named list of frequency tables per variable

See Also

describe() for detailed numeric summaries, frequency() for detailed frequency tables, read_spss(), read_por(), read_stata(), read_sas(), read_xpt() for importing data with tagged NAs

Examples

data(survey_data)

# Compact console overview (no Viewer)
cb <- codebook(survey_data)
print(cb)

# Detailed console output
summary(cb)


# Full codebook (opens in RStudio Viewer when interactive)
codebook(survey_data)

# Only trust-related variables
codebook(survey_data, starts_with("trust"))

# Save to file for sharing
codebook(survey_data, file = tempfile(fileext = ".html"))

Description

The unstandardized coefficients B. Also available for pairwise results (taken from the coefficients table); grouped results hold one model per group in $groups.

Usage

## S3 method for class 'linear_regression'
coef(object, ...)

Arguments

Value

A named numeric vector.

Description

t-based intervals for B. For weighted models they use the SPSS frequency-weight standard errors and df (sum(w) - rank) and equal the CI columns of summary().

Usage

## S3 method for class 'linear_regression'
confint(object, parm, level = 0.95, ...)

Arguments

Value

A matrix with one row per coefficient and columns for the lower and upper limits.

Description

Confidence intervals for the coefficients B (log-odds scale) of a logistic_regression model.

The default method = "wald" gives Wald intervals ($B \pm z_{1-\alpha/2} \cdot SE$), the interval SPSS LOGISTIC REGRESSION reports as "95\ summary() prints: exp(confint(model)) reproduces the Lower/Upper columns of the coefficients table. method = "profile" gives the profile-likelihood intervals of stats::confint() for glm objects.

Usage

## S3 method for class 'logistic_regression'
confint(object, parm, level = 0.95, method = c("wald", "profile"), ...)

Arguments

Value

A matrix with one row per coefficient and columns for the lower and upper limits (log-odds scale).

Examples

survey_data$high_satisfaction <- as.integer(survey_data$life_satisfaction >= 4)
model <- logistic_regression(survey_data, high_satisfaction ~ age + gender)
confint(model)        # Wald (SPSS)
exp(confint(model))   # SPSS "95% C.I. for EXP(B)"

Description

Copies variable labels, value labels, and tagged NA metadata from a source data frame to a target data frame. dplyr verbs such as dplyr::filter(), dplyr::select() or dplyr::arrange() keep labels; they are lost by base-R conversions and computations (e.g. as.numeric(), ifelse(), arithmetic on labelled vectors), by merge() / rbind() of plain data frames, or by a detour through CSV. copy_labels() restores them from the original data.

Usage

copy_labels(data, source)

Arguments

Details

The variable label ("label") is always copied. The following are copied only when the target column still holds the source's codes (a numeric column whose values are observed values or labelled codes of the source column):

• "labels" — value labels

• "na_tag_map" — tagged NA mapping

• "na_tag_format" — tagged NA format (spss/stata/sas)

• "na_values", "na_range" — SPSS missing-value definitions

• "class" — vector class (e.g., haven_labelled)

A converted column (e.g. a factor from to_label()) or a summarised one (e.g. group means) keeps its own type and gets the variable label only.

Value

The target data frame with labels copied from the source. Only columns present in both data frames are affected. Columns only in the target are left unchanged.

See Also

var_label(), val_labels()

Other labels: drop_labels(), find_var(), set_na(), to_character(), to_label(), to_labelled(), to_numeric(), unlabel(), val_labels(), var_label()

Examples

# as.numeric() drops the variable label
data_plain <- dplyr::mutate(survey_data, age = as.numeric(age))
attr(data_plain$age, "label")

# Restore it
data_plain <- copy_labels(data_plain, survey_data)
attr(data_plain$age, "label")

Description

crosstab() shows you how two categorical variables relate to each other. It creates a table that reveals patterns - like whether education level differs by region, or if gender influences product preferences.

Think of it as a two-way frequency table that shows:

• How many people fall into each combination of categories

• What percentage each cell represents

• Whether there are patterns or associations

Usage

crosstab(
  data,
  row,
  col,
  weights = NULL,
  percentages = c("row", "none", "col", "total", "all"),
  na.rm = TRUE,
  digits = 1
)

Arguments

Details

Understanding the Results

The crosstab table shows:

• Cell counts: Number of people in each combination

• Row %: Distribution within each row (e.g., "Among those with high school education, X% live in the East")

• Column %: Distribution within each column (e.g., "Among those in the East, X% have high school education")

• Total %: Percentage of the entire sample (e.g., "X% of all respondents have high school education AND live in the East")

• Adjusted residuals (via summary(result, residuals = TRUE), SPSS /CELLS=ASRESID): which cells deviate from independence. After a significant chi_square test, cells with |adj. residual| > 2 are the ones driving the association. For weighted tables the residuals are computed on the rounded weighted cell counts (see below); an SPSS v29 reference run for the residuals is pending, so they are currently verified against the Haberman formula (chisq.test()$stdres) rather than SPSS output.

Weighted Tables

As SPSS CROSSTABS does by default (/COUNT ROUND CELL), each weighted cell count is rounded to a whole number first; the row and column totals are sums of the rounded cells and all percentages come from the rounded counts. The table total can therefore differ by a few cases from the rounded sum of weights shown as "N (valid)" (SPSS: 2518 vs. 2516 for education x employment in survey_data).

When to Use This

Use crosstab when you want to:

• See if two categorical variables are related

• Compare distributions across groups

• Find patterns in survey responses

• Create demographic breakdowns

Choosing Percentages

• Row %: Use when your row variable is the grouping factor (e.g., "How does region vary BY education level?")

• Column %: Use when your column variable is the grouping factor (e.g., "How does education vary BY region?")

• Total %: Use to understand the overall sample composition

Tips for Success

• Start with row or column percentages, not both at once

• Use chi-squared test to check if the relationship is statistically significant

• Watch for small cell counts (< 5) which may be unreliable

• Consider combining sparse categories if many cells are empty

Value

A cross-tabulation table showing the relationship between two variables. The result also carries the expected cell counts ($expected) and adjusted standardized residuals ($adj_residuals); display the residuals with summary(result, residuals = TRUE).

See Also

table for base R contingency tables.

frequency for single-variable frequency tables.

chi_square for testing if the cross-tabulated variables are related.

Other descriptive: describe(), frequency(), multiple_response(), normality_test()

Examples

# Load required packages and data
library(dplyr)
data(survey_data)

# Basic crosstab
survey_data %>% crosstab(gender, region)

# With weights and all percentages
survey_data %>% crosstab(gender, education,
                         weights = sampling_weight,
                         percentages = "all")

# Grouped analysis
survey_data %>%
  group_by(employment) %>%
  crosstab(gender, region, weights = sampling_weight)

# Column percentages only
survey_data %>% crosstab(education, employment, percentages = "col")

Description

describe() gives you a complete summary of numeric variables - like age, income, or satisfaction scores. It's your first step in any analysis, helping you understand what's typical, what's unusual, and how spread out your data is.

Think of it as a health check for your data that reveals:

• What's the average value?

• What's the middle value?

• How spread out are the responses?

• Are there unusual patterns or outliers?

Usage

describe(
  data,
  ...,
  weights = NULL,
  show = "short",
  probs = c(0.25, 0.5, 0.75),
  na.rm = TRUE,
  excess = TRUE
)

Arguments

Details

Understanding the Results

Key statistics and what they tell you:

• n: How many valid responses (watch for too many missing)

• Mean: The average value

• Median: The middle value (half above, half below)

• SD: Standard deviation - how spread out values are

• Range: The minimum and maximum values

• IQR: Interquartile range - the middle 50% of values

• Skewness: Whether data leans left (negative) or right (positive)

• Kurtosis: Whether you have unusual outliers

• N / Missing: Valid and missing cases. With weights, both are sums of weights (displayed rounded), as in SPSS FREQUENCIES with WEIGHT BY. Kish's effective sample size is kept in the result (<variable>_Effective_N) but not printed.

When to Use This

Always start here! Use describe() to:

• Check data quality (impossible values?)

• Understand distributions before testing

• Spot outliers that might affect analyses

• Compare groups side by side

Interpreting Patterns

• Mean close to Median: Data is roughly symmetric

• Mean > Median: Right-skewed (tail extends right)

• Mean < Median: Left-skewed (tail extends left)

• Large SD: Responses vary widely

• Small SD: Responses are similar

Value

A summary table with descriptive statistics for each variable

See Also

summary for base R summary statistics.

frequency for categorical variable summaries.

w_mean, w_sd, w_median for individual weighted statistics.

t_test and oneway_anova for group comparisons.

Other descriptive: crosstab(), frequency(), multiple_response(), normality_test()

Examples

# Load required packages and data
library(dplyr)
data(survey_data)

# Basic unweighted analysis
survey_data %>% describe(age)

# Weighted analysis
survey_data %>% describe(age, weights = sampling_weight)

# Multiple variables with custom statistics
survey_data %>% describe(age, income, life_satisfaction,
                        weights = sampling_weight,
                        show = c("mean", "sd", "skew"))

# Grouped analysis
survey_data %>%
  group_by(region) %>%
  describe(age, weights = sampling_weight)

Description

Weighted models: sum(w) - rank (SPSS frequency weights, non-integer); unweighted: the lm value.

Usage

## S3 method for class 'linear_regression'
df.residual(object, ...)

Arguments

Value

A single number.

Description

Removes value labels for values that are not present in the data, and unused levels of factors. This is useful after filtering or subsetting, when some categories may no longer exist but their labels remain attached.

Usage

drop_labels(data, ..., drop_na = FALSE)

Arguments

Details

This is useful after subsetting data (e.g., filtering out a category). The removed category's label still exists on the variable, which can cause confusing output in frequency() or codebook(). drop_labels() cleans this up by keeping only labels for values actually present in the data. For factors, unused levels are dropped; the variable label and the original codes of a to_label() factor are kept.

By default, tagged NA labels are preserved (drop_na = FALSE) because they represent missing value types, not substantive categories.

Value

The data with unused labels removed.

See Also

val_labels(), copy_labels()

Other labels: copy_labels(), find_var(), set_na(), to_character(), to_label(), to_labelled(), to_numeric(), unlabel(), val_labels(), var_label()

Examples

# After filtering, "Basic Secondary" no longer occurs but remains a level
data_subset <- dplyr::filter(survey_data, education != "Basic Secondary")
levels(data_subset$education)
data_clean <- drop_labels(data_subset)
levels(data_clean$education)

# Value labels of labelled vectors
if (requireNamespace("haven", quietly = TRUE)) {
  x <- haven::labelled(c(1, 2, 2), labels = c(low = 1, mid = 2, high = 3))
  drop_labels(x)   # the unused label "high" is removed
}

Description

dunn_test() tells you exactly which groups are different from each other after Kruskal-Wallis finds overall differences. It's the non-parametric equivalent of a Tukey or Scheffe post-hoc test.

Think of it as:

• Kruskal-Wallis says "there are differences somewhere"

• Dunn test says "specifically, Group A differs from Group C"

• A way to make all possible pairwise comparisons using rank-based statistics

Usage

dunn_test(x, ...)

## Default S3 method:
dunn_test(x, ...)

Arguments

Details

Understanding the Results

Z-Statistics: Based on differences in mean ranks between groups

• Large absolute Z values indicate big rank differences

• Positive Z: First group has higher mean rank than second

• Negative Z: Second group has higher mean rank than first

Adjusted P-values: Control for multiple comparisons

• p < 0.05: Groups are significantly different

• p >= 0.05: No significant difference between these groups

The Dunn Test Formula

For each pair of groups (i, j):

$Z_{ij} = \frac{\bar{R}_i - \bar{R}_j}{\sqrt{\frac{N(N+1)}{12} \left(\frac{1}{n_i} + \frac{1}{n_j}\right)}}$

where $\bar{R}_i$ is the mean rank for group i, $N$ is the total sample size, and $n_i$ is the size of group i.

P-Value Adjustment Methods

• Bonferroni (default): Most conservative, multiplies p by number of comparisons

• Holm: Step-down method, less conservative than Bonferroni

• BH: Controls false discovery rate, good for many comparisons

When to Use This

Use Dunn test when:

• Your Kruskal-Wallis test shows significant differences (p < 0.05)

• You want to know which specific groups differ

• Your data violates normality assumptions

• You have ordinal data or skewed distributions

Relationship to Other Tests

• Non-parametric equivalent of tukey_test() and scheffe_test()

• Follow-up to kruskal_wallis(), just like Tukey follows ANOVA

Weighted variants

When the parent kruskal_wallis() result is weighted, the pairwise z statistics use the same frequency-weighted midranks. SPSS NPAR TESTS ignores WEIGHT BY, so weighted results have no SPSS reference (R-only, guarded by an internal invariance suite); see vignette("spss-compatibility") for validation status.

• Uses ranks instead of raw values, making it robust to outliers

Value

Pairwise comparison results showing:

• Which group pairs are significantly different

• Z-statistics based on rank differences

• Adjusted p-values (controlling for multiple comparisons)

The comparison table (one row per pair) is stored as $results (also available as $comparisons).

References

Dunn, O. J. (1964). Multiple comparisons using rank sums. Technometrics, 6(3), 241-252.

See Also

kruskal_wallis for performing Kruskal-Wallis tests.

tukey_test for parametric post-hoc comparisons after ANOVA.

scheffe_test for conservative parametric post-hoc comparisons.

Other posthoc: levene_test(), pairwise_wilcoxon(), scheffe_test(), tukey_test()

Examples

# Load required packages and data
library(dplyr)
data(survey_data)

# Perform Kruskal-Wallis followed by Dunn post-hoc test
kw_result <- survey_data %>%
  kruskal_wallis(life_satisfaction, group = education)

# Dunn post-hoc comparisons (default: Bonferroni)
kw_result %>% dunn_test()

# With Holm correction (less conservative)
kw_result %>% dunn_test(p_adjust = "holm")

# With Benjamini-Hochberg (controls false discovery rate)
kw_result %>% dunn_test(p_adjust = "BH")

# With weights
kw_weighted <- survey_data %>%
  kruskal_wallis(life_satisfaction, group = education,
                 weights = sampling_weight)

kw_weighted %>% dunn_test()

# Multiple variables
kw_multi <- survey_data %>%
  kruskal_wallis(life_satisfaction, trust_government,
                 group = education)

kw_multi %>% dunn_test()

# Grouped analysis
kw_grouped <- survey_data %>%
  group_by(region) %>%
  kruskal_wallis(life_satisfaction, group = education)

kw_grouped %>% dunn_test()

Description

efa() performs Exploratory Factor Analysis (EFA) to discover underlying patterns in your survey items. Supports both Principal Component Analysis (PCA) and Maximum Likelihood (ML) extraction. This is the R equivalent of SPSS's FACTOR procedure.

For example, if you have 6 items measuring different attitudes, EFA can reveal whether they group into 2-3 underlying dimensions (factors or components).

Usage

efa(
  data,
  ...,
  n_factors = NULL,
  rotation = "varimax",
  extraction = "pca",
  weights = NULL,
  use = "pairwise",
  sort = TRUE,
  blank = 0.4,
  na.rm = TRUE
)

Arguments

Details

Understanding the Results

KMO (Kaiser-Meyer-Olkin) measures sampling adequacy:

• KMO > 0.90: Marvelous

• KMO 0.80 - 0.90: Meritorious

• KMO 0.70 - 0.80: Middling

• KMO 0.60 - 0.70: Mediocre

• KMO 0.50 - 0.60: Miserable

• KMO < 0.50: Unacceptable - don't use factor analysis

Bartlett's Test of Sphericity tests whether correlations are significantly different from zero. A significant result (p < .05) means the correlation matrix is suitable for factor analysis.

Eigenvalues indicate how much variance each component explains. The Kaiser criterion retains components with eigenvalue > 1.

Factor Loadings show how strongly each item relates to each component:

• |loading| > 0.70: Strong association

• |loading| 0.40 - 0.70: Moderate association

• |loading| < 0.40: Weak (suppressed by default)

Communalities show how much of each item's variance is explained by the extracted components. Low communalities (< 0.40) suggest the item doesn't fit well with the others.

Choosing an Extraction Method

• PCA (default): Extracts components explaining maximum total variance. Simple and robust. Does not assume normality.

• ML: Extracts factors explaining shared variance only. Assumes multivariate normality. Provides a goodness-of-fit test to evaluate model fit. A non-significant chi-square (p > .05) suggests adequate fit.

Choosing a Rotation

• Varimax (default): Assumes factors are uncorrelated. Produces simpler, easier-to-interpret results.

• Oblimin: Allows factors to be correlated. More realistic for social science data. Produces both a Pattern Matrix (unique contributions) and Structure Matrix (total correlations).

• Promax: Oblique rotation based on a power transformation of Varimax results. Like Oblimin, produces Pattern and Structure matrices. Common alternative to Oblimin in SPSS.

• None: No rotation. Rarely useful for interpretation.

Value

An efa result object containing:

loadings

Component loading matrix (rotated if rotation applied)

unrotated_loadings

Unrotated component matrix

eigenvalues

All eigenvalues from the correlation matrix

variance_explained

Tibble with the initial eigenvalues: Total, % of Variance, Cumulative % (one row per variable)

extraction_variance

Tibble with the extraction sums of squared loadings of the extracted components/factors (SPSS "Extraction Sums of Squared Loadings"). For ML this is the variance the common factors explain - the figure the compact print reports.

rotation_variance

Tibble with rotation sums of squared loadings (for the oblique rotations the column sums of squares of the structure matrix, as SPSS reports them)

communalities

Extraction communalities for each variable

kmo

List with overall KMO and per-item MSA values

bartlett

List with chi_sq, df, and p_value

rotation

Rotation method used

extraction

Extraction method used

n_factors

Number of components extracted

correlation_matrix

Correlation matrix used for analysis

initial_communalities

Initial communalities (1.0 for PCA, SMC for ML)

goodness_of_fit

Goodness-of-fit test (ML only): chi_sq, df, p_value. NULL for PCA.

uniquenesses

Unique variances per variable (ML only, NULL for PCA)

pattern_matrix

Pattern matrix (oblimin/promax only, NULL otherwise)

structure_matrix

Structure matrix (oblimin/promax only, NULL otherwise)

factor_correlations

Factor correlation matrix (oblimin/promax only, NULL otherwise)

rotation_iterations, rotation_converged

Iterations of the rotation as SPSS counts them ("Rotation converged in 4 iterations"; for promax those of its varimax step) and whether it converged; NULL without rotation

variables

Character vector of variable names

variable_labels

Named character vector with the variable labels (NA where a variable has none); summary() shows them next to the names, shortened to the console width in the tables

weights

Weights variable name or NULL

item_statistics

Tibble with mean, SD, analysis N and missing N per item. With use = "pairwise" each item uses its own valid cases; with use = "complete" all items use the complete cases.

n

Sample size: the smallest pairwise N (use = "pairwise", the N of Bartlett's test as in SPSS) or the number of complete cases (use = "complete"); the sum of weights when weighted

use

The missing-data handling used ("pairwise" or "complete")

col_prefix

Column name prefix: "PC" for PCA, "Factor" for ML

sort

Whether loadings are sorted

blank

Suppression threshold

Use summary() for the full SPSS-style output with toggleable sections.

See Also

reliability for checking scale reliability before creating indices.

row_means for creating mean indices after identifying factors.

summary.efa for detailed output with toggleable sections.

Other scale: pomps(), reliability(), row_count(), row_means(), row_sums()

Examples

library(dplyr)
data(survey_data)

# Basic EFA with Varimax rotation
efa(survey_data,
    political_orientation, environmental_concern, life_satisfaction,
    trust_government, trust_media, trust_science)

# With Oblimin rotation
efa(survey_data,
    political_orientation, environmental_concern, life_satisfaction,
    trust_government, trust_media, trust_science,
    rotation = "oblimin")

# Maximum Likelihood extraction
efa(survey_data,
    political_orientation, environmental_concern, life_satisfaction,
    trust_government, trust_media, trust_science,
    extraction = "ml")

# Promax rotation (oblique)
efa(survey_data,
    political_orientation, environmental_concern, life_satisfaction,
    trust_government, trust_media, trust_science,
    rotation = "promax")

# Fix number of factors
efa(survey_data,
    political_orientation, environmental_concern, life_satisfaction,
    trust_government, trust_media, trust_science,
    n_factors = 2)

# With survey weights
efa(survey_data,
    political_orientation, environmental_concern, life_satisfaction,
    trust_government, trust_media, trust_science,
    weights = sampling_weight)

# Grouped by region
survey_data %>%
  group_by(region) %>%
  efa(political_orientation, environmental_concern, life_satisfaction,
      trust_government, trust_media, trust_science)

# --- Three-layer output ---
result <- efa(survey_data, political_orientation, environmental_concern,
              life_satisfaction, trust_government, trust_media, trust_science)
result              # compact overview
summary(result)     # full detailed output with all sections
summary(result, communalities = FALSE)  # hide communalities table

Description

factorial_anova() tests whether group means differ across two or more factors simultaneously, including their interactions. It performs a factorial (two-way, three-way) ANOVA using Type III Sum of Squares, matching SPSS UNIANOVA output.

Think of it as:

• Testing multiple grouping variables at once

• Detecting interaction effects (do factor combinations matter?)

• An extension of one-way ANOVA to multiple factors

The test tells you:

• Whether each factor has a main effect on the outcome

• Whether factors interact (the effect of one depends on the other)

• How much variance each factor explains (partial eta squared)

Usage

factorial_anova(data, dv, between, weights = NULL, ss_type = 3)

Arguments

Details

Understanding the Results

Main Effects: Does each factor independently affect the outcome?

• Significant main effect = group means differ for that factor

• Example: Education affects income regardless of gender

Interaction Effects: Does the effect of one factor depend on another?

• Significant interaction = the pattern differs across factor combinations

• Example: The gender gap in income varies by education level

Partial Eta Squared (Effect Size):

• Less than 0.01: Negligible

• 0.01 to 0.06: Small

• 0.06 to 0.14: Medium

• 0.14 or greater: Large

Type III Sum of Squares

Type III SS tests each effect after adjusting for all other effects. This is the standard in SPSS and recommended for unbalanced designs (unequal cell sizes). It uses orthogonal contrasts (contr.sum) internally.

When to Use This

Use factorial ANOVA when:

• You have one numeric outcome variable

• You have 2-3 categorical grouping factors

• You want to test main effects AND interactions

• Your data is approximately normally distributed within cells

What Comes Next?

If the ANOVA is significant:

1. Check which effects are significant (main effects vs. interactions)

2. Use tukey_test() for post-hoc comparisons on main effects

3. Examine cell means to interpret interaction patterns

4. Consider effect sizes for practical significance

Value

An object of class "factorial_anova" containing:

anova_table

Tibble with Source, SS, df, MS, F, p, Partial Eta Squared

descriptives

Tibble with cell means, SDs, and Ns for each factor combination

levene_test

Tibble with Levene's test results (F, df1, df2, p)

r_squared

R-squared and Adjusted R-squared

model

The underlying model object for S3 dispatch

call_info

List with metadata (dv, factors, weighted, n_total, n_missing)

Use summary() for the full SPSS-style output with toggleable sections. For data grouped with group_by(), one ANOVA is computed per group: the tables carry the group keys as leading columns, group_results holds the complete result of each group (NULL, with a warning, for a group that cannot be analysed), and print(), summary(), tukey_test(), scheffe_test() and levene_test() report per group.

References

Cohen, J. (1988). Statistical Power Analysis for the Behavioral Sciences (2nd ed.). Lawrence Erlbaum Associates.

IBM Corp. (2023). IBM SPSS Statistics 29 Algorithms. IBM Corporation.

Maxwell, S. E., & Delaney, H. D. (2004). Designing Experiments and Analyzing Data (2nd ed.). Lawrence Erlbaum Associates.

See Also

oneway_anova for single-factor ANOVA.

tukey_test for post-hoc pairwise comparisons.

levene_test for testing homogeneity of variances.

ancova for ANOVA with covariates.

summary.factorial_anova for detailed output with toggleable sections.

Other hypothesis_tests: ancova(), binomial_test(), chi_square(), chisq_gof(), fisher_test(), friedman_test(), kruskal_wallis(), mann_whitney(), mcnemar_test(), oneway_anova(), t_test(), wilcoxon_test()

Examples

# Load required packages and data
library(dplyr)
data(survey_data)

# Two-way ANOVA: income by gender and education
survey_data %>%
  factorial_anova(dv = income, between = c(gender, education))

# Two-way ANOVA with weights
survey_data %>%
  factorial_anova(dv = life_satisfaction, between = c(gender, region),
                  weights = sampling_weight)

# Separate ANOVA for each region
survey_data %>%
  group_by(region) %>%
  factorial_anova(dv = life_satisfaction, between = c(gender, education))

# Three-way ANOVA
survey_data %>%
  factorial_anova(dv = income, between = c(gender, region, education))

# Follow up with post-hoc tests
result <- survey_data %>%
  factorial_anova(dv = income, between = c(gender, education))
result %>% tukey_test()
result %>% levene_test()

# --- Three-layer output ---
result              # compact overview
summary(result)     # full detailed output with all sections
summary(result, descriptives = FALSE)  # hide the cell descriptives

Description

Searches for variables in your data by matching a pattern against variable names, variable labels, or both. This is especially useful for SPSS datasets where variable names are often cryptic codes (e.g., v104, q23a_1) and the actual meaning is stored in variable labels.

Usage

find_var(
  data,
  pattern,
  search = c("name_label", "name", "label"),
  fixed = FALSE
)

Arguments

Details

When to Use This

• You imported an SPSS file and need to find which variable contains "trust" or "satisfaction"

• You want to quickly identify all variables related to a topic

• You know the German/English label text but not the variable code

Pattern Matching

The pattern argument supports regular expressions. Matching is case-insensitive. Some examples:

• "trust" — matches "trust", "Trust", "distrust", "trustworthy"

• "^trust" — matches only names/labels starting with "trust"

• "^q[0-9]+" — matches variable names like q1, q23, q104

• "zufried" — finds German labels containing "Zufriedenheit"

Label text often contains characters with a special meaning in regular expressions, such as parentheses: "BEFRAGTE(R)" as a regular expression matches "BEFRAGTER". Use fixed = TRUE to search for the text exactly as written.

Value

A data frame with columns:

col

Column position in the data

name

Variable name

label

Variable label (or "" if none)

Without matches, an empty data frame is returned invisibly (with a message).

See Also

var_label() for getting/setting variable labels, val_labels() for value labels

Other labels: copy_labels(), drop_labels(), set_na(), to_character(), to_label(), to_labelled(), to_numeric(), unlabel(), val_labels(), var_label()

Examples

library(dplyr)
data(survey_data)

# Find all variables related to "trust"
find_var(survey_data, "trust")

# Search only in variable labels
find_var(survey_data, "satisfaction", search = "label")

# Use regex to find numbered items
find_var(survey_data, "^q[0-9]+", search = "name")

# Literal text with regex characters, e.g. parentheses in a label
find_var(survey_data, "(1=left", fixed = TRUE)

Description

fisher_test() performs Fisher's exact test for independence in a contingency table. Use this instead of chi_square() when your sample is small or when expected cell frequencies are below 5.

Think of it as:

• An exact alternative to the chi-square test of independence

• Best for small samples where the chi-square approximation may be inaccurate

• SPSS automatically reports Fisher's Exact Test for 2x2 tables

The test tells you:

• Whether two categorical variables are related (exact p-value)

• The contingency table of observed frequencies

• Results that are valid even with very small samples

Usage

fisher_test(
  data,
  row,
  col,
  weights = NULL,
  simulate.p.value = FALSE,
  B = 10000,
  ...
)

Arguments

Details

Understanding the Results

P-value: If p < 0.05, the variables are likely related (not independent)

• p < 0.001: Very strong evidence of relationship

• p < 0.01: Strong evidence of relationship

• p < 0.05: Moderate evidence of relationship

• p >= 0.05: No significant relationship found

Unlike the chi-square test which uses a large-sample approximation, Fisher's exact test computes the exact probability of observing the given table (or a more extreme one) under the null hypothesis of independence.

For tables larger than 2x2, the Fisher-Freeman-Halton extension is used.

When to Use This

Use Fisher's exact test when:

• Any expected cell frequency is less than 5

• Your total sample size is small (typically N < 30)

• You have a 2x2 table (Fisher's exact is standard here)

• You want an exact p-value rather than an approximation

Relationship to Other Tests

• For large samples with all expected frequencies >= 5: Use chi_square() instead

• For paired binary data (before/after): Use mcnemar_test() instead

• For testing a single proportion: Use binomial_test() instead

SPSS Equivalent

SPSS: CROSSTABS /STATISTICS=CHISQ (Fisher's exact test is automatically reported for 2x2 tables)

Value

Test results showing whether two categorical variables are related, including:

• Exact p-value (two-sided)

• Contingency table of observed frequencies

• Sample size (N)

References

Fisher, R. A. (1922). On the interpretation of chi-square from contingency tables, and the calculation of P. Journal of the Royal Statistical Society, 85(1), 87-94.

Freeman, G. H., & Halton, J. H. (1951). Note on an exact treatment of contingency, goodness of fit and other problems of significance. Biometrika, 38(1/2), 141-149.

See Also

chi_square for chi-square test of independence (large samples).

mcnemar_test for paired proportions.

Other hypothesis_tests: ancova(), binomial_test(), chi_square(), chisq_gof(), factorial_anova(), friedman_test(), kruskal_wallis(), mann_whitney(), mcnemar_test(), oneway_anova(), t_test(), wilcoxon_test()

Examples

# Load required packages and data
library(dplyr)
data(survey_data)

# Basic 2x2 Fisher test
survey_data %>%
  fisher_test(row = gender, col = region)

# Fisher test for larger table
survey_data %>%
  fisher_test(row = gender, col = interview_mode)

# With weights
survey_data %>%
  fisher_test(row = gender, col = region, weights = sampling_weight)

# Grouped analysis
survey_data %>%
  group_by(education) %>%
  fisher_test(row = gender, col = region)

Description

Dispatches to stats::fitted() for the fitted lm; grouped and pairwise results raise an informative error.

Usage

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

Arguments

Value

A numeric vector.

Description

frequency() helps you understand categorical data by showing how many people chose each option. It's perfect for survey questions with fixed choices like education level, yes/no questions, or rating scales.

Think of it as creating a summary table that shows:

• How many people chose each option

• What percentage that represents

• Running totals to see cumulative patterns

Usage

frequency(
  data,
  ...,
  weights = NULL,
  sort_frq = "none",
  show_na = TRUE,
  show_prc = TRUE,
  show_valid = TRUE,
  show_sum = TRUE,
  show_labels = "auto",
  show_unused = FALSE,
  sort.frq = NULL,
  show.na = NULL,
  show.prc = NULL,
  show.valid = NULL,
  show.sum = NULL,
  show.labels = NULL,
  show.unused = NULL
)

fre(data, ..., weights = NULL, sort_frq = "none", show_na = TRUE,
  show_prc = TRUE, show_valid = TRUE, show_sum = TRUE, show_labels = "auto",
  show_unused = FALSE, sort.frq = NULL, show.na = NULL, show.prc = NULL,
  show.valid = NULL, show.sum = NULL, show.labels = NULL, show.unused = NULL)

Arguments

Details

Understanding the Results

The frequency table follows the SPSS FREQUENCIES layout:

• N: Number of responses in each category (weighted: sum of weights, displayed rounded)

• Raw %: Percentage including missing values (use for "response rate")

• Valid %: Percentage excluding missing values (use for "among those who answered")

• Cum. %: Running total of the valid percentages (helps identify cutoff points)

• Total valid, the missing categories, Total missing (with two or more missing categories) and the grand Total; without missing values a single Total row ends the table.

Factors, character and logical variables show their categories in the Value column; labelled numeric variables show the code and its label. Long labels are never cut; they wrap when the table would be wider than the console.

When to Use This

Use frequency() when you have:

• Categorical variables (gender, region, education level)

• Yes/No questions

• Rating scales (satisfied/neutral/dissatisfied)

• Any question with a fixed set of options

Weights Make a Difference

Without weights, you're describing your sample. With weights, you're estimating population values. Always use weights for population inference.

Tagged Missing Values

When data is imported with tagged NAs (e.g., via read_spss() with tag_na = TRUE, or read_stata(), read_sas(), read_xpt() with the tag_na parameter), frequency() automatically expands the missing value section to show each missing type individually (with its original missing value code and label), plus summary rows for Total Valid and Total Missing.

Value

A frequency table showing counts and percentages for each category

See Also

table for base R frequency tables.

crosstab for cross-tabulation of two variables.

chi_square for testing relationships between categories.

describe for numeric variable summaries.

Other descriptive: crosstab(), describe(), multiple_response(), normality_test()

Examples

# Load required packages and data
library(dplyr)
data(survey_data)

# Basic categorical analysis
survey_data %>% frequency(gender)

# Multiple variables with weights
survey_data %>% frequency(gender, region, weights = sampling_weight)

# Grouped analysis by region
survey_data %>% 
  group_by(region) %>% 
  frequency(gender, weights = sampling_weight)

# Education levels with sorting
survey_data %>% frequency(education, sort_frq = "desc")

# Employment status with custom display options
survey_data %>% frequency(employment, weights = sampling_weight, 
                         show_na = TRUE, show_sum = TRUE)

Description

friedman_test() compares three or more related measurements from the same subjects when your data isn't normally distributed. It's the non-parametric alternative to repeated-measures ANOVA.

Think of it as:

• Comparing ratings of multiple items by the same respondents

• Testing whether scores change across three or more time points

• A robust repeated-measures comparison that works with any data shape

The test tells you:

• Whether at least one measurement is significantly different from the others

• Which measurements tend to be rated higher or lower (via mean ranks)

• The strength of the overall effect (Kendall's W)

Usage

friedman_test(data, ..., weights = NULL, conf.level = 0.95)

Arguments

Details

Understanding the Results

P-value: If p < 0.05, at least one measurement is significantly different

• p < 0.001: Very strong evidence of differences

• p < 0.01: Strong evidence of differences

• p < 0.05: Moderate evidence of differences

• p > 0.05: No significant differences found

Kendall's W (Effect size: How consistent is the pattern?):

• < 0.1: Negligible agreement/effect

• 0.1 - 0.3: Weak agreement

• 0.3 - 0.5: Moderate agreement

• 0.5 or higher: Strong agreement

Mean Ranks:

• Higher mean rank = measurement tends to have higher values

• Lower mean rank = measurement tends to have lower values

• Compare mean ranks to see which measurements stand out

When to Use This

Use the Friedman test when:

• You have 3 or more related measurements from the same subjects

• Your data is not normally distributed

• You have ordinal data (ratings, rankings)

• You want a robust alternative to repeated-measures ANOVA

• You're comparing multiple ratings by the same respondents

Relationship to Other Tests

• For 2 related measurements: Use wilcoxon_test() instead

• For normally distributed repeated measures: Use repeated-measures ANOVA

Weighted variants

SPSS NPAR TESTS ignores WEIGHT BY, so weighted results have no SPSS reference. The weighted variant is an R-only frequency-weight extension that reduces exactly to the unweighted test when all weights equal 1 (enforced by an internal invariance suite); see vignette("spss-compatibility") for validation status.

• For independent groups: Use kruskal_wallis() instead

Value

Test results showing whether the measurements differ, including:

• Chi-Square statistic (chi_squared, the Friedman test statistic)

• Degrees of freedom (number of measurements minus 1)

• P-value (are measurements different?)

• Kendall's W (effect size: how strong is the overall pattern?)

• Mean rank for each measurement (which measurements are higher/lower?)

References

Friedman, M. (1937). The use of ranks to avoid the assumption of normality implicit in the analysis of variance. Journal of the American Statistical Association, 32(200), 675-701.

Kendall, M. G., & Babington Smith, B. (1939). The problem of m rankings. The Annals of Mathematical Statistics, 10(3), 275-287.

See Also

friedman.test for the base R Friedman test.

wilcoxon_test for comparing two related measurements.

kruskal_wallis for comparing independent groups.

Other hypothesis_tests: ancova(), binomial_test(), chi_square(), chisq_gof(), factorial_anova(), fisher_test(), kruskal_wallis(), mann_whitney(), mcnemar_test(), oneway_anova(), t_test(), wilcoxon_test()

Examples

# Load required packages and data
library(dplyr)
data(survey_data)

# Compare three trust items (rated by same respondents)
survey_data %>%
  friedman_test(trust_government, trust_media, trust_science)

# Using tidyselect helpers
survey_data %>%
  friedman_test(starts_with("trust_"))

# Weighted analysis
survey_data %>%
  friedman_test(trust_government, trust_media, trust_science,
                weights = sampling_weight)

# Grouped analysis (separate test per region)
survey_data %>%
  group_by(region) %>%
  friedman_test(trust_government, trust_media, trust_science)

Description

Calculates Kendall's tau-b rank correlation coefficients between variables with support for weighted correlations, grouped data, and multiple variable pairs. Provides significance testing and SPSS-compatible output formatting.

The function computes tau-b, which is adjusted for ties and is particularly suitable for ordinal data or when the assumptions of Pearson correlation are not met. For weighted correlations, it uses survey-weighted rank calculations.

Usage

kendall_tau(
  data,
  ...,
  weights = NULL,
  alternative = c("two.sided", "less", "greater"),
  use = c("pairwise", "listwise"),
  na.rm = NULL
)

Arguments

Details

Understanding the Results

Kendall's tau measures how often pairs of observations are in the same order (concordant) versus different order (discordant). It is particularly useful for ordinal data, data with outliers, small sample sizes, and non-linear but monotonic relationships.

The tau value ranges from -1 to +1:

• Strong positive (0.5 to 1.0): High values of one variable tend to go with high values of the other

• Moderate positive (0.3 to 0.5): Some tendency for values to increase together

• Weak positive (0 to 0.3): Slight tendency for values to increase together

• No correlation (near 0): No relationship between the variables

• Negative values: As one variable increases, the other tends to decrease

The output also provides:

• p-value: Probability of seeing this correlation by chance (smaller = stronger evidence)

• n: Number of observations used

• significance stars: Quick visual indicator of statistical significance

When to Use This

Choose Kendall's tau when:

• Your data is ordinal (ranked categories)

• You have a small sample size (< 30 observations)

• Your data has outliers that might affect Pearson correlation

Weighted variants

The weighted tau-b is an exact frequency-weighted computation (it reproduces the unweighted tau when all weights equal 1, enforced by an internal invariance suite), but its z statistic and p-value use a no-ties normal approximation. SPSS NONPAR CORR ignores WEIGHT BY, so weighted results have no SPSS reference; see vignette("spss-compatibility") for validation status.

• You want a more conservative measure than Spearman's rho

Value

Correlation results showing rank-based relationships between variables, including the tau-b coefficient, p-value, z-score, and sample size for each pair. For multiple variables, correlation, significance, and sample size matrices are also provided. Use summary() for the full SPSS-style output with toggleable sections.

References

Kendall, M. G. (1938). A new measure of rank correlation. Biometrika, 30(1/2), 81–93.

Kendall, M. G. (1945). The treatment of ties in ranking problems. Biometrika, 33(3), 239–251.

Agresti, A. (2010). Analysis of Ordinal Categorical Data (2nd ed.). John Wiley & Sons.

See Also

cor with method = "kendall" for the base R implementation.

spearman_rho for Spearman's rank correlation.

pearson_cor for Pearson correlation analysis.

summary.kendall_tau for detailed output with toggleable sections.

Other correlation: partial_cor(), pearson_cor(), spearman_rho()

Examples

# Load required packages and data
library(dplyr)
data(survey_data)

# Kendall's tau is O(n^2); the examples run on a subset for speed.
# On your own data, simply drop the subsetting.
mini_survey <- survey_data[1:300, ]

# Basic correlation between two variables
mini_survey %>%
  kendall_tau(life_satisfaction, political_orientation)

# Correlation matrix for multiple variables
mini_survey %>%
  kendall_tau(life_satisfaction, political_orientation, trust_media)

# Weighted correlations
mini_survey %>%
  kendall_tau(age, income, weights = sampling_weight)

# Listwise deletion for missing data
mini_survey %>%
  kendall_tau(age, income, use = "listwise")

# One-tailed test
mini_survey %>%
  kendall_tau(age, income, alternative = "greater")


# Grouped correlations
mini_survey %>%
  group_by(region) %>%
  kendall_tau(age, income, life_satisfaction)

# Using tidyselect helpers for ordinal variables
mini_survey %>%
  kendall_tau(starts_with("trust"), weights = sampling_weight)

# --- Three-layer output ---
result <- mini_survey %>%
  kendall_tau(life_satisfaction, political_orientation, trust_media,
              weights = sampling_weight)
result              # compact one-line overview
summary(result)     # full correlation, p-value, and N matrices
summary(result, pvalue_matrix = FALSE)  # hide p-values

Description

kruskal_wallis() compares three or more groups when your data isn't normally distributed or when you have ordinal data (like ratings or rankings). It's the non-parametric alternative to one-way ANOVA.

Think of it as:

• An extension of the Mann-Whitney test for more than two groups

• A robust way to compare groups that works with any data shape

• Perfect for Likert scales, rankings, or skewed distributions

The test tells you:

• Whether at least one group is different from the others

• How strong the overall group effect is (effect size)

• Which groups tend to have higher or lower values (via mean ranks)

Usage

kruskal_wallis(data, ..., group, weights = NULL, conf.level = 0.95)

Arguments

Details

Understanding the Results

P-value: If p < 0.05, at least one group is significantly different

• p < 0.001: Very strong evidence of group differences

• p < 0.01: Strong evidence of group differences

• p < 0.05: Moderate evidence of group differences

• p > 0.05: No significant group differences found

Effect Size Epsilon-squared (How much do groups matter?):

• < 0.01: Negligible effect

• 0.01-0.06: Small effect

• 0.06-0.14: Medium effect

• 0.14 or higher: Large effect

Mean Ranks:

• Higher mean rank = group tends to have higher values

• Lower mean rank = group tends to have lower values

• Compare mean ranks to see the pattern of group differences

When to Use This

Use Kruskal-Wallis test when:

• Your data is not normally distributed (skewed, outliers)

• You have ordinal data (rankings, Likert scales)

• Sample sizes are small or very unequal across groups

• You want a robust alternative to one-way ANOVA

• You're comparing satisfaction ratings, income, or other skewed variables

What Comes Next?

If the Kruskal-Wallis test is significant:

1. Look at mean ranks to see the pattern

2. Use pairwise Mann-Whitney tests with Bonferroni correction to find which specific groups differ

3. Consider effect sizes to judge practical importance

Relationship to Other Tests

• For 2 groups: Use mann_whitney() instead

• For normally distributed data: Use oneway_anova() instead

Weighted variants

SPSS NPAR TESTS ignores WEIGHT BY, so weighted results have no SPSS reference. The weighted variant is an R-only frequency-weight extension that reduces exactly to the unweighted test when all weights equal 1 (enforced by an internal invariance suite); see vignette("spss-compatibility") for validation status.

• For repeated measures (same subjects): Use friedman_test() instead

Value

Test results showing whether groups differ, including:

• H statistic (Kruskal-Wallis chi-square test statistic)

• Degrees of freedom (number of groups minus 1)

• P-value (are groups different?)

• Effect size epsilon-squared (how big is the group effect?)

• Mean rank for each group (which groups are higher/lower?)

References

Kruskal, W. H., & Wallis, W. A. (1952). Use of ranks in one-criterion variance analysis. Journal of the American Statistical Association, 47(260), 583-621.

Tomczak, M., & Tomczak, E. (2014). The need to report effect size estimates revisited. An overview of some recommended measures of effect size. Trends in Sport Sciences, 1(21), 19-25.

See Also

kruskal.test for the base R Kruskal-Wallis test.

mann_whitney for comparing exactly two groups.

oneway_anova for parametric one-way ANOVA.

Other hypothesis_tests: ancova(), binomial_test(), chi_square(), chisq_gof(), factorial_anova(), fisher_test(), friedman_test(), mann_whitney(), mcnemar_test(), oneway_anova(), t_test(), wilcoxon_test()

Examples

# Load required packages and data
library(dplyr)
data(survey_data)

# Basic Kruskal-Wallis test (comparing across education levels)
survey_data %>%
  kruskal_wallis(life_satisfaction, group = education)

# Multiple variables
survey_data %>%
  kruskal_wallis(life_satisfaction, income, trust_government,
                 group = education)

# Using tidyselect helpers
survey_data %>%
  kruskal_wallis(starts_with("trust_"), group = education)

# Weighted analysis
survey_data %>%
  kruskal_wallis(life_satisfaction, group = education,
                 weights = sampling_weight)

# Grouped analysis (separate test for each region)
survey_data %>%
  group_by(region) %>%
  kruskal_wallis(life_satisfaction, group = education)

# Compare across employment status (5 groups)
survey_data %>%
  kruskal_wallis(income, group = employment)

Description

levene_test() checks if different groups have similar amounts of variation. This is an important assumption for many statistical tests - groups should spread out in similar ways.

The test tells you:

• Whether variance is consistent across groups

• If you can trust standard ANOVA and t-test results

• When to use alternative tests that don't assume equal variance

Usage

levene_test(x, ...)

## Default S3 method:
levene_test(x, ...)

## S3 method for class 'data.frame'
levene_test(x, ..., group, weights = NULL, center = c("mean", "median"))

## S3 method for class 'oneway_anova'
levene_test(x, center = c("mean", "median"), ...)

## S3 method for class 't_test'
levene_test(x, center = c("mean", "median"), ...)

## S3 method for class 'ancova'
levene_test(x, center = c("mean", "median"), ...)

## S3 method for class 'mann_whitney'
levene_test(x, ...)

## S3 method for class 'grouped_df'
levene_test(x, ..., group, weights = NULL, center = c("mean", "median"))

Arguments

Details

Understanding the Results

P-value interpretation:

• p > 0.05: Good! Groups have similar variance (assumption met)

• p <= 0.05: Problem - groups vary differently (assumption violated)

Think of it like checking if all groups are equally "spread out":

• Similar spread = can use standard tests

• Different spread = need special methods

When to Use This

Check variance equality when:

• Before running t-tests or ANOVA

• Comparing groups with different sizes

• Your statistical test assumes equal variances

• You see very different standard deviations

What If Variances Are Unequal?

If Levene's test is significant (p <= 0.05):

• For t-tests: Use Welch's t-test (var.equal = FALSE)

• For ANOVA: Use Welch's ANOVA

• Consider transforming your data

• Use non-parametric alternatives

• Report that equal variance assumption was violated

Usage Flexibility

You can use this function two ways:

• Standalone: Check any variables for equal variance

• After tests: Pipe after t_test() or oneway_anova() to verify assumptions

Tips for Success

• Always check this assumption for group comparisons

• Visual inspection (boxplots) can supplement the test

• Large samples make the test very sensitive

• Use median-based test for skewed data (center = "median")

• Don't panic if violated - alternatives exist!

Value

Test results showing:

• Whether groups have equal variances (p-value)

• F-statistic measuring variance differences

• Which variables meet the assumption

References

Levene, H. (1960). Robust tests for equality of variances. In I. Olkin (Ed.), Contributions to Probability and Statistics (pp. 278–292). Stanford University Press.

Brown, M. B., & Forsythe, A. B. (1974). Robust tests for the equality of variances. Journal of the American Statistical Association, 69(346), 364–367.

IBM Corp. (2023). IBM SPSS Statistics 29 Algorithms. IBM Corporation.

See Also

oneway_anova for one-way ANOVA (which assumes equal variances).

t_test for group mean comparisons.

var.test for the base R F-test of variance equality.

Other posthoc: dunn_test(), pairwise_wilcoxon(), scheffe_test(), tukey_test()

Examples

# Load required packages and data
library(dplyr)
data(survey_data)

# Standalone Levene test (test homogeneity of variances)
survey_data %>% levene_test(life_satisfaction, group = region)

# Multiple variables
survey_data %>% levene_test(life_satisfaction, trust_government, group = region)

# Weighted analysis
survey_data %>% levene_test(income, group = education, weights = sampling_weight)

# Piped after ANOVA (common workflow)
result <- survey_data %>%
  oneway_anova(life_satisfaction, group = education)
result %>% levene_test()

# Piped after t-test
survey_data %>%
  t_test(age, group = gender) %>%
  levene_test()

# Using mean instead of median as center
survey_data %>% levene_test(income, group = region, center = "mean")

Description

linear_regression() performs bivariate or multiple linear regression with SPSS-compatible output. Wraps stats::lm() and adds standardized coefficients (Beta), a formatted ANOVA table, and a model summary matching SPSS REGRESSION output.

Supports two interface styles:

• Formula interface: linear_regression(data, life_satisfaction ~ age + education)

• SPSS-style: linear_regression(data, dependent = life_satisfaction, predictors = c(age, education))

Usage

linear_regression(
  data,
  formula = NULL,
  dependent = NULL,
  predictors = NULL,
  weights = NULL,
  use = c("listwise", "pairwise"),
  standardized = TRUE,
  conf.level = 0.95,
  factors = c("dummy", "numeric")
)

Arguments

Details

Understanding the Results

The output includes four sections matching SPSS REGRESSION output:

• Model Summary: R, R-squared, Adjusted R-squared, and Standard Error of the Estimate. R-squared tells you how much variance in the dependent variable is explained by the predictors.

• ANOVA: Tests whether the overall model is significant. A significant F-test means at least one predictor matters.

• Coefficients: B (unstandardized), Beta (standardized), t-value, p-value, and confidence intervals for each predictor.

• Descriptives: Mean, SD, and N for all variables in the model.

Interpreting coefficients:

• B (unstandardized): For each 1-unit increase in the predictor, the dependent variable changes by B units

• Beta (standardized): Allows comparison across predictors with different scales. Larger absolute Beta = stronger effect

• p-value: Values below 0.05 indicate statistically significant predictors

When to Use This

Use linear_regression() when:

• Your dependent variable is continuous (e.g., income, satisfaction score)

• You want to predict an outcome from one or more predictors

• You need standardized coefficients to compare predictor importance

For binary outcomes (yes/no, 0/1), use logistic_regression instead.

Technical Details

Missing Data: By default, listwise deletion is used (matching SPSS REGRESSION /MISSING LISTWISE). Set use = "pairwise" to match SPSS /MISSING PAIRWISE, which computes the regression from a pairwise covariance matrix. Pairwise deletion retains more cases and produces results closer to SPSS output when data has varying patterns of missingness.

Weights: When weights are specified, they are treated as frequency weights (matching SPSS WEIGHT BY behavior). The model is fitted using weighted least squares via lm(weights = ...); the coefficients are those of lm(), but N is sum(w) and the residual df are sum(w) - rank (unrounded), as in SPSS. lm() itself treats weights as analytic (precision) weights with df = cases - rank, so the inherited generics are adjusted to the SPSS convention: vcov(), confint(), nobs() (unrounded sum(w)), df.residual(), anova() (single model), predict() (standard errors and intervals), broom::tidy() and broom::glance() all agree with summary(). stats::summary.lm(), logLik(), AIC() and BIC() keep lm's analytic-weight definitions.

Standardized Coefficients: Beta = B * (SD_x / SD_y). This matches the SPSS standardized coefficient output. Not available for the intercept. For dummy-coded factor terms (factors = "dummy"), the SD of the contrast column from the design matrix is used.

Factor Predictors: By default (factors = "dummy"), factor predictors are expanded into L - 1 contrasts via R's stats::model.matrix(), matching base R lm(): unordered factors get treatment (dummy) contrasts against the first level, while ordered factors get R's default polynomial contrasts (.L/.Q/.C terms). Pass factors = "numeric" to silently coerce factor levels to their integer codes (SPSS REGRESSION default). The "numeric" mode is required to reproduce SPSS results for ordinal predictors like education or Likert scales that SPSS treats as continuous.

Grouped Analysis: When data is grouped via dplyr::group_by(), a separate regression is run for each group (matching SPSS SPLIT FILE BY).

Value

For ungrouped + listwise data, an object of class c("linear_regression", "lm") — the fitted lm itself, with mariposa-specific slots attached:

coef_table

SPSS-style tibble with B, Std.Error, Beta, t, p, CI_lower, CI_upper. For weighted models, SE / t / p are adjusted to SPSS's frequency-weight df (see Technical Details).

anova_table

SPSS-style overall-model ANOVA tibble (Source × Sum_of_Squares / df / Mean_Square / F_statistic / Sig).

model_summary

List with R, R_squared, adj_R_squared, std_error.

descriptives

Tibble with Mean, Std.Deviation, N for all variables.

n

Sample size (listwise complete cases; weighted N when weighted).

formula, dependent, predictor_names, weighted, weight_name, use, is_grouped, standardized, conf.level

Call metadata.

Because the object inherits from "lm", all standard generics (predict(), anova(), vcov(), confint(), residuals(), fitted(), coef(), model.matrix(), broom::tidy(), broom::glance(), broom::augment()) dispatch natively without unwrapping. summary() returns the SPSS-style mariposa summary; for the raw lm summary use stats::summary.lm() on the same object.

For use = "pairwise" (no single fitted lm available) or for grouped data, returns a list of class "linear_regression". Pairwise results expose the same SPSS-style tables but not the lm generics; grouped results hold one fitted lm-inheriting model per group under $groups.

See Also

logistic_regression for binary outcome variables.

describe for checking variable distributions before regression.

pearson_cor for checking bivariate correlations.

summary.linear_regression for detailed output with toggleable sections.

Other regression: logistic_regression(), marginal_effects()

Examples

library(dplyr)
data(survey_data)

# Bivariate regression
linear_regression(survey_data, life_satisfaction ~ age)

# Multiple regression
linear_regression(survey_data, income ~ age + education + life_satisfaction)

# SPSS-style interface
linear_regression(survey_data,
                  dependent = life_satisfaction,
                  predictors = c(trust_government, trust_media, trust_science))

# Weighted regression
linear_regression(survey_data, life_satisfaction ~ age, weights = sampling_weight)

# Grouped by region
survey_data |>
  dplyr::group_by(region) |>
  linear_regression(life_satisfaction ~ age)

# Factor predictors: dummy-coding (default, matches base R lm())
linear_regression(survey_data, income ~ age + education)

# Factor predictors: SPSS-style ordinal-as-scale
linear_regression(survey_data, income ~ age + education,
                  factors = "numeric")

# --- Three-layer output ---
result <- linear_regression(survey_data, life_satisfaction ~ age + income)
result                                  # compact one-line overview
summary(result)                         # full detailed SPSS-style output
summary(result, descriptives = FALSE)   # hide descriptives section

Description

logistic_regression() performs binary logistic regression with SPSS-compatible output. Wraps stats::glm(family = binomial) and adds odds ratios, pseudo R-squared measures, classification table, and model tests matching SPSS LOGISTIC REGRESSION output.

Supports two interface styles:

• Formula interface: logistic_regression(data, high_satisfaction ~ age + income)

• SPSS-style: logistic_regression(data, dependent = high_satisfaction, predictors = c(age, income))

Usage

logistic_regression(
  data,
  formula = NULL,
  dependent = NULL,
  predictors = NULL,
  weights = NULL,
  conf.level = 0.95,
  factors = c("dummy", "numeric")
)

Arguments

Details

Understanding the Results

The output includes five sections matching SPSS LOGISTIC REGRESSION output:

• Omnibus Test: Tests whether the model as a whole is significant. A significant chi-square means the model predicts better than chance.

• Model Summary: -2 Log Likelihood and pseudo R-squared values. Lower -2LL = better fit. Higher R-squared = more variance explained.

• Hosmer-Lemeshow Test: Goodness-of-fit test. A non-significant result (p > 0.05) means the model fits the data well.

• Classification Table: How well the model classifies cases. Shows percentage correctly predicted for each group and overall.

• Coefficients: B, Wald test, odds ratios (Exp(B)), and CIs.

Interpreting odds ratios (Exp(B)):

• Exp(B) > 1: Predictor increases the odds of the outcome

• Exp(B) < 1: Predictor decreases the odds of the outcome

• Exp(B) = 1: Predictor has no effect on the odds

When to Use This

Use logistic_regression() when:

• Your dependent variable is binary (yes/no, 0/1, pass/fail)

• You want to predict group membership from one or more predictors

• You need odds ratios to interpret predictor effects

For continuous outcomes, use linear_regression instead.

Technical Details

Dependent Variable: Any variable with exactly two distinct observed values, coded internally as 0/1 like SPSS LOGISTIC REGRESSION does: for numeric and labelled variables the lower value becomes 0 and the higher 1 (so 1/2 and 0/1 codings give the same model); for factors unused levels are dropped and the first remaining level becomes 0; character values are ordered alphabetically; logicals code FALSE = 0, TRUE = 1. The model predicts the probability of the category coded 1 - the compact print names it ([P(y = category)]), and summary() shows the SPSS "Dependent Variable Encoding" table (also stored as $dv_encoding). A grouped analysis uses one encoding for all groups.

Missing Data: Listwise deletion is used (matching SPSS LOGISTIC REGRESSION default behavior).

Weights: When weights are specified, they are treated as frequency weights (matching SPSS WEIGHT BY behavior).

Pseudo R-squared: Three measures are reported:

• Cox & Snell R-squared (bounded below 1)

• Nagelkerke R-squared (adjusted to reach 1)

• McFadden R-squared (1 - LL_model/LL_null)

Factor Predictors: By default (factors = "dummy"), factor predictors are expanded into L - 1 contrasts via R's stats::model.matrix(), matching base R glm(): unordered factors get treatment (dummy) contrasts against the first level, while ordered factors get R's default polynomial contrasts (.L/.Q/.C terms). Pass factors = "numeric" to silently coerce factor levels to their integer codes (SPSS LOGISTIC REGRESSION default without an explicit /CATEGORICAL subcommand).

Grouped Analysis: When data is grouped via dplyr::group_by(), a separate regression is run for each group (matching SPSS SPLIT FILE BY).

Value

For ungrouped data, an object of class c("logistic_regression", "glm", "lm") — the fitted glm itself, with mariposa-specific slots attached:

coef_table

Tibble with B, S.E., Wald, df, Sig., Exp(B), CI_lower, CI_upper

model_summary

List with minus2LL, cox_snell_r2, nagelkerke_r2, mcfadden_r2

omnibus_test

List with chi_sq, df, p for overall model test

classification

List with table, overall_pct, pct_correct_0, pct_correct_1

hosmer_lemeshow

List with chi_sq, df, p (goodness-of-fit test)

dv_encoding

Tibble Original -> Internal (0/1) of the outcome categories (SPSS "Dependent Variable Encoding")

n

Sample size (listwise complete cases; weighted N when weighted)

formula, dependent, predictor_names, weighted, weight_name, is_grouped, conf.level

Call metadata.

Because the object inherits from "glm", all standard generics (predict(), anova(), vcov(), confint(), residuals(), fitted(), coef(), broom::tidy(), broom::glance(), broom::augment()) dispatch natively without unwrapping. summary() returns the SPSS-style mariposa summary; for the raw glm summary use stats::summary.glm() on the same object. confint() returns Wald intervals on the log-odds scale (the SPSS method; exp(confint(model)) gives the "C.I. for EXP(B)" of the summary), profile-likelihood intervals via confint(model, method = "profile"); see confint.logistic_regression.

For grouped data, returns a list of class "logistic_regression" with $groups holding one fitted glm-inheriting result per group.

See Also

linear_regression for continuous outcome variables.

chi_square for testing associations between categorical variables.

summary.logistic_regression for detailed output with toggleable sections.

Other regression: linear_regression(), marginal_effects()

Examples

library(dplyr)
data(survey_data)

# Create binary DV
survey_data$high_satisfaction <- ifelse(survey_data$life_satisfaction >= 4, 1, 0)

# Bivariate logistic regression
logistic_regression(survey_data, high_satisfaction ~ age)

# Multiple logistic regression
logistic_regression(survey_data, high_satisfaction ~ age + income + education)

# SPSS-style interface
logistic_regression(survey_data,
                    dependent = high_satisfaction,
                    predictors = c(age, income))

# Weighted logistic regression
logistic_regression(survey_data, high_satisfaction ~ age,
                    weights = sampling_weight)

# Grouped by region
survey_data |>
  dplyr::group_by(region) |>
  logistic_regression(high_satisfaction ~ age)

# Factor predictors: dummy-coding (default, matches base R glm())
logistic_regression(survey_data, high_satisfaction ~ age + education)

# Factor predictors: SPSS-style ordinal-as-scale
logistic_regression(survey_data, high_satisfaction ~ age + education,
                    factors = "numeric")

# --- Three-layer output ---
result <- logistic_regression(survey_data, high_satisfaction ~ age + income)
result                                    # compact one-line overview
summary(result)                           # full detailed SPSS-style output
summary(result, classification = FALSE)   # hide classification table

Description

coef(), residuals(), fitted() and vcov() dispatch to the glm methods for an ungrouped model; a grouped result raises an informative error (each element of $groups is a fitted model). nobs() returns the number of cases, or for a weighted model the unrounded sum of the frequency weights (SPSS N, shown rounded in the summary).

Usage

## S3 method for class 'logistic_regression'
coef(object, ...)

## S3 method for class 'logistic_regression'
residuals(object, ...)

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

## S3 method for class 'logistic_regression'
vcov(object, ...)

## S3 method for class 'logistic_regression'
nobs(object, ...)

Arguments

Value

As the corresponding glm method.

Description

A synthetic repeated measures dataset suitable for testing longitudinal analysis functions. Contains realistic treatment effects, missing data patterns, and within-subject correlations.

Usage

longitudinal_data

Format

A data frame with 480 rows and 10 variables:

subject_id

Subject identifier (factor, 1-120)

group

Treatment group (Control, Treatment)

age

Age in years (numeric)

gender

Gender (Male, Female)

time

Time point (T1, T2, T3, T4)

time_numeric

Time point as numeric (1-4)

outcome_score

Primary outcome measure (continuous)

secondary_outcome

Secondary outcome measure (continuous)

physio_measure

Physiological measure (continuous)

questionnaire_score

Questionnaire rating (ordered factor, 1-7)

Details

Study design features:

• 120 subjects (60 per group)

• 4 measurement occasions

• Balanced treatment assignment

• Realistic dropout patterns (0% at T1, 35% by T4)

• Treatment effect grows over time (interaction effect)

• Autoregressive error structure

• Effect size approximately Cohen's d = 0.6

Missing data patterns reflect realistic longitudinal study attrition with higher dropout in later time points. The treatment effect demonstrates a clear Group x Time interaction suitable for repeated measures testing.

Source

Generated synthetically with realistic longitudinal correlation patterns and treatment effects. No real study data was used.

See Also

longitudinal_data_wide for the wide format version.

survey_data for the cross-sectional survey dataset.

Examples

# Load required packages and data
library(dplyr)
data(longitudinal_data)

# Simple example analysis with wide format data
# data(longitudinal_data_wide)
# (Repeated measures functions coming in future version)

# Descriptive statistics by group and time
longitudinal_data %>%
  group_by(group, time) %>%
  describe(outcome_score)

Description

Wide format version of the longitudinal_data dataset with one row per subject and separate columns for each time point. Useful for certain repeated measures analyses and data visualization.

Usage

longitudinal_data_wide

Format

A data frame with 120 rows and 8 variables:

subject_id

Subject identifier (factor, 1-120)

group

Treatment group (Control, Treatment)

age

Age in years (numeric)

gender

Gender (Male, Female)

score_T1

Outcome score at Time 1

score_T2

Outcome score at Time 2

score_T3

Outcome score at Time 3

score_T4

Outcome score at Time 4

Details

This is the wide format version of longitudinal_data with outcome scores spread across columns by time point. Missing values represent subject dropout or missed assessments.

Source

Generated synthetically from the long format longitudinal_data.

See Also

longitudinal_data for the long format version

Examples

# Load required packages and data
library(dplyr)
data(longitudinal_data_wide)

# Analysis of change scores
# (Repeated measures functions coming in future version)

Description

mann_whitney() compares two groups when your data isn't normally distributed or when you have ordinal data (like ratings or rankings). It's the go-to alternative when t-tests aren't appropriate.

Think of it as:

• A robust way to compare groups that works with any data shape

• Perfect for Likert scales, ratings, or skewed distributions

• A test that compares the typical values between groups

The test tells you:

• Whether one group tends to have higher values than the other

• How strong the difference is (effect size)

• Which group has higher average ranks

Usage

mann_whitney(
  data,
  ...,
  group,
  weights = NULL,
  mu = 0,
  alternative = c("two.sided", "less", "greater"),
  conf.level = 0.95
)

Arguments

Details

Understanding the Results

P-value: If p < 0.05, the groups are significantly different

• p < 0.001: Very strong evidence of difference

• p < 0.01: Strong evidence of difference

• p < 0.05: Moderate evidence of difference

• p >= 0.05: No significant difference found

Effect Size r (How big is the difference?):

• |r| < 0.1: Negligible difference

• 0.1 to < 0.3: Small difference

• 0.3 to < 0.5: Medium difference

• 0.5 or higher: Large difference

Rank Mean Difference:

• Positive: Group 1 tends to have higher values

• Negative: Group 2 tends to have higher values

• Zero: Groups have similar distributions

When to Use This

Use Mann-Whitney test when:

• Your data is not normally distributed (skewed, outliers)

• You have ordinal data (rankings, Likert scales)

• Sample sizes are small (< 30 per group)

• You want a robust alternative to the t-test

• You're comparing satisfaction ratings, income, or other skewed variables

Advantages Over t-test

• Works with any data distribution

• Not affected by outliers

• Valid for ordinal data

• No assumptions about variance

• More robust for real-world data

Tips for Success

• Each group should have at least 5 observations

• The test compares distributions, not just means

• Look at both p-values and effect sizes

• Consider plotting the data to see the pattern

Weighted variants

The weighted test is the design-based Lumley-Scott (2013) rank test (Horvitz-Thompson midranks with a sandwich variance), validated against survey::svyranktest() rather than SPSS: SPSS NPAR TESTS ignores WEIGHT BY, so no SPSS reference exists for weighted results. The weighted descriptive U and W are design-based rank quantities and may differ from SPSS's expanded-data U; the Z statistic and p-value are the validated quantities.

• Use this for Likert scales and rating data

Value

Test results showing whether groups differ, including:

• U and W statistics (test statistics)

• Z-score and p-value (are groups different?)

• Effect size r (r_effect, how big is the difference?)

• Rank means for each group (which group is higher?) Use summary() for the full SPSS-style output with toggleable sections.

References

Mann, H. B., & Whitney, D. R. (1947). On a test of whether one of two random variables is stochastically larger than the other. The Annals of Mathematical Statistics, 18(1), 50-60.

Wilcoxon, F. (1945). Individual comparisons by ranking methods. Biometrics Bulletin, 1(6), 80-83.

Lumley, T., & Scott, A. (2013). Two-sample rank tests under complex sampling. Biometrika, 100(4), 831-842.

See Also

wilcox.test for the base R Wilcoxon test function.

svyranktest for survey-weighted rank tests.

t_test for parametric t-tests.

summary.mann_whitney for detailed output with toggleable sections.

Other hypothesis_tests: ancova(), binomial_test(), chi_square(), chisq_gof(), factorial_anova(), fisher_test(), friedman_test(), kruskal_wallis(), mcnemar_test(), oneway_anova(), t_test(), wilcoxon_test()

Examples

# Load required packages and data
library(dplyr)
data(survey_data)

# Basic Mann-Whitney test (non-parametric comparison)
survey_data %>%
  mann_whitney(age, group = gender)

# Multiple variables
survey_data %>%
  mann_whitney(age, income, life_satisfaction, group = region)

# Using tidyselect helpers
survey_data %>%
  mann_whitney(starts_with("trust_"), group = gender)

# Weighted analysis
survey_data %>%
  mann_whitney(income, group = region, weights = sampling_weight)

# Grouped analysis (separate tests for each education level)
survey_data %>%
  group_by(education) %>%
  mann_whitney(life_satisfaction, group = gender)

# One-sided test
survey_data %>%
  mann_whitney(life_satisfaction, group = region, alternative = "greater")

# --- Three-layer output ---
result <- survey_data %>%
  mann_whitney(income, group = gender, weights = sampling_weight)
result              # compact one-line overview
summary(result)     # full detailed output with all sections
summary(result, effect_sizes = FALSE)  # hide effect sizes

Description

marginal_effects() computes average marginal effects (AMEs) for a fitted logistic_regression model — the Stata margins, dydx(*) workhorse. AMEs translate logit coefficients into the language reports actually use: percentage-point changes in the predicted probability.

For each continuous predictor, the AME is the derivative of the predicted probability with respect to that predictor, averaged over the observed sample. For each factor level, it is the average discrete change in predicted probability compared to the reference level.

Usage

marginal_effects(model, conf.level = 0.95, ...)

Arguments

Details

Understanding the Output

An AME of 0.03 for age means: averaged over the sample, one additional year of age increases the predicted probability of the outcome by 3 percentage points. Unlike odds ratios, AMEs are directly comparable across models and across groups, which is why they are the preferred reporting style in much of the social sciences.

When to Use This

• To report logistic regression results on the probability scale instead of (or alongside) odds ratios

• To compare predictor effects across groups (run on a group_by()-fitted model)

Technical Details

Continuous predictors use a centered numerical derivative of the predicted probability; factor, character and logical predictors use the average discrete change against the reference level (the first level; FALSE for logicals). Effects are computed per variable from the original data: a variable that enters through several terms (x + I(x^2), poly(x, 2), log(x), interactions) gets one AME that moves all of those terms together. A numeric variable that enters only as a categorical term (e.g. factor(x)) cannot be differentiated; it is skipped with a warning. Standard errors come from the delta method with the analytic gradient of the AME with respect to the coefficients and the model's Wald covariance matrix, matching the default in Stata's margins and R's margins package. Weighted models average with their frequency weights (unrounded, Charter §5.1); at weights == 1 the weighted AME reduces exactly to the unweighted one.

Linear regression: AMEs are not needed there — for a linear model without interactions or transformations, the unstandardized coefficient B is the marginal effect, already shown in the linear_regression coefficients table. Calling marginal_effects() on a linear_regression result says so instead of duplicating the table.

Validation: SPSS has no AME procedure, so this function is Tier 4 (Internal) under the Validation Charter — verified against the analytic logit-AME formula and an independent finite-difference delta-method recomputation, not against SPSS output.

Value

An object of class "marginal_effects" whose $results tibble holds one row per predictor term (and group combination) with:

Term

Predictor name; factor rows read "var: level vs. ref"

Type

"dydx" (continuous derivative) or "discrete" (factor-level contrast)

AME

Average marginal effect on the probability scale

SE

Delta-method standard error

z, p_value

Wald test of the AME

CI_lower, CI_upper

Confidence interval at conf.level

See Also

logistic_regression for fitting the model.

summary.marginal_effects for detailed output.

Other regression: linear_regression(), logistic_regression()

Examples

data(survey_data)
survey_data$high_satisfaction <- as.integer(survey_data$life_satisfaction >= 4)

model <- logistic_regression(survey_data,
                             high_satisfaction ~ age + income + education)
marginal_effects(model)

# Weighted model
model_w <- logistic_regression(survey_data, high_satisfaction ~ age + income,
                               weights = sampling_weight)
marginal_effects(model_w)

# --- Three-layer output ---
ame <- marginal_effects(model)
ame                 # compact overview
summary(ame)        # full detailed output

Description

mcnemar_test() tests whether paired proportions have changed between two dichotomous measurements. Use this for before/after comparisons of categorical outcomes.

Think of it as:

• A paired comparison test for binary (yes/no) data

• The categorical equivalent of a paired t-test

• Tests whether the proportion of "changers" is symmetric

The test tells you:

• Whether paired proportions changed significantly

• Both asymptotic and exact p-values for maximum reliability

• The number of discordant pairs (who actually changed)

Usage

mcnemar_test(data, var1, var2, weights = NULL, correct = TRUE, ...)

Arguments

Details

Understanding the Results

P-value: If p < 0.05, the paired proportions are significantly different

• p < 0.001: Very strong evidence of change

• p < 0.01: Strong evidence of change

• p < 0.05: Moderate evidence of change

• p >= 0.05: No significant change found

Exact vs Asymptotic: The exact binomial p-value is more reliable for small samples. For large samples, both p-values will be very similar.

Discordant Pairs: Only pairs where the two measurements differ (b and c) contribute to the test. If b approximately equals c, there is no evidence of systematic change.

When to Use This

Use McNemar's test when:

• You have paired or matched binary data

• You're comparing before/after proportions

• Both variables must be dichotomous (exactly 2 levels)

The McNemar Statistic

For a 2x2 table with discordant cells b and c:

$\chi^2 = \frac{(|b - c| - 1)^2}{b + c}$

(with continuity correction)

The exact test uses a binomial test on the discordant pairs.

Relationship to Other Tests

• For unpaired categorical data: Use chi_square() instead

• For paired ordinal/continuous data: Use wilcoxon_test() instead

• For paired data with more than 2 levels: Consider the Bowker test of symmetry

SPSS Equivalent

SPSS: CROSSTABS /STATISTICS=MCNEMAR

Value

Test results showing whether paired proportions changed, including:

• McNemar chi-square statistic (chi_squared, with continuity correction)

• Asymptotic p-value

• Exact binomial p-value (two-sided)

• 2x2 contingency table

• Discordant pair counts (b and c)

References

McNemar, Q. (1947). Note on the sampling error of the difference between correlated proportions or percentages. Psychometrika, 12(2), 153-157.

See Also

chi_square for independence tests.

wilcoxon_test for paired non-parametric tests on ordinal data.

Other hypothesis_tests: ancova(), binomial_test(), chi_square(), chisq_gof(), factorial_anova(), fisher_test(), friedman_test(), kruskal_wallis(), mann_whitney(), oneway_anova(), t_test(), wilcoxon_test()

Examples

# Load required packages and data
library(dplyr)
data(survey_data)

# Create dichotomous variables
test_data <- survey_data %>%
  mutate(
    trust_gov_high = as.integer(trust_government >= 4),
    trust_media_high = as.integer(trust_media >= 4)
  )

# McNemar test
test_data %>%
  mcnemar_test(var1 = trust_gov_high, var2 = trust_media_high)

# Grouped analysis
test_data %>%
  group_by(region) %>%
  mcnemar_test(var1 = trust_gov_high, var2 = trust_media_high)

Description

multiple_response() analyzes "check all that apply" survey questions — the SPSS MULT RESPONSE procedure. It takes a set of 0/1 indicator variables (one per answer option) and produces the two tables SPSS users know:

• Without by: the frequencies table — number of mentions per option, percent of responses (sums to 100%), and percent of cases (sums above 100%, because respondents can tick several options).

• With by: the crosstab of the set against a categorical variable — mentions and case-based column percentages per group.

Usage

multiple_response(data, ..., by = NULL, counted = 1, weights = NULL)

Arguments

Details

Understanding the Output

The two percentage columns answer different questions:

• Percent of responses: "Of all boxes ticked, how many were this option?" — describes the mix of answers.

• Percent of cases: "What share of respondents ticked this option?" — usually the number reports need. It sums above 100% whenever respondents tick more than one box.

Case handling

Following SPSS MULT RESPONSE, a case is valid if it has at least one non-missing indicator in the set; cases missing on all indicators are excluded and reported as missing. Within a valid case, missing indicators simply contribute no mention. With by, cases missing on the by variable are excluded too.

Technical Details

Weighted analyses count mentions and cases as unrounded sums of weights (Charter §5.1); displayed Ns are rounded. With weights == 1 the weighted table reduces exactly to the unweighted one. Only dichotomy sets (indicator + counted value) are supported; SPSS's category-range sets are not.

An SPSS v29 MULT RESPONSE reference run is pending; until it lands the counts and percentages are verified against direct hand-computation from the indicator matrix (see the SPSS compatibility vignette).

Value

An object of class "multiple_response" whose $results tibble holds one row per answer option (and group combination) with:

Option

Variable name of the option

Label

The option's variable label (falls back to the name)

n

Number of mentions (weighted sum when weighted)

pct_responses

Share of all mentions — sums to 100%

pct_cases

Share of valid cases mentioning the option — can sum above 100%

With by, $by_results additionally holds the long-form crosstab (columns by_level, Option, Label, n, pct_cases). $n_cases is the number of valid cases (at least one non-missing indicator), $n_responses the total number of mentions.

See Also

frequency for single-variable frequency tables.

crosstab for ordinary two-variable crosstabs.

summary.multiple_response for detailed output.

Other descriptive: crosstab(), describe(), frequency(), normality_test()

Examples

library(dplyr)
data(survey_data)

# Build an example set: which institutions does a respondent
# trust highly (rating of 4 or 5)?
trust <- survey_data %>%
  mutate(
    gov     = as.integer(trust_government >= 4),
    media   = as.integer(trust_media >= 4),
    science = as.integer(trust_science >= 4)
  )

# Frequencies table: % of responses vs. % of cases
multiple_response(trust, gov, media, science)

# Crossed against gender, with weights
multiple_response(trust, gov, media, science,
                  by = gender, weights = sampling_weight)

# --- Three-layer output ---
result <- multiple_response(trust, gov, media, science)
result              # full tables
summary(result)     # same tables, with section toggles