R: Smoothes and plots adjusted longitudinal measurements

acc_loess {dataquieR}

R Documentation

Smoothes and plots adjusted longitudinal measurements

Description

The following R implementation executes calculations for quality indicator "Unexpected location" (see here. Local regression (LOESS) is a versatile statistical method to explore an averaged course of time series measurements (Cleveland, Devlin, and Grosse 1988). In context of epidemiological data, repeated measurements using the same measurement device or by the same examiner can be considered a time series. LOESS allows to explore changes in these measurements over time.

Descriptor

Usage

acc_loess(
  resp_vars,
  group_vars = NULL,
  time_vars,
  co_vars = NULL,
  study_data,
  meta_data,
  label_col = NULL,
  min_obs_in_subgroup = 30,
  resolution = 80,
  comparison_lines = list(type = c("mean/sd", "quartiles"), color = "grey30", linetype =
    2, sd_factor = 0.5),
  mark_time_points = getOption("dataquieR.acc_loess.mark_time_points", FALSE),
  plot_observations = getOption("dataquieR.acc_loess.plot_observations", TRUE),
  plot_format = "AUTO"
)

Arguments

`resp_vars`	variable the name of the continuous measurement variable
`group_vars`	variable the name of the observer, device or reader variable
`time_vars`	variable the name of the variable giving the time of measurement
`co_vars`	variable list a vector of covariables for adjustment, for example age and sex. Can be NULL (default) for no adjustment.
`study_data`	data.frame the data frame that contains the measurements
`meta_data`	data.frame the data frame that contains metadata attributes of study data
`label_col`	variable attribute the name of the column in the metadata with labels of variables
`min_obs_in_subgroup`	integer (optional argument) If `group_vars` is specified, this argument can be used to specify the minimum number of observations required for each of the subgroups. Subgroups with fewer observations are excluded. The default number is `30`.
`resolution`	numeric the maximum number of time points used for plotting the trend lines
`comparison_lines`	list type and style of lines with which trend lines are to be compared. Can be mean +/- 0.5 standard deviation (the factor can be specified differently in `sd_factor`) or quartiles (Q1, Q2, and Q3). Arguments `color` and `linetype` are passed to `ggplot2::geom_line()`.
`mark_time_points`	logical mark time points with observations (caution, there may be many marks)
`plot_observations`	logical show observations as scatter plot in the background. If there are `co_vars` specified, the values of the observations in the plot will also be adjusted for the specified covariables.
`plot_format`	enum AUTO \| COMBINED \| FACETS \| BOTH. Return the plot as one combined plot for all groups or as facet plots (one figure per group). `BOTH` will return both variants, `AUTO` will decide based on the number of observers.

Details

If mark_time_points or plot_observations is selected, but would result in plotting more than 400 points, only a sample of the data will be displayed.

Limitations

The application of LOESS requires model fitting, i.e. the smoothness of a model is subject to a smoothing parameter (span). Particularly in the presence of interval-based missing data, high variability of measurements combined with a low number of observations in one level of the group_vars may distort the fit. Since our approach handles data without knowledge of such underlying characteristics, finding the best fit is complicated if computational costs should be minimal. The default of LOESS in R uses a span of 0.75, which provides in most cases reasonable fits. The function acc_loess adapts the span for each level of the group_vars (with at least as many observations as specified in min_obs_in_subgroup and with at least three time points) based on the respective number of observations. LOESS consumes a lot of memory for larger datasets. That is why acc_loess switches to a generalized additive model with integrated smoothness estimation (gam by mgcv) if there are 1000 observations or more for at least one level of the group_vars (similar to geom_smooth from ggplot2).

Value

a list with: