Fit the meta-d' model using brms package

This function is a wrapper around brms::brm() using a custom family for the meta-d' model.

Usage

fit_metad(
  formula,
  data,
  ...,
  aggregate = TRUE,
  .stimulus = "stimulus",
  .response = "response",
  .confidence = "confidence",
  .joint_response = "joint_response",
  K = NULL,
  distribution = "normal",
  metac_absolute = TRUE,
  stanvars = NULL,
  categorical = FALSE
)

Arguments

formula

A model formula for some or all parameters of the metad brms family. To display all parameter names for a model with K confidence levels, use metad(K).

data

A tibble containing the data to fit the model.

If aggregate==TRUE, data should have one row per observation with columns stimulus, response, confidence, and any other variables in formula
If aggregate==FALSE, it should be aggregated to have one row per cell of the design matrix, with joint type 1/type 2 response counts in a matrix column (see aggregate_metad()).

...

Additional parameters passed to the brm function.

aggregate

If TRUE, automatically aggregate data by the variables included in formula using aggregate_metad(). Otherwise, data should already be aggregated.

.stimulus

The name of "stimulus" column

.response

The name of "response" column

.confidence

The name of "confidence" column

.joint_response

The name of "joint_response" column

K

The number of confidence levels. By default, this is estimated from the data.

distribution

The noise distribution to use for the signal detection model. By default, uses a normal distribution with a mean parameterized by dprime.

metac_absolute

If TRUE, fix the type 2 criterion to be equal to the type 1 criterion. Otherwise, equate the criteria relatively such that metac/metadprime = c/dprime.

stanvars

Additional stanvars to pass to the model code, for example to define an alternative distribution or a custom model prior (see brms::stanvar()).

categorical

If FALSE (default), use the multinomial likelihood over aggregated data. If TRUE, use the categorical likelihood over individual trials.

Examples

# fit a basic model on simulated data
# running few iterations so example runs quickly, use more in practice
fit_metad(N ~ 1, sim_metad(), chains = 1, iter = 500)
#> Compiling Stan program...
#> Start sampling
#> 
#> SAMPLING FOR MODEL 'anon_model' NOW (CHAIN 1).
#> Chain 1: 
#> Chain 1: Gradient evaluation took 3.4e-05 seconds
#> Chain 1: 1000 transitions using 10 leapfrog steps per transition would take 0.34 seconds.
#> Chain 1: Adjust your expectations accordingly!
#> Chain 1: 
#> Chain 1: 
#> Chain 1: Iteration:   1 / 500 [  0%]  (Warmup)
#> Chain 1: Iteration:  50 / 500 [ 10%]  (Warmup)
#> Chain 1: Iteration: 100 / 500 [ 20%]  (Warmup)
#> Chain 1: Iteration: 150 / 500 [ 30%]  (Warmup)
#> Chain 1: Iteration: 200 / 500 [ 40%]  (Warmup)
#> Chain 1: Iteration: 250 / 500 [ 50%]  (Warmup)
#> Chain 1: Iteration: 251 / 500 [ 50%]  (Sampling)
#> Chain 1: Iteration: 300 / 500 [ 60%]  (Sampling)
#> Chain 1: Iteration: 350 / 500 [ 70%]  (Sampling)
#> Chain 1: Iteration: 400 / 500 [ 80%]  (Sampling)
#> Chain 1: Iteration: 450 / 500 [ 90%]  (Sampling)
#> Chain 1: Iteration: 500 / 500 [100%]  (Sampling)
#> Chain 1: 
#> Chain 1:  Elapsed Time: 0.029 seconds (Warm-up)
#> Chain 1:                0.032 seconds (Sampling)
#> Chain 1:                0.061 seconds (Total)
#> Chain 1: 
#> Warning: Bulk Effective Samples Size (ESS) is too low, indicating posterior means and medians may be unreliable.
#> Running the chains for more iterations may help. See
#> https://mc-stan.org/misc/warnings.html#bulk-ess
#> Warning: Tail Effective Samples Size (ESS) is too low, indicating posterior variances and tail quantiles may be unreliable.
#> Running the chains for more iterations may help. See
#> https://mc-stan.org/misc/warnings.html#tail-ess
#>  Family: metad__4__normal__absolute__multinomial 
#>   Links: mu = log 
#> Formula: N ~ 1 
#>    Data: data.aggregated (Number of observations: 1) 
#>   Draws: 1 chains, each with iter = 500; warmup = 250; thin = 1;
#>          total post-warmup draws = 250
#> 
#> Regression Coefficients:
#>           Estimate Est.Error l-95% CI u-95% CI Rhat Bulk_ESS Tail_ESS
#> Intercept    -1.97      2.08    -7.37     0.52 1.00      123       96
#> 
#> Further Distributional Parameters:
#>                 Estimate Est.Error l-95% CI u-95% CI Rhat Bulk_ESS Tail_ESS
#> dprime              0.76      0.26     0.27     1.24 1.02      309      104
#> c                  -0.03      0.13    -0.26     0.22 1.02      190      153
#> metac2zero1diff     0.47      0.08     0.33     0.65 1.00      206      154
#> metac2zero2diff     0.23      0.08     0.11     0.39 1.00      327      206
#> metac2zero3diff     0.69      0.16     0.44     1.05 1.01      433      208
#> metac2one1diff      0.58      0.10     0.42     0.80 1.02      133      186
#> metac2one2diff      0.58      0.13     0.37     0.89 1.00      437      230
#> metac2one3diff      0.52      0.17     0.21     0.89 1.00      286      153
#> 
#> Draws were sampled using sampling(NUTS). For each parameter, Bulk_ESS
#> and Tail_ESS are effective sample size measures, and Rhat is the potential
#> scale reduction factor on split chains (at convergence, Rhat = 1).