superbData {superb}

Obtain summary statistics with correct error bars.

Description

The function suberbData() computes standard error or confidence interval for various descriptive statistics under various designs, sampling schemes, population size and purposes, according to the suberb framework. See (Cousineau et al. 2021) for more.

Usage

superbData(
  data,
  BSFactors = NULL,
  WSFactors = NULL,
  WSDesign = "fullfactorial",
  factorOrder = NULL,
  variables,
  statistic = "mean",
  errorbar = "CI",
  gamma = 0.95,
  adjustments = list(purpose = "single", popSize = Inf, decorrelation = "none",
    samplingDesign = "SRS"),
  preprocessfct = NULL,
  postprocessfct = NULL,
  clusterColumn = ""
)

Arguments

data

Dataframe in wide format

BSFactors

The name of the columns containing the between-subject factor(s)

WSFactors

The name of the within-subject factor(s)

WSDesign

the within-subject design if not a full factorial design (default "fullfactorial")

factorOrder

Order of factors as shown in the graph (x axis, groups, horizontal panels, vertical panels)

variables

The dependent variable(s)

statistic

The summary statistic function to use

errorbar

The function that computes the error bar. Should be "CI" or "SE" or any function name. Defaults to "CI"

gamma

The coverage factor; necessary when errorbar == "CI". Default is 0.95.

adjustments

List of adjustments as described below. Default is adjustments = list(purpose = "single", popSize = Inf, decorrelation = "none", samplingDesign = "SRS")

preprocessfct

is a transform (or vector of) to be performed first on data matrix of each group

postprocessfct

is a transform (or vector of)

clusterColumn

used in conjunction with samplingDesign = "CRS", indicates which column contains the cluster membership

Details

The possible adjustements are the following

• popsize: Size of the population under study. Defaults to Inf

• purpose: The purpose of the comparisons. Defaults to "single". Can be "single", "difference", or "tryon".

• decorrelation: Decorrelation method for repeated measure designs. Chooses among the methods "CM", "LM", "CA" or "none". Defaults to "none".

• samplingDesign: Sampling method to obtain the sample. implemented sampling is "SRS" (Simple Randomize Sampling) and "CRS" (Cluster-Randomized Sampling).

Value

a list with (1) the summary statistics in summaryStatistics (2) the raw data in long format in rawData (using numeric levels for repeated-measure variables).

References

Cousineau D, Goulet M, Harding B (2021). “Summary plots with adjusted error bars: The superb framework with an implementation in R.” Advances in Methods and Practices in Psychological Science, 4, 1–18. doi:10.1177/25152459211035109.

Examples

# Basic example using a built-in dataframe as data; 
# by default, the mean is computed and the error bar are 95% confidence intervals
# (it also produces a $rawData dataframe, not shown here)
res <- superbData(ToothGrowth, BSFactors = c("dose", "supp"), 
  variables = "len") 
res$summaryStatistics

# Example introducing adjustments for pairwise comparisons 
# and assuming that the whole population is limited to 200 persons
res <- superbData(ToothGrowth, BSFactors = c("dose", "supp"), 
  variables = "len",  
  statistic = "median", errorbar = "CI", gamma = .80,
  adjustments = list( purpose = "difference", popSize = 200) )
res$summaryStatistics