calc_stats: Calculate Statistics

In dRiftDM: Estimating (Time-Dependent) Drift Diffusion Models

Calculate Statistics

Description

calc_stats provides an interface for calculating statistics/metrics on model predictions and/or observed data. Supported statistics include Conditional Accuracy Functions (CAFs), Quantiles, Delta Functions, and fit statistics. Results can be aggregated across individuals.

Usage

calc_stats(object, type, ...)

## S3 method for class 'data.frame'
calc_stats(
  object,
  type,
  ...,
  conds = NULL,
  verbose = 0,
  average = FALSE,
  split_by_ID = TRUE,
  b_coding = NULL
)

## S3 method for class 'drift_dm'
calc_stats(object, type, ..., conds = NULL)

## S3 method for class 'fits_ids_dm'
calc_stats(object, type, ..., verbose = 1, average = FALSE)

## S3 method for class 'stats_dm'
print(
  x,
  ...,
  round_digits = drift_dm_default_rounding(),
  print_rows = 10,
  some = FALSE,
  show_header = TRUE,
  show_note = TRUE
)

## S3 method for class 'stats_dm_list'
print(x, ...)

Arguments

object	an object for which statistics are calculated. This can be a data.frame of observed data, a drift_dm object, or a fits_ids_dm object (see estimate_model_ids).
type	a character vector, specifying the statistics to calculate. Supported values include "cafs", "quantiles", "delta_funs", and "fit_stats".
...	additional arguments passed to the respective method and the underlying calculation functions (see Details for mandatory arguments).
conds	optional character vector specifying conditions to include. Conditions must match those found in the object.
verbose	integer, indicating if information about the progress should be displayed. 0 -> no information, 1 -> a progress bar. Default is 0.
average	logical. If TRUE, averages the statistics across individuals where applicable. Default is FALSE.
split_by_ID	logical. If TRUE, statistics are calculated separately for each individual ID in object (when object is a data.frame). Default is TRUE.
b_coding	a list for boundary coding (see b_coding). Only relevant when object is a data.frame. For other object types, the b_coding of the Object is used.
x	an object of type stats_dm or stats_dm_list, as returned by the function calc_stats().
round_digits	integer, controls the number of digits shown. Default is 3.
print_rows	integer, controls the number of rows shown.
some	logical. If TRUE, a subset of randomly sampled rows is shown.
show_header	logical. If TRUE, a header specifying the type of statistic will be displayed.
show_note	logical. If TRUE, a footnote is displayed indicating that the underlying data.frame can be accessed as usual.

Details

calc_stats is a generic function to handle the calculation of different statistics/metrics for the supported object types. Per default, it returns the requested statistics/metrics.

Conditional Accuracy Function (CAFs)

CAFs are a way to quantify response accuracy against speed. To calculate CAFs, RTs (whether correct or incorrect) are first binned and then the percent correct responses per bin is calculated.

When calculating model-based CAFs, a joint CDF combining both the pdf of correct and incorrect responses is calculated. Afterwards, this CDF is separated into even-spaced segments and the contribution of the pdf associated with a correct response relative to the joint CDF is calculated.

The number of bins can be controlled by passing the argument n_bins. The default is 5.

Quantiles

For observed response times, the function stats::quantile is used with default settings.

Which quantiles are calcuated can be controlled by providing the probabilites, probs, with values in [0, 1]. Default is seq(0.1, 0.9, 0.1).

Delta Functions

Delta functions calculate the difference between quantiles of two conditions against their mean:

• Delta_i = Q_{i,j} - Q_{i,k}

• Avg_i = 0.5 \cdot Q_{i,j} + 0.5 \cdot Q_{i,k}

With i indicating a quantile, and j and k two conditions.

To calculate delta functions, users have to specify:

• minuends: character vector, specifying condition(s) j. Must be in conds(drift_dm_obj).

• subtrahends: character vector, specifying condition(s) k. Must be in conds(drift_dm_obj)

• dvs: character, indicating which quantile columns to use. Default is "Quant_<u_label>". If multiple dvs are provided, then minuends and subtrahends must have the same length, and matching occurs pairwise. In this case, if only one minuend/subtrahend is specified, minuend and subtrahend are recycled to the necessary length.

Fit Statistics

Calculates the Akaike and Bayesian Information Criteria (AIC and BIC). Users can provide a k argument to penalize the AIC statistic (see stats::AIC and AIC.fits_ids_dm)

Value

If type is a single character string, then a subclass of data.frame is returned, containing the respective statistic. Objects of type sum_dist will have an additional attribute storing the boundary encoding (see also b_coding). The reason for returning subclasses of data.frame is to provide custom plot() methods (e.g., plot.cafs). To get rid of the subclass label and additional attributes (i.e., to get just the plain underlying data.frame, users can use unpack_obj()).

If type contains multiple character strings (i.e., is a character vector) a subclass of list with the calculated statistics is returned. The list will be of type stats_dm_list (to easily create multiple panels using the respective plot.stats_dm_list() method).

The print methods print.stats_dm() and print.stats_dm_list() each invisibly return the supplied object x.

Examples

# Example 1: Calculate CAFs and Quantiles from a model ---------------------
# get a model for demonstration purpose
a_model <- ssp_dm(dx = .0025, dt = .0025, t_max = 2)
# and then calculate cafs and quantiles
some_stats <- calc_stats(a_model, type = c("cafs", "quantiles"))
print(some_stats)

# Example 2: Calculate a Delta Function from a data.frame ------------------
# get a data set for demonstration purpose
some_data <- ulrich_simon_data
conds(some_data) # relevant for minuends and subtrahends
some_stats <- calc_stats(
  a_model,
  type = "delta_funs",
  minuends = "incomp",
  subtrahends = "comp"
)
print(some_stats, print_rows = 5)


# Example 3: Calculate Quantiles from a fits_ids_dm object -----------------
# get an auxiliary fits_ids_dm object
all_fits <- get_example_fits_ids()
some_stats <- calc_stats(all_fits, type = "quantiles")
print(some_stats, print_rows = 5) # note the ID column

# one can also request that the statistics are averaged across individuals
print(
  calc_stats(all_fits, type = "quantiles", average = TRUE)
)

dRiftDM documentation built on April 3, 2025, 7:48 p.m.