Package 'glba' reference manual

Title:	General Linear Ballistic Accumulator Models
Description:	Analyses response times and accuracies from psychological experiments with the linear ballistic accumulator (LBA) model from Brown and Heathcote (2008). The LBA model is optionally fitted with explanatory variables on the parameters such as the drift rate, the boundary and the starting point parameters. A log-link function on the linear predictors can be used to ensure that parameters remain positive when needed.
Authors:	Ingmar Visser
Maintainer:	Ingmar Visser <[email protected]>
License:	GPL
Version:	0.2.1
Built:	2025-02-16 04:30:20 UTC
Source:	https://github.com/cran/glba

Fit LBA models with explanatory variables.

Description

Fit LBA models with explanatory variables on the parameters.

Details

Package:	glba
Type:	Package
Version:	0.2
Date:	2015-02-11
License:	GPL

See ?lba for examples.

Author(s)

Ingmar Visser (with functions adapted from Brown, Heathcote and Donkin). Maintainer: Ingmar Visser <[email protected]>

References

Brown, S. D., and Heathcote, A. (2008). The simplest complete model of choice response time: linear ballistic accumulation. Cognitive psychology, 57(3), 153-178.

Examples

# To be added later
# To be added later

Example data from Brown and Heathcote (2008).

Description

Example data from Brown and Heathcote (2008); response times and accuracies for three difficulty levels.

Usage

data(bh08)data(bh08)

Format

A data frame with 3000 observations on the following 3 variables.

acc: response accuracy
rt: response times
diff: difficulty, a factor with levels easy medium diff

Details

Example data from Brown and Heathcote, 2008.

Source

Data from: http://www.newcl.org/members/chris/fitLBA.zip

Brown and Heathcote, Cognitive science, 2008

References

Brown and Heathcote, 2008

Examples

data(bh08)
data(bh08)

Core functions to compute the probability density function, cumulative distribution function, and defective distribution of the LBA (see Brown and Heathcote, 2008).

Description

For internal use only.

Author(s)

Ingmar Visser adapted these functions, to make them fully vectorized in all relevant arguments. Original functions fptpdf, fptcdf and n1PDF are provided by Brown, Heathcote and Donkin and are retrieved from: http://www.newcl.org/members/chris/fitLBA.zip

References

http://www.newcl.org/members/chris/fitLBA.zip

Implicit learning data from Visser et al (2007).

Description

Implicit learning data from Visser et al (2007); these data are from blocks 1-12 of participant 2 of Experiment 1.

Usage

data(ilpp2)data(ilpp2)

Format

A data frame with 12 blocks of 395 trials of a sequential response time task; observations on the following variables:

id: participant id
ses: session number (1-2)
blk: block number within session (1-6)
tri: trial location (1-4)
ans: answer location (1-4)
rt: response time in seconds
acc: accuracy (factor with levels 'cor'rect and 'inc'orrect
acBin: accuracy in binary format
blk2: block number continuous (1-12)
tt: trial type; factor with levels 'seq'uential and 'ran'dom

Details

Data from Visser et al (2007), Memory and Cognition.

Source

Visser et al (2007), Memory and Cognition.

References

Visser et al (2007), Memory and Cognition.

Examples

data(ilpp2)
data(ilpp2)

Utility functions for internal use.

Description

Functions for specifying, printing and altering the submodels for each of the parameters.

Author(s)

Ingmar Visser

Specify and fit lba models.

Description

Specification of lba models with explanatory variables on the parameters. Models are fitted using full information maximum likelihood.

Usage

lba(rt, response, data, weights, 
sddr = ~1, 
sp = ~1, 
bound = ~1, 
nond = ~1, 
drift = ~1, 
scaling = "sum", 
loglink = c(FALSE, FALSE, FALSE, FALSE), 
sdstart=0.1,
startpars, 
fixed = NULL,
method = "L-BFGS-B",
hessian = FALSE,
lower = -Inf,
upper = Inf,
fit=TRUE,
debug=FALSE) 

## S3 method for class 'lba'
logLik(object, ...)
## S3 method for class 'lba'
print(x, ...)
## S3 method for class 'lba'
summary(object, ...)

tablba(object)

lba(rt, response, data, weights, 
sddr = ~1, 
sp = ~1, 
bound = ~1, 
nond = ~1, 
drift = ~1, 
scaling = "sum", 
loglink = c(FALSE, FALSE, FALSE, FALSE), 
sdstart=0.1,
startpars, 
fixed = NULL,
method = "L-BFGS-B",
hessian = FALSE,
lower = -Inf,
upper = Inf,
fit=TRUE,
debug=FALSE) 

## S3 method for class 'lba'
logLik(object, ...)
## S3 method for class 'lba'
print(x, ...)
## S3 method for class 'lba'
summary(object, ...)

tablba(object)

Arguments

`rt`	The name of the response time variable in data.frame 'data'.
`response`	The name of the response time variable in data.frame 'data'.
`data`	Data.frame containing the variables.
`weights`	Optional case weights.
`sddr`	The model for the standard deviation of the drift rate, see Details.
`sp`	The model for the start point parameter, see Details.
`bound`	The model for the boundary parameter, see Details.
`nond`	The model for the non-decision time, see Details.
`drift`	The model for the drift rate parameter, see Details.
`scaling`	Options for making the model identifiable; options are "sum" or "fixedSD".
`loglink`	Wheter parameters (sddr, sp, nond, and bound) should be fitted using a log link function (to avoid boundary estimation issues).
`sdstart`	Starting value of the standard deviation of the drift rates in case argument scaling uses option "fixedSD".
`startpars`	Vector of starting values for the parameters. This is currently a required argument as no automatic starting values are available.
`fixed`	Logical; when startpars is given 'fixed' can be used to specify whether parameters should remain fixed during estimation; sometimes required for more stable estimation.
`method`	Optimization method; passed to optim.
`hessian`	Logical; indicating whether the estimated hessian at the minimum; passed to optim.
`lower`, `upper`	lower and upper boundaries for the parameters; only applicable with optimization method 'L-BFGS-B' is used.
`fit`	Logical; indicating whehter the model should be fit, ie, its parameters optimized or not. Default is TRUE.
`debug`	Logical, default is FALSE; prints out detailed information on submodels, parameters et cetera during optimization.
`object`	a (fitted) lba model.
`x`	a (fitted) lba model.
`...`	not currently in use.

Details

The 5 sub-models of the LBA model can be specified using a formula. Eg, nond=~diff, specifies a model in which the nondecision time is modeled as function of difficulty; diff may be a factor or numerical variable.

Identification of the model is attained by having the drift rates for alternatives in response sum to unity or by having a fixed standard deviation of the drift rates. These options are specified by scaling="sum" or scaling="fixedSD", respectively. In the latter case, the value of the fixed standard deviation is assumed to be the first value of startpars.

If hessian is set to TRUE, optim is used to get the Hessian at the maximum likelihood estimates of the parameters. This is used in turn to compute standard errors. The summary function pretty prints a table of parameter estimates, standard errors, z- and p-values. The summary function also prints the separate sub-model specifications and the parameter estimates. The print function prints basic information and a (named) vector of parameter estimates.

Value

The lba function returns a list with the following components:

`pars`	The values of fitted parameters.
`logl`	The optimized log likelihood
`convergence`	Convergence information from `optim`
`hessian`	Only included if `hessian` was set to TRUE
`ses`	Only included if `hessian` was set to TRUE and the hessian is non-singular
`fixed`	Vector of logical's indicating whether parameters were fixed
`model`	List of 5 sub-models of the LBA model, see Details above.
`npar`	The number of parameters of the model
`freepars`	The number of freely estimated parameters of the model
`nobs`	The number of observations, used in computing the BIC
`call`	The (matched) call to the `lba` function

Function tablba returns a data.frame with columns:

`value`	The estimated (or fixed) parameter value
`se`	The standard error of the parameter computed from the Hessian
`z`	The z-ratio of `value` and `se`
`p`	The p-value associated with `z`

Author(s)

Ingmar Visser

References

LBA models as in Brown and Heathcote, Cognitive science, 2008.

Examples

data(bh08)

# reduce the data set for faster runtimes
bh1 <- bh08[c(1:300,1001:1300,2001:2300),]

# remove extreme RTs
bh1 <- bh1[bh1$rt>.180&bh1$rt<2,]

# starting values based on the quantile parameter 
# estimates from Brown and Heathcote, 2008:
# pars <- c(.25,.3,.1,.2,.9,.75,.6)

# fit the model with starting values
pars <- c(.25,.3,.1,.2,.9,.75,.6)
m1 <- lba(rt=rt,response=acc,drift=~diff-1,data=bh1,
	startpars=pars)

m1

summary(m1)

## Not run: 
	# use random starting values instead
	set.seed(2)
	m1 <- lba(rt=rt,response=acc,drift=~diff-1,data=bh08,
	startpars=pars, hessian=TRUE)

	summary(m1)
	
	# get the parameters
	pp <- m1$pars
	# simulate some data from the model for the three conditions
	set.seed(1)
	dt1 <- rlba(1000, b=pp[3]+pp[2], A=pp[2], vs=c(pp[5],1-pp[5]), 
		s=pp[1], t0=pp[4], truncdrifts=TRUE)
	dt2 <- rlba(1000, b=pp[3]+pp[2], A=pp[2], vs=c(pp[6],1-pp[6]), 
		s=pp[1], t0=pp[4], truncdrifts=TRUE)
	dt3 <- rlba(1000, b=pp[3]+pp[2], A=pp[2], vs=c(pp[7],1-pp[7]), 
		s=pp[1], t0=pp[4], truncdrifts=TRUE)
	dt <- rbind(dt1,dt2,dt3)
	dt$diff <- gl(3,1000)
	dt$resp <- ifelse(dt$resp==2,0,1)
	
	# remove extreme RTs
	dt <- dt[dt$rt>.180&dt$rt<2,]
	
	# refit the model with the simualted data
	m1rf <- lba(rt=rt,response=resp,drift=~diff-1,data=dt,startpars=pp)
	
	data(numpp1)
	
	set.seed(9)
	m2 <- lba(rt=rt,response=acc,drift=~diff+block,data=numpp1,
	startpars=c(0.25,runif(4),0,0), scaling="fixedSD", 
		sdstart=0.25, hessian=TRUE) 
	tablba(m2) 
	
	
## End(Not run)

data(bh08)

# reduce the data set for faster runtimes
bh1 <- bh08[c(1:300,1001:1300,2001:2300),]

# remove extreme RTs
bh1 <- bh1[bh1$rt>.180&bh1$rt<2,]

# starting values based on the quantile parameter 
# estimates from Brown and Heathcote, 2008:
# pars <- c(.25,.3,.1,.2,.9,.75,.6)

# fit the model with starting values
pars <- c(.25,.3,.1,.2,.9,.75,.6)
m1 <- lba(rt=rt,response=acc,drift=~diff-1,data=bh1,
	startpars=pars)

m1

summary(m1)

## Not run: 
	# use random starting values instead
	set.seed(2)
	m1 <- lba(rt=rt,response=acc,drift=~diff-1,data=bh08,
	startpars=pars, hessian=TRUE)

	summary(m1)
	
	# get the parameters
	pp <- m1$pars
	# simulate some data from the model for the three conditions
	set.seed(1)
	dt1 <- rlba(1000, b=pp[3]+pp[2], A=pp[2], vs=c(pp[5],1-pp[5]), 
		s=pp[1], t0=pp[4], truncdrifts=TRUE)
	dt2 <- rlba(1000, b=pp[3]+pp[2], A=pp[2], vs=c(pp[6],1-pp[6]), 
		s=pp[1], t0=pp[4], truncdrifts=TRUE)
	dt3 <- rlba(1000, b=pp[3]+pp[2], A=pp[2], vs=c(pp[7],1-pp[7]), 
		s=pp[1], t0=pp[4], truncdrifts=TRUE)
	dt <- rbind(dt1,dt2,dt3)
	dt$diff <- gl(3,1000)
	dt$resp <- ifelse(dt$resp==2,0,1)
	
	# remove extreme RTs
	dt <- dt[dt$rt>.180&dt$rt<2,]
	
	# refit the model with the simualted data
	m1rf <- lba(rt=rt,response=resp,drift=~diff-1,data=dt,startpars=pp)
	
	data(numpp1)
	
	set.seed(9)
	m2 <- lba(rt=rt,response=acc,drift=~diff+block,data=numpp1,
	startpars=c(0.25,runif(4),0,0), scaling="fixedSD", 
		sdstart=0.25, hessian=TRUE) 
	tablba(m2) 
	
	
## End(Not run)

Example data from a numerosity task.

Description

Example data from a numerosity task. Participant is required to categorize a display of randomly placed dots into 'few' or 'many'.

Usage

data(numpp1)data(numpp1)

Format

A data frame with 186 observations on the following 10 variables. Extreme data are removed.

stim: file name of the stimulus
trial: trial number
acc: accuracy in binary format
rt: response time in seconds
nr: required response; factor with levels 'few' and 'many'
block: block number (1-5)
dots: number of dots in the display
diff: absolute value of 'dots'-50
df2: dichotomized version of 'diff'
id: participant id

Details

Example data from a numerosity task.

Source

Unpublished data.

References

Unpublished data.

Examples

data(numpp1)
data(numpp1)

Generate data from an LBA model.

Description

Generate data from an LBA model.

Usage

rlba(n, b, A, vs, s, t0, st0 = 0, truncdrifts = TRUE)
rlba(n, b, A, vs, s, t0, st0 = 0, truncdrifts = TRUE)

Arguments

`n`	The number of random variates required.
`b`	The boundary parameter.
`A`	The start point parameter.
`vs`	The drift rates for each of the accumulators.
`s`	The standard deviation of the drift rates.
`t0`	The non-decision time.
`st0`	Variability of the non-decision time, uniformly distributed as t0+U(0,st0).
`truncdrifts`	Logical; whether drifts that are generated should be truncated at zero. Negative RTs may result when set to FALSE.

Details

No more details.

Value

A data.frame with two variables, 'rt' and 'resp', for the response time and the response, respectively.

Author(s)

Ingmar Visser, function adapted from Brown and Heathcote.

http://www.newcl.org/publications/2008/lbasoftware.htm

References

Function adapted from Brown and Heathcote.

http://www.newcl.org/publications/2008/lbasoftware.htm

Examples

# to be added later
# to be added later

Package 'glba'

Help Index

Fit LBA models with explanatory variables.

Description

Details

Author(s)

References

Examples

Example data from Brown and Heathcote (2008).

Description

Usage

Format

Details

Source

References

Examples

Core functions to compute the probability density function, cumulative distribution function, and defective distribution of the LBA (see Brown and Heathcote, 2008).

Description

Author(s)

References

Implicit learning data from Visser et al (2007).

Description

Usage

Format

Details

Source

References

Examples

Utility functions for internal use.

Description

Author(s)

Specify and fit lba models.

Description

Usage

Arguments

Details

Value

Author(s)

References

Examples

Example data from a numerosity task.

Description

Usage

Format

Details

Source

References

Examples

Generate data from an LBA model.

Description

Usage

Arguments

Details

Value

Author(s)

References

Examples