ssMousetrack-package: Bayesian State-Space Modeling of Mouse-Tracking Experiments...
In ssMousetrack: Bayesian State-Space Modeling of Mouse-Tracking Experiments via Stan
ssMousetrack-package R Documentation
Bayesian State-Space Modeling of Mouse-Tracking Experiments Via Stan
Description
The ssMousetrack package allows analysing mouse-tracking experiments via Bayesian state-space modeling.
The package estimates the model using Markov Chain Monte Carlo, variational approximations to the posterior distribution, or optimization,
as implemented in the rstan package. The user can use the customary R modeling syntax to define equations of the model and Stan syntax to
specify priors over the model parameters.
The sections below provide an overview of the state-space model implemented by the ssMousetrack package.
Details
(i) Mouse-tracking data
The raw data of a mouse-tracking experiment for I individuals and J stimuli consist of a collection of arrays
(x,y)_{ij} = (x_0,...,x_{N_{ij}}; y_0,...,y_{N_{ij}}) which contain ordered N_{ij} x 1 sequences of x-y Cartesian coordinates as mapped to the
computer-mouse pointer. The x-y coordinates are pre-processed according to the following steps:
-
Realigning: the arrays (x,y)_{ij} are re-aligned on a common sampling scale, so that N indicates the cumulative amount of progressive time from 0% to N = 100%, with N being the same over i=1,...,I and j=1,...,J
-
Normalization: the aligned arrays (x,y)_{ij} are normalized so that (x_0,y_0)_{ij}=(0,0) and (x_N,y_N)_{ij}=(1,1) for each i=1,...,I and j=1,...,J
-
Translation: the normalized arrays (x,y)_{ij} are translated into the quadrant [-1,1]x[0,1]
-
atan2 projection: the final arrays (x,y)_{ij} are projected onto a lower-subspace via the atan2 function by getting the ordered collection
of radians (y)_{ij} = (y_0,...,y_N) in the subset of reals (0,\pi]^N, for each i=1,...,I and j=1,...,J.
The final I x J x N array of data Y contains the mouse-tracking trajectories expressed in terms of angles. These trajectories lie on the arc defined by
the union of two disjoint sets, namely the sets \{y_0,...,y_N: y_n \geq \pi/2 \} (target's hemispace) and \{y_0,...,y_N: y_n < (3\pi)/4 \} (distractor's hemispace), with \pi/2 and (3\pi)/4 being the location points for target and distractor, respectively.
Note that, the current version of ssMousetrack package requires the number of stimuli J to be the same over the subjects i=1,...,I.
The pre-processed mouse-tracking trajectories are analysed using the state-space modeling described below.
(ii) Model representation
The array Y contains the observed data expressed in angles. The measurement equation of the model is:
y_{ij}^{(n)} \sim vonMises\big(\mu_{ij}^{(n)},\kappa_{ij}^{(n)}\big)
where \mu_{ij}^{(n)} and \kappa_{ij}^{(n)} are the location and the concentration parameters for the vonMises probability law.
The moving mean on the arc \mu_{ij}^{(n)} is defined as:
\mu_{ij}^{(n)} := G(\beta,x_{i}^{(n)})
with \beta being a J x 1 array of real parameters representing the contribution of the j-th stimulus on the observed trajectory y_{ij} = (y^{(0)},...,y^{(N)})
whereas G is a non-linear function mapping reals to the subset (0,\pi] of the form: (i) \big[ (1 + \exp(\beta - x_{i}^{(n)})) \big]\pi^{-1} (logistic), (ii) \big[ \exp(-\beta \exp(-x_{i}^{(n)})) \big]\pi (gompertz).
In the G equation, x_i^{(n)} is a real random quantity obeying to the law:
x_i^{(n)} \sim Normal\big( x_i^{(n-1)},\sigma^2_i \big)
which represents a random walk process with time-fixed variance \sigma^2_i. The terms x_{i} = (x_{i}^{(0)},...,x_{i}^{(N)}) are the individual latent dynamics
unaffected by the stimuli (i.e., how individual differ in executing the task) whereas \beta contains the experimental effects regardless to the individual dynamic (i.e., how experimental variables act on the individual dynamics to produce the observed responses).
The terms \beta = (\beta_1,...,\beta_J) are defined according to the following linear combination:
\beta_j := \sum_{k=1}^K z_{jk}\gamma_k
where z_{jk} is an element of the J x K dummy matrix Z representing main and high-order effects of the experimental design.
The terms \kappa_{ij} = (\kappa_{ij}^{(0)},...,\kappa_{ij}^{(N)}) are computed as follows:
\kappa_{ij}^{(n)} := \exp^{o}\big(\delta_{ij}^{(n)}\big)
where \delta^{(n)}_{ij} = |y_{ij}^{(n)}-(3\pi)/4| (if y_{ij}^{(n)} < \pi/2) or \delta^{(n)}_{ij} = |y_{ij}^{(n)}-\pi/4| (if y_{ij}^{(n)} \geq \pi/2). The function \exp^o is the exponential function scaled in the natural range of the parameters \kappa_{ij} (positive real numbers).
(iii) Bayesian formulation
The state-space model in the ssMousetrack package requires estimating the array of latent trajectories X and the K x 1 parameters \gamma.
Let \Theta representing both the unknown quantities, the posterior density after factorization is:
f(\Theta|Y) \propto f(\gamma) \prod_{i=1}^I \prod_{j=1}^J f(\gamma|y_{ij}) \prod_{i=1}^I \prod_{j=1}^J f(x_i|y_{ij})
Sampling from f(\Theta|Y) is solved via marginal MCMC where the term f(x_i|y_{ij}) is approximated by means of Kalman filtering/smoothing. The marginal Likelihood of the model used for the rejection criterion of the MCMC sampler is approximated with the Normal distribution using the Kalman filter theory.
References
Calcagnì, A., Lombardi, L., & D'Alessandro, M. (2018). A state space approach to dynamic modeling of mouse-tracking data. Frontiers in Psychology: Quantitative Psychology and Measurement, 10, 2716
Calcagnì, A., Lombardi, L., & D'Alessandro, M. (2018). A state space approach to dynamic modeling of mouse-tracking data. Under review
Calcagnì, A., Lombardi, L., & D'Alessandro (2018, August). Probabilistic modeling of mouse-tracking data: A statespace approach. Paper presented at the 2018 European Mathematical Psychology Group Meeting (EMPG 2018), Genova, Italy
Calcagnì, A., Lombardi, L., D'Alessandro, M., & Sulpizio S. (2018, March). A subject oriented state-space approach to model mouse-tracking data. Paper presented at the 60th Conference of Experimental Psychologists (TeaP 2018), Marburg, Germany
Freeman, J. B. (2018). Doing psychological science by hand. Current Directions in Psychological Science, In press, 1-9
Särkkä, S. (2013). Bayesian Filtering and Smoothing. Cambridge University Press
Durbin, J., & Koopman, S. J. (2012). Time series analysis by state space methods (Vol. 38). Oxford University Press
Andrieu, C., Doucet, A., & Holenstein, R. (2010). Particle markov chain monte carlo methods. Journal of the Royal Statistical Society: Series B (Statistical Methodology), 72(3), 269s-342
Gelman, A., Carlin, J. B., Stern, H. S., & Rubin, D. B. (2004). Bayesian Data Analysis (Second edition). Chapman & Hall/CRC.
See Also
https://mc-stan.org/ for more information on the Stan C++ language used by ssMousetrack package
Jokkala, J. (2016). Github repository: kalman-stan-randomwalk, https://github.com/juhokokkala/kalman-stan-randomwalk
ssMousetrack documentation built on April 5, 2023, 5:11 p.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
| ssMousetrack-package | R Documentation |
Bayesian State-Space Modeling of Mouse-Tracking Experiments Via Stan
Description
The ssMousetrack package allows analysing mouse-tracking experiments via Bayesian state-space modeling. The package estimates the model using Markov Chain Monte Carlo, variational approximations to the posterior distribution, or optimization, as implemented in the rstan package. The user can use the customary R modeling syntax to define equations of the model and Stan syntax to specify priors over the model parameters.
The sections below provide an overview of the state-space model implemented by the ssMousetrack package.
Details
(i) Mouse-tracking data
The raw data of a mouse-tracking experiment for I individuals and J stimuli consist of a collection of arrays
(x,y)_{ij} = (x_0,...,x_{N_{ij}}; y_0,...,y_{N_{ij}}) which contain ordered N_{ij} x 1 sequences of x-y Cartesian coordinates as mapped to the
computer-mouse pointer. The x-y coordinates are pre-processed according to the following steps:
-
Realigning: the arrays
(x,y)_{ij}are re-aligned on a common sampling scale, so that N indicates the cumulative amount of progressive time from 0% to N = 100%, with N being the same overi=1,...,Iandj=1,...,J -
Normalization: the aligned arrays
(x,y)_{ij}are normalized so that(x_0,y_0)_{ij}=(0,0)and(x_N,y_N)_{ij}=(1,1)for eachi=1,...,Iandj=1,...,J -
Translation: the normalized arrays
(x,y)_{ij}are translated into the quadrant[-1,1]x[0,1] -
atan2 projection: the final arrays
(x,y)_{ij}are projected onto a lower-subspace via the atan2 function by getting the ordered collection of radians(y)_{ij} = (y_0,...,y_N)in the subset of reals(0,\pi]^N, for eachi=1,...,Iandj=1,...,J.
The final I x J x N array of data Y contains the mouse-tracking trajectories expressed in terms of angles. These trajectories lie on the arc defined by
the union of two disjoint sets, namely the sets \{y_0,...,y_N: y_n \geq \pi/2 \} (target's hemispace) and \{y_0,...,y_N: y_n < (3\pi)/4 \} (distractor's hemispace), with \pi/2 and (3\pi)/4 being the location points for target and distractor, respectively.
Note that, the current version of ssMousetrack package requires the number of stimuli J to be the same over the subjects i=1,...,I.
The pre-processed mouse-tracking trajectories are analysed using the state-space modeling described below.
(ii) Model representation
The array Y contains the observed data expressed in angles. The measurement equation of the model is:
y_{ij}^{(n)} \sim vonMises\big(\mu_{ij}^{(n)},\kappa_{ij}^{(n)}\big)
where \mu_{ij}^{(n)} and \kappa_{ij}^{(n)} are the location and the concentration parameters for the vonMises probability law.
The moving mean on the arc \mu_{ij}^{(n)} is defined as:
\mu_{ij}^{(n)} := G(\beta,x_{i}^{(n)})
with \beta being a J x 1 array of real parameters representing the contribution of the j-th stimulus on the observed trajectory y_{ij} = (y^{(0)},...,y^{(N)})
whereas G is a non-linear function mapping reals to the subset (0,\pi] of the form: (i) \big[ (1 + \exp(\beta - x_{i}^{(n)})) \big]\pi^{-1} (logistic), (ii) \big[ \exp(-\beta \exp(-x_{i}^{(n)})) \big]\pi (gompertz).
In the G equation, x_i^{(n)} is a real random quantity obeying to the law:
x_i^{(n)} \sim Normal\big( x_i^{(n-1)},\sigma^2_i \big)
which represents a random walk process with time-fixed variance \sigma^2_i. The terms x_{i} = (x_{i}^{(0)},...,x_{i}^{(N)}) are the individual latent dynamics
unaffected by the stimuli (i.e., how individual differ in executing the task) whereas \beta contains the experimental effects regardless to the individual dynamic (i.e., how experimental variables act on the individual dynamics to produce the observed responses).
The terms \beta = (\beta_1,...,\beta_J) are defined according to the following linear combination:
\beta_j := \sum_{k=1}^K z_{jk}\gamma_k
where z_{jk} is an element of the J x K dummy matrix Z representing main and high-order effects of the experimental design.
The terms \kappa_{ij} = (\kappa_{ij}^{(0)},...,\kappa_{ij}^{(N)}) are computed as follows:
\kappa_{ij}^{(n)} := \exp^{o}\big(\delta_{ij}^{(n)}\big)
where \delta^{(n)}_{ij} = |y_{ij}^{(n)}-(3\pi)/4| (if y_{ij}^{(n)} < \pi/2) or \delta^{(n)}_{ij} = |y_{ij}^{(n)}-\pi/4| (if y_{ij}^{(n)} \geq \pi/2). The function \exp^o is the exponential function scaled in the natural range of the parameters \kappa_{ij} (positive real numbers).
(iii) Bayesian formulation
The state-space model in the ssMousetrack package requires estimating the array of latent trajectories X and the K x 1 parameters \gamma.
Let \Theta representing both the unknown quantities, the posterior density after factorization is:
f(\Theta|Y) \propto f(\gamma) \prod_{i=1}^I \prod_{j=1}^J f(\gamma|y_{ij}) \prod_{i=1}^I \prod_{j=1}^J f(x_i|y_{ij})
Sampling from f(\Theta|Y) is solved via marginal MCMC where the term f(x_i|y_{ij}) is approximated by means of Kalman filtering/smoothing. The marginal Likelihood of the model used for the rejection criterion of the MCMC sampler is approximated with the Normal distribution using the Kalman filter theory.
References
Calcagnì, A., Lombardi, L., & D'Alessandro, M. (2018). A state space approach to dynamic modeling of mouse-tracking data. Frontiers in Psychology: Quantitative Psychology and Measurement, 10, 2716
Calcagnì, A., Lombardi, L., & D'Alessandro, M. (2018). A state space approach to dynamic modeling of mouse-tracking data. Under review
Calcagnì, A., Lombardi, L., & D'Alessandro (2018, August). Probabilistic modeling of mouse-tracking data: A statespace approach. Paper presented at the 2018 European Mathematical Psychology Group Meeting (EMPG 2018), Genova, Italy
Calcagnì, A., Lombardi, L., D'Alessandro, M., & Sulpizio S. (2018, March). A subject oriented state-space approach to model mouse-tracking data. Paper presented at the 60th Conference of Experimental Psychologists (TeaP 2018), Marburg, Germany
Freeman, J. B. (2018). Doing psychological science by hand. Current Directions in Psychological Science, In press, 1-9
Särkkä, S. (2013). Bayesian Filtering and Smoothing. Cambridge University Press
Durbin, J., & Koopman, S. J. (2012). Time series analysis by state space methods (Vol. 38). Oxford University Press
Andrieu, C., Doucet, A., & Holenstein, R. (2010). Particle markov chain monte carlo methods. Journal of the Royal Statistical Society: Series B (Statistical Methodology), 72(3), 269s-342
Gelman, A., Carlin, J. B., Stern, H. S., & Rubin, D. B. (2004). Bayesian Data Analysis (Second edition). Chapman & Hall/CRC.
See Also
https://mc-stan.org/ for more information on the Stan C++ language used by ssMousetrack package
Jokkala, J. (2016). Github repository: kalman-stan-randomwalk, https://github.com/juhokokkala/kalman-stan-randomwalk
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.