DurgaDiff.formula: Formula interface for estimating group mean differences

In Durga: Effect Size Estimation and Visualisation

Formula interface for estimating group mean differences

Description

Estimates differences between groups in preparation for plotting by DurgaPlot. The formula interface allows the value and group columns to be specified in a formula, which means, for example, that transformation functions can be applied to columns.

Usage

## S3 method for class 'formula'
DurgaDiff(x, data = NULL, id.col, ...)

Arguments

x	a formula, such as y ~ grp, where y is a numeric vector of data values or measurements to be split into groups according to the grouping variable grp, which is typically a categorical value. Multiple group columns can be separated by +, in which case Durga treats each unique combination of group variables as a distinct group.
data	a data.frame (or list) from which the variables in formula should be taken.
id.col	Specify for paired data/repeated measures/with-subject comparisons only. Name or index of ID column for repeated measures/paired data. Observations for the same individual must have the same ID. For non-paired data, do not specify an id.col, (or use id.col = NA).
...	Arguments passed on to DurgaDiff.default groups Vector of group names. Defaults to all groups in x in natural order. If groups is a named vector, the names are used as group labels for plotting or printing. If data.col and group.col are not specified, x is assumed be to in wide format, and groups must be a list of column names identifying the group/treatment data (see example). contrasts Specify the pairs of groups to be compared. By default, all pairwise differences are generated. May be a single string, a vector of strings, or a matrix. Specify NULL to avoid calculating any contrasts. See Details for more information. effect.type Type of group difference to be estimated. Values cannot be abbreviated. See Details for further information. R The number of bootstrap replicates. R should be larger than your sample size, so the default value of 1000 may need to be increased for large sample sizes. If R <= nrow(x), an error such as "Error in bca.ci... estimated adjustment 'a' is NA" will be thrown. Additionally, warnings such as "In norm.inter(t, adj.alpha) : extreme order statistics used as endpoints" may be avoided by increasing R. Specify R = NA if you do not wish to calculate any CIs, either for group means for for effect sizes. This may be useful if Durga is only being used for plotting large data sets. boot.params Optional list of additional names parameters to pass to the boot function. ci.conf Numeric confidence level of the required confidence interval, e.g. ci.conf = 0.95 specifies that 95\ be calculated. Applies to both CI of effect sizes and CI of group means. boot.ci.params Optional list of additional names parameters to pass to the boot.ci function. na.rm a logical evaluating to TRUE or FALSE indicating whether NA values should be stripped before the computation proceeds. If TRUE for "paired" data (i.e. id.col is specified), all rows (observations) for IDs with missing data are stripped.

Details

Applies the formula, x, and a data set, data, to construct a data frame that is then passed, with all remaining arguments, to the function DurgaDiff.default.

Value

A DurgaDiff object, which is a list containing:

group.statistics	Matrix with a row for each group, columns are: mean, median, sd (standard deviation), se (standard error of the mean), CI.lower and CI.upper (lower and upper bootstrapped confidence intervals of the mean, confidence level as set by the ci.conf parameter) and n (group sample size). If there are fewer than 3 distinct values in the group, or if R is NA, the confidence interval will not be calculated and CI.lower and CI.upper will be NA.
group.differences	List of DurgaGroupDiff objects, which are boot objects with added confidence interval information. See boot and boot.ci. This element will be missing if contrasts is empty or NULL
groups	Vector of group names
group.names	Labels used to identify groups
effect.type	Value of effect.type parameter
effect.name	Name of the effect type; may include formatting such as subscripts
effect.name.print	Text-only version of effect.name for printing; subscripts are indicated by "_"
data.col	Value of data.col parameter; may be an index or a name
data.col.name	Name of the data.col column
group.col	Value of group.col parameter; may be an index or a name
group.col.name	Name of the group.col column
id.col	Value of id.col parameter. May be NULL
paired.data	TRUE if paired differences were estimated
data	The input data frame (x), or the reshaped (long format) data frame if the input data set was in wide format
call	How this function was called

A DurgaGroupDiff object is a boot object (as returned by boot) with added bootci components (as returned by boot.ci) and components identifying the groups used to estimate the difference. Particularly relevant members are:

t0	The observed value of the statistic
bca[4]	The lower endpoint of the confidence interval
bca[5]	The upper endpoint of the confidence interval
groups	The difference is estimated on groups[1] - groups[2]

References

• Cumming, G. (2012). Understanding the new statistics : effect sizes, confidence intervals, and meta-analysis (1st ed.). New York: Routledge.

• Delacre, M., Lakens, D., Ley, C., Liu, L., & Leys, C. (2021). Why Hedges' g* based on the non-pooled standard deviation should be reported with Welch's t-test. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.31234/osf.io/tu6mp")}

• Khan, M. K., & McLean, D. J. (2023). Durga: An R package for effect size estimation and visualisation. bioRxiv, 2023.2002.2006.526960. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.1101/2023.02.06.526960")}

• Lakens, D. (2013). Calculating and reporting effect sizes to facilitate cumulative science: a practical primer for t-tests and ANOVAs. Frontiers in Psychology, 4. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.3389/fpsyg.2013.00863")}

See Also

DurgaDiff.default, boot, boot.ci, DurgaPlot

Examples

d <- DurgaDiff(log(sugar) ~ treatment, insulin, id.col = "id")
print(d)

Durga documentation built on May 29, 2024, 12:33 p.m.