summarize_by_id: Calculate ID-level longitudinal summaries (linear slope,...
In wfforrest/maeve: Modeling Accessories Enabling Visualization of Experiments

Description Usage Arguments Details Value Author(s) References Examples

Computes a longitudinal summary 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'.

summarize_by_id(
  study_data_frame,
  metric = c("linear", "ITGR", "AUC"),
  method = c("trapezoid", "step", "spline"),
  check_data = FALSE,
  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 with factors for group_name and subject_ID, numeric columns for x_name (i.e., time) and endpoint_name (i.e., response).
`metric`	character name method for longitudinal summary.
`method`	character name method for computing AUC. Passed directly to DescTools::AUC( ..., method = ... ).
`check_data`	logical whether to pass "study_data_frame" through maeve::check_study_data_frame() to check for problems.
`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]] )"). If subtract_starting_value = TRUE, 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'. ITGR and AUC summaries will be x-range normalized based on the value of 'xrange_norm_method'. Under default settings, each should then be close to the linear slope summary when the longitudinal trace is fairly linear. With the default settings, the "AUC" and "ITGR" statistics are empirical, subject-specific versions of the "eGaIT" and "eDOT" summary statistics, while the "linear" statistic is the least-squares slope of "y" regressed on "x" after any transformations.

If a subject_ID has only one observation, its summary is ambiguous, since, its literal AUC or vertical shift 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