Package 'mfcurve'

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

data	A data frame containing the variables.
outcome	Name of the numeric outcome variable (string).
factors	Character vector of factor variable names for grouping.
test	Reference for t-tests: "mean", "zero", or "leave-one-out". Passed to preprocessing. Default is "mean".
alpha	Significance level for t-tests and confidence intervals. Default is 0.05.
showTitle	Logical. Show the plot title? Default is TRUE.
SaveProcessedData	Logical. If TRUE, saves group-level statistics to the current working directory as timestamped files: group_stats_*.csv and group_stats_*.rds. Default is FALSE.
mode	Factor labeling mode: "collapsed" (default) or "expanded".
rounding	Number of digits to round outcome statistics. Default is 2.
plotOrigin	Logical. Force axes to include 0? Default is FALSE.
CI	Logical. Display confidence intervals? Default is TRUE.
showGrandMean	Logical. Show the grand mean line? Default is TRUE.
showSigStars	Logical. Show markers for significant values? Default is TRUE.

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 the working directory 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

group_stats_vis	Data frame containing group-level summary statistics.
lower_data	Data frame defining the factor structure for the lower panel.
grand_mean	Numeric. The overall mean of the outcome variable.
outcome	Name of the outcome variable (string).
factors	Character vector of factor variable names.
level	Level for confidence intervals (e.g., 0.95).
rounding	Number of digits to round outcome values. Default is 2.
showTitle	Logical. Show the plot title? Default is TRUE.
plotOrigin	Logical. Force axes to include 0? Default is FALSE.
CI	Logical. Display confidence intervals? Default is TRUE.
mode	Labeling mode for the lower panel: "collapsed" (default) or "expanded".
showGrandMean	Logical. Show the grand mean overall groups. Default is TRUE.
showSigStars	Logical. Flag significant results. Default is TRUE.

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

data	Data frame containing the variables.
outcome	Name of the numeric outcome variable (string).
factors	Character vector of factor variable names for grouping.
alpha	Significance level for the t-tests and confidence intervals. Default is 0.05.
test	Reference for t-tests: "mean" (grand mean), "leave-one-out" (mean of all other groups), or "zero" (testing against 0).

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.

---