mfcurve: Multi-Factor Curve Analysis for Grouped Data in 'R'

Description

Implements multi-factor curve analysis for grouped data in 'R', replicating and extending the functionality of the the 'Stata' ado 'mfcurve' (Krähmer, 2023) https://ideas.repec.org/c/boc/bocode/s459224.html. Related to the idea of specification curve analysis (Simonsohn, Simmons, and Nelson, 2020) doi:10.1038/s41562-020-0912-z. Includes data preprocessing, statistical testing, and visualization of results with confidence intervals.

Author(s)

Maintainer: Maximilian Frank maximilian.frank@psy.lmu.de

Authors:

• Daniel Krähmer Daniel.Kraehmer@soziologie.uni-muenchen.de

• Claudia Weileder maximilian.frank@psy.lmu.de

See Also

Useful links:

• https://github.com/XAM12/mfcurve_R

• Report bugs at https://github.com/XAM12/mfcurve_R/issues

Pipe operator

Description

See magrittr::%>% for details.

Usage

lhs %>% rhs

Arguments

Value

The result of calling rhs(lhs).

Wrapper for mfcurve preprocessing and plotting

Description

Calls mfcurve_preprocessing() and mfcurve_plotting() in sequence to generate a two-panel interactive mfcurve plot.

Usage

mfcurve(
  data,
  outcome,
  factors,
  test = "mean",
  alpha = 0.05,
  showTitle = TRUE,
  SaveProcessedData = FALSE,
  mode = "collapsed",
  rounding = 2,
  plotOrigin = FALSE,
  CI = TRUE,
  showGrandMean = TRUE,
  showSigStars = TRUE
)

Arguments

Details

mfcurve() plots the mean of an outcome variable across all combinations of multiple grouping factors, producing a two-panel interactive plot.

The upper panel shows group means (and confidence intervals, if requested); the lower panel marks which factor levels are present in each group. In the lower panel, factor labels can be displayed in two modes:

• In collapsed mode, each factor occupies only one row. Factor levels are differentiated by marker color.

• In expanded mode, each factor is split into its levels (dummy-coded), with levels listed below each other. Markers indicate whether a specific factor level is present or absent in the group.

While collapsed mode saves space when many factors or levels are present, expanded mode may be more intuitive (especially for readers familiar with specification curves).

mfcurve() allows optional significance testing (t-tests). Group-level statistics can be saved if needed.

Value

Invisibly returns the plotly object representing the two-panel plot. If SaveProcessedData = TRUE, also writes group_stats to CSV and RDS in tempdir() and prints the file paths.

See Also

mfcurve_preprocessing, mfcurve_plotting

Examples

# Simulate data for a 3 x 2 experimental design: 3 treatments (A, B, C), 2 doses (low, high)
set.seed(123)
df <- data.frame(
  treatment = sample(c("A", "B", "C"), 1000, replace = TRUE),
  dose      = sample(c("low", "high"), 1000, replace = TRUE)
)

# Generate self-rated health (scale 1–10) with small group differences
df$self_rated_health <- 6 +
  ifelse(df$treatment == "B", 0.5, ifelse(df$treatment == "C", -0.5, 0)) +
  ifelse(df$dose == "high", 0.3, 0) +
  rnorm(1000, 0, 1.5)

# Restrict health scores to valid range
df$self_rated_health <- pmin(pmax(df$self_rated_health, 1), 10)

# Create mfcurve plot
mfcurve(
  data = df,
  outcome = "self_rated_health",
  factors = c("treatment", "dose"),
  test = "mean"
)

Create a two-panel mfcurve plot from processed statistics

Description

Generates an interactive two-panel plot showing group means (with optional confidence intervals) and corresponding factor combinations.

Usage

mfcurve_plotting(
  group_stats_vis,
  lower_data,
  grand_mean,
  outcome,
  factors,
  level,
  rounding = 2,
  showTitle = TRUE,
  plotOrigin = FALSE,
  CI = TRUE,
  mode = "collapsed",
  showGrandMean = TRUE,
  showSigStars = TRUE
)

Arguments

Value

A plotly object (invisible).

Preprocess data and compute group statistics

Description

Prepares the data and computes descriptive statistics and t-tests for groups defined by combinations of categorical factors.

Usage

mfcurve_preprocessing(data, outcome, factors, alpha = 0.05, test = "mean")

Arguments

Value

A list with:

group_stats

Data frame with computed statistics and CI bounds.

group_stats_vis

Visualization-ready version with rounded values.

lower_data

Data for the lower panel (without y positions).

grand_mean

Overall mean of the outcome variable.

level

Confidence level used.