auc_by_id: Calculate ID-level area-under-curve (AUC) summaries from raw...
In wfforrest/maeve: Modeling Accessories Enabling Visualization of Experiments

Description Usage Arguments Details Value Author(s) References Examples

Computes an area-under-curve (AUC) measure for the (x,y) values from each subject_ID, without any explicit model fit. The AUC is calculated using 'DescTools::AUC(...)', which takes one of 'trapezoid', 'step', 'spline' as its 'method'.

auc_by_id(
  study_data_frame,
  check_data = FALSE,
  method = c("trapezoid", "step", "spline"),
  VST = TRUE,
  xmin = -Inf,
  xmax = Inf,
  subtract_starting_value = TRUE,
  na.rm = TRUE,
  singleton_to_NA = TRUE,
  group_name = maeve_options("group_name"),
  subject_ID = maeve_options("subject_ID"),
  x_name = maeve_options("x_name"),
  endpoint_name = maeve_options("endpoint_name"),
  add_to_endpoint = maeve_options("add_to_endpoint"),
  trans_func_char = maeve_options("trans_func_char"),
  inv_func_char = maeve_options("inv_func_char"),
  test_func_x = maeve_options("test_func_x"),
  xrange_norm_method = maeve_options("xrange_norm_method")
)

`study_data_frame`	data.frame a "well-prepared" data.frame (e.g., processed through maeve::check_study_data_frame() is recommended but not required) with the study data and appropriate columns.
`check_data`	logical whether to pass "study_data_frame" through maeve::check_study_data_frame() to check for problems.
`method`	character name method for computing AUC. Passed directly to DescTools::AUC( ..., method = ... ).
`VST`	logical whether to apply a variance stabilizing transform to endpoint_name values.
`xmin`	numeric left / lower end of the interval.
`xmax`	numeric right / uppper end of the interval.
`subtract_starting_value`	logical whether to subtract, for each subject_ID, the first value in the time series so that each series starts at zero.
`na.rm`	logical whether to remove NA values when computing summaries.
`singleton_to_NA`	logical whether to assign subject_ID cases with a single observation NA or zero.
`group_name`	character column name for the group name factor
`subject_ID`	character column name for the subject name factor
`x_name`	character column name for the x-axis / time field
`endpoint_name`	character column name for the x-axis / time field
`add_to_endpoint`	numeric offset value added to the endpoint before transformation
`trans_func_char`	character function name for transformation of (endpoint_name + add_to_endpoint)
`inv_func_char`	character inverse function for transformation of (endpoint_name + add_to_endpoint)
`test_func_x`	numeric values with which to test that trans_func and inv_func are inverse functions.
`xrange_norm_method`	character method for normalization of spline summary statistics.

If VST == TRUE, each ID-level vector of endpoint values (specified in 'endpoint_name') will be transformed for variance stabilization by adding a constant then transforming (e.g., "y = log( 1 + [[endpoint_name]] )"). Next, the ID-level vector is centered to its first (in time-order) value, i.e, each y-value will have the first y-value subtracted from it. These transformed & centered values then have their AUC relative to the line y = 0 computed by the DescTools::AUC(...) function and given 'method'. Finally, the AUC will be x-range normalized appropriately based on 'xrange_norm_method'. By default, AUC values are divided by half the square of their x-range, which will give a good approximation of the slope if the transformed data are fairly linear.

If a subject_ID has only one observation, its AUC is ambiguous, since its literal AUC must be zero, but so is the x-range over which it is found. by default, these receive NA, but are set to zero if 'singleton_to_NA == FALSE.'

An R data.frame with one row per ID.

Bill Forrest <forrest@gene.com>

Bill Forrest forrest@gene.com

www.r-project.org