check_discretization: Check time/space discretization via reference comparison

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

Check time/space discretization via reference comparison

Description

check_discretization() helps you choose or check time (dt) and space (dx) discretization settings. It computes a high-precision reference solution of the model's PDFs with dt_ref/dx_ref, and then compares the reference PDFs to the discretization settings of the supplied object, using the Hellinger distance per condition. Smaller distances indicate closer agreement with the reference — i.e., a sufficiently fine grid.

There are not yet overall and officially published recommendations on how large the Hellinger distance can be without affecting model precision, and this very likely will depend on the model itself. Based on some preliminary simulations using dmc_dm(), we would recommend trying to keep the Hellinger Distance at best below 10 percent. However, we also observed for extreme parameter values that the Hellinger distance can be even larger without sacrificing the qualitative model behavior, and vice versa! It is thus best to iterate between plotting model predictions and calculating the Hellinger Distance, to ensure that you can best interpret this quantity for your model at hand. Furthermore, we recommend to run parameter recoveries using simulate_data() and estimate_dm(), to check if you can recover data generated under your model with fine discretization using that same model with coarse discretization.

Usage

check_discretization(object, ...)

## S3 method for class 'drift_dm'
check_discretization(
  object,
  ...,
  dt_ref = 0.001,
  dx_ref = 0.001,
  round_digits = 5
)

## S3 method for class 'fits_ids_dm'
check_discretization(object, ...)

## S3 method for class 'fits_agg_dm'
check_discretization(object, ...)

Arguments

object	a drift_dm, fits_agg_dm, or fits_ids_dm object. (the latter two are returned by estimate_dm())
...	further arguments passed forward to the respective method.
dt_ref, dx_ref	numeric scalars, providing a fine time or space step size for the reference solution. Defaults to 0.001.
round_digits	number of decimal places to which the final Hellinger distances are rounded (default: 5).

Details

Under the hood, for each condition, we concatenate the lower- and upper- boundary PDFs (pdf_l, pdf_u), interpolate the model PDFs to a time space matching with the reference PDFs, and then compute the Hellinger distance: H(p,q) = \sqrt{1 - \int \sqrt{p(t)\,q(t)}\,dt}

There are not yet overall, officially published recommendations on how large the Hellinger distance can be without affecting model precision, and this may even depend on the specific model. Based on preliminary simulations, we recommend trying to keep the average Hellinger distance below 5\

The reference discretizations (dt_ref/dx_ref) must be at least as fine as the object's current discretization settings (dt_model/dx_model). If dt_model < dt_ref or dx_model < dx_ref, an error is raised because the “reference” would not be the finest solution.

Value

a named numeric vector of Hellinger distances (one per condition) if object is of type drift_dm or fits_agg_dm. A data.frame of Hellinger distances across IDs and conditions if object is of type fits_ids_dm. Hellinger distances are in ⁠[0, 1]⁠, where 0 means identical to the reference.

See Also

estimate_dm(), trapz()

Examples

# Example:
my_model <- ratcliff_dm()

# Assess current (dt=0.0075, dx=0.02) against a fine reference:
check_discretization(my_model)

# If distances are near zero across conditions, the current grid is adequate.

dRiftDM documentation built on Dec. 1, 2025, 5:08 p.m.