DurgaDiff.formula {Durga}

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. 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. 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. 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)