run_ssm {ssMousetrack}

State-space modeling of mouse-tracking trajectories via Stan

Description

State-space modeling of mouse-tracking trajectories via Stan

Usage

run_ssm(
  N,
  I,
  J,
  Y = NULL,
  D = NULL,
  Z = NULL,
  sigmax = 1,
  lambda = 1,
  y_T = pi/4,
  y_D = (3 * pi)/4,
  priors = "default",
  gfunction = c("logistic", "gompertz"),
  kappa_bnds = c(5, 300),
  nchains = 1,
  niter = 2000,
  nwarmup = 500,
  ncores = "AUTO",
  stan_object = FALSE,
  ...
)

Arguments

N

(integer) length of the Y-trajectories

I

(integer) number of individuals

J

(integer) number of trials

Y

(matrix) N x JI matrix of observed trajectories

D

(matrix) N x JI matrix of delta values for the observed trajectories

Z

(matrix) matrix of contrasts associated to the experimental design (see generate_design)

sigmax

(numeric) fixed value for the model parameter sigmax

lambda

(numeric) fixed value for the model parameter lambda

y_T

(numeric) position in angles of the target

y_D

(numeric) position in angles of the distractor

priors

(list) a list of arguments specifying priors for each parameter involved in the model (see check_prior). If priors="default" then pre-defined tpriors will be used.

gfunction

(character) type of link function between latent states and observed data: 'logistic', 'gompertz' (default = 'logistic').

kappa_bnds

(array) array containing the lower and upper bounds for the kappa parameter (default = c(5,300))

nchains

(integer) number of chains for the MCMC algorithm

niter

(integer) number of iterations for each chain

nwarmup

(integer) number of warmup/burnin iterations per chain

ncores

(integer) number of cores to use when executing the chains in parallel. The default option ncores="AUTO" will automatically determine the number of cores via the parallel package

stan_object

(boolean) if stan_object=TRUE, the object of S4 class stanfit representing the fitted results will be saved as stan_object.rda

...

other stan arguments (e.g., 'init', 'algorithm', 'sample_file'. See sampling)

Details

The function drawns samples from the posterior distribution of the model parameters. Note that, the current version of ssMousetrack package requires the number of stimuli J to be the same over the subjects i=1,...,I.

Value

a datalist containing the posterior samples for the model parameters along with the main Stan output

Examples

## Not run: 
## Fit a state-space model using simulated data 
# Generate mouse-tracking data for an univariate experimental design with K = 3 categorical levels, 
# J = 12 trials, I = 5 subjects
X1 <- generate_data(I=5,J=12,K=3,Z.formula="~Z1")
iid <- 23 # keep just one dataset from the simulated set of datasets
# Run the state-space model on the chosen dataset
X1_fit <- run_ssm(N = X1$N,I = X1$I,J = X1$J,Y = X1$data$Y[iid,,],D = X1$data$D[iid,,],
Z = X1$data$Z)

## Fit a state-space model using the experimental dataset language
# The dataset is ready to be used and it does not need to be pre-processed (preprocess=FALSE). 
# In this case, the function prepare_data just computes the observed radians from 
# the x-y trajectories
X2 <- prepare_data(X = language, preprocess = FALSE, Z.formula = "~condition")
# Run the state-space model on the chosen dataset
X2_fit <- run_ssm(N = X2$N,I = X2$I,J = X2$J,Y = X2$Y,D = X2$D,Z = X2$Z,
niter=5000,nchains=2)

## Fit a state-space model using the experimental dataset congruency
# The dataset needs to be pre-processed (preprocess=TRUE)
X3 <- prepare_data(X = congruency, preprocess = TRUE, 
Z.formula = "~congruency+plausibility") # additive design
# Define priors of the model parameters 
KK <- dim(X3$Z)[2] # number of model parameters implied by the design matrix Z
priors_list <- list("lognormal(1,0.5)","pareto(3,5.25)","normal(0,2.5)")
# note that length(priors_list) = KK 
# Run the state-space model on the chosen dataset
X3_fit <- run_ssm(N = X3$N,I = X3$I,J = X3$J,Y = X3$Y,D = X3$D,Z = X3$Z,
niter=10000,nwarmup=3500,priors=priors_list,nchains=4)

## End(Not run)