participants_book {esmtools}

Generate a participants' book

Description

The 'participants_book()' function creates a participants' book, which provides a concise summary of participants' data from an intensive longitudinal study, such as Experience Sampling Method (ESM). The book is generated using the DT package, and each participant is represented by a row in the table. The participants' book displays various information about participants' response behaviors, including compliance rate, study duration, and start time. Additionally, it provides descriptive statistics and time series plots for the variables of interest. See an example here: https://preprocess.esmtools.com/pages/90_Participant_book.html.

Usage

participants_book(
  df,
  idvar = "id",
  obsnovar = "obsno",
  focusvar = NULL,
  timevar = NULL,
  validvar = NULL,
  compliancevar = NULL,
  obsno_max = NULL,
  list_behaviors = c("min_date", "max_date", "nb_answer", "compliance"),
  list_stats = c("mean", "sd", "n_length", "n_unique"),
  viz = list(c("ts", "hist")),
  html_output = NULL,
  kable_out = TRUE,
  min_max_regularize = TRUE
)

Arguments

df

A dataframe containing the participant data

idvar

The name of the column in the dataframe that represents the participant identifier

obsnovar

The name of the column in the dataframe that represents the beep number

focusvar

A vector of variable names representing the variables of interest in the dataframe

timevar

The name of the column in the dataframe that represents the timestamp

validvar

The name of the column in the dataframe that represents the validity of responses

compliancevar

The name of the column in the dataframe that represents the compliance rate (alternatively, if NULL, the compliance score is computed as the number of rows divided by obsno_max)

obsno_max

The maximum number of beeps for computing the compliance score (only used if compliancevar is NULL)

list_behaviors

A vector indicating the types of participants' response behavior information to display. Valid options are "min_date", "max_date", "nb_answer", and "compliance".

list_stats

A vector indicating the types of descriptive statistics to display. Valid options are "mean", "sd", "range", "n_length", and "n_unique".

viz

A vector indicating the visualization type to display for each focusvar variable. Valid options are "ts" (time series plot) and "hist" (histogram).

html_output

Define a file name (e.g., "path/to/participant_book.html") to create an html output version of the participant book.

kable_out

When TRUE, output is in kable version. If FALSE, use DT package.

min_max_regularize

Whether to regularize the y-axis or x-axis limits across plots based on the global minimum and maximum values. Default is TRUE.

Value

A kable or datatable object (from the DT package), representing the participants' book.

Examples

 participants_book(esmdata_preprocessed,
   idvar = "id",
   obsnovar = "obsno",
   focusvar = c("pos_aff", "neg_aff"),
   timevar = "start",
   validvar = "valid",
   obsno_max = 70,
   list_behaviors = c("min_date", "max_date", "nb_answer", "compliance"),
   list_stats = c("mean", "sd", "range", "n_length", "n_unique"),
   viz = list(c("ts", "hist"), c("ts", "hist"))
 )