Calculate and report geometric means (GM) and geometric mean ratios (GMR)

This function is intended to calculate and output geometric means (GM) and geometric mean ratios (GMR) into a data.frame suitable for plotting using the make_forestplot function.

make_gmr_data(
  data,
  x_var,
  id_var,
  by = NULL,
  covariates,
  labels,
  ref_levels,
  paired = FALSE,
  var.equal = TRUE,
  ci = 0.9,
  sep = "\t",
  digits = 3L,
  silent = FALSE
)

Arguments

data: a data.frame of data provided in wide-form and expected to contain one record per individual
x_var: the variable(s) in data for which the GM and GMRs must be calculated
id_var: the variable in data differentiating individual data
by: a stratification variable in data
covariates: a vector of variables in data. They are expected to be categorical variables (either logical, character, or factor) and define the group for which the GM and GMRs of x_var are calculated
labels: a vector of character or expression which defines the labels for the variables set in covariates. Expected to have the same length as covariates
ref_levels: a vector of integer defining the reference level to be used in the calculation of GMRs for the variables set in covariates. Expected to have the same length as covariates
paired: a logical value indicating if the results to be compared in the calculation of GMRs are paired (TRUE) or not (FALSE, default)
var.equal: a logical value indicating if equal variance on the linear scale must be assumed (TRUE, default) or not (FALSE)
ci: a numerical value between 0 and 1 defining the width of the confidence interval around the calculated GMRs
sep: the character that separates counts from GMR + confidence interval in the gmr_n_label output variable
digits: the number of significant digits to apply when creating result labels (see Results)
silent: a logical value indicating whether information messages should be shown (FALSE) or hidden (TRUE)

Value

This function returns a data.frame with one row per variable in covariates and level in these variables. The variables in this data.frame are:

x_var: one of the variables defined in x_var,
y_var: one of the variables defined in covariates,
y_label: the label associated with each variables defined in covariates; one of the label defined in labels, or, if this argument was not defined, either the name of the variables and its 'label' attributes in data,
by: one of the level of the by variable,
value: one of the level of the covariates variables
n: the number of individuals included in this particular level of y_var and by; records with missing value of x_var are excluded
reference: a logical variable defining whether this particular level of y_var is the reference for the calculation of GMRs
gm: the GM value for this particular level of y_var and by
gm_lo: the lower limit of the GM confidence interval
gm_hi: the upper limit of the GM confidence interval
gm_label: the GM label; structured as X1 [X2, X3], where X1 is gm, X2 is gm_lo, X3 is gm_hi, and X1, X2, and X3 are formatted to digits significant digits
gmr: the GMR value for this particular level of y_var and by with respect to the reference level
gmr_lo: the lower limit of the GMR confidence interval
gmr_hi: the upper limit of the GMR confidence interval
gmr_label: the GMR label; structured as X1 [X2, X3], where X1 is gmr, X2 is gmr_lo, X3 is gmr_hi, and X1, X2, and X3 are formatted to digits significant digits
gmr_n_label: the GMR label with n; structured as X1 [X2, X3] n = X4, where X1 is gmr, X2 is gmr_lo, X3 is gmr_hi, X4 is n, and X1, X2, and X3 are formatted to digits significant digits

y_var, y_label, and value are coerced to factors to facilitate plotting using make_forestplot.

Examples

if (FALSE) { # \dontrun{
# Use expo dataset provided in the ggcognigen package

make_gmr_data(
  data = expo,
  x_var = c('CMAXSS', 'AUCSS', 'CMINSS'),
  id_var = 'ID',
  by = NULL,
  covariates = c('AGE', 'WTKG', 'BMI', 'SEXF', 'RFCAT', 'CPCAT'),
  labels = c(
    expression('Age'~'(y)'),
    expression('Body'~'Weight'~'(kg)'),
    expression('Body'~'Mass'~'Index'~'(kg/'*m^2*')'),
    expression('Sex'),
    expression('Renal'~'Function'),
    expression('Hepatic'~'Function')
  ),
  ref_levels = c(2, 3, 2, 1, 1, 1),
  digits = 3,
  silent = TRUE
)

# same example with tidyverse syntax
expo %>%
  make_gmr_data(
    x_var = c(CMAXSS, AUCSS, CMINSS),
    id_var = ID,
    by = NULL,
    covariates = c(AGE, WTKG, BMI, SEXF, RFCAT, CPCAT),
    labels = c(
      expression('Age'~'(y)'),
      expression('Body'~'Weight'~'(kg)'),
      expression('Body'~'Mass'~'Index'~'(kg/'*m^2*')'),
      expression('Sex'),
      expression('Renal'~'Function'),
      expression('Hepatic'~'Function')
    ),
    ref_levels = c(2, 3, 2, 1, 1, 1),
    digits = 3,
    silent = TRUE
  )
} # }