dynr-package {dynr}R Documentation

Dynamic Models with Regime-Switching

Description

Intensive longitudinal data have become increasingly prevalent in various scientific disciplines. Many such data sets are noisy, multivariate, and multi-subject in nature. The change functions may also be continuous, or continuous but interspersed with periods of discontinuities (i.e., showing regime switches). The package 'dynr' (Dynamic Modeling in R) is an R package that implements a set of computationally efficient algorithms for handling a broad class of linear and nonlinear discrete- and continuous-time models with regime-switching properties under the constraint of linear Gaussian measurement functions. The discrete-time models can generally take on the form of a state- space or difference equation model. The continuous-time models are generally expressed as a set of ordinary or stochastic differential equations. All estimation and computations are performed in C, but users are provided with the option to specify the model of interest via a set of simple and easy-to-learn model specification functions in R. Model fitting can be performed using single- subject time series data or multiple-subject longitudinal data. Ou, Hunter, & Chow (2019) <doi:10.32614/RJ-2019-012> provided a detailed introduction to the interface and more information on the algorithms.

Details

The DESCRIPTION file:

Package: dynr
Date: 2021-11-16
Title: Dynamic Models with Regime-Switching
Authors@R: c(person("Lu", "Ou", role="aut"), person(c("Michael", "D."), "Hunter", role=c("aut", "cre"), email="mike.dynr@gmail.com", comment=c(ORCID = "0000-0002-3651-6709")), person("Sy-Miin", "Chow", role="aut", comment=c(ORCID = "0000-0003-1938-027X")), person("Linying", "Ji", role="aut", email=""), person("Meng", "Chen", role="aut", email=""), person("Hui-Ju", "Hung", role="aut", email=""), person("Jungmin", "Lee", role="aut", email="leejapply@gmail.com"), person("Yanling", "Li", role="aut", email=""), person("Jonathan", "Park", role="aut", email=""), person("Massachusetts Institute of Technology", role="cph"), person("S. G.", "Johnson", role="cph"), person("Benoit", "Scherrer", role="cph"), person("Dieter", "Kraft", role="cph"))
Maintainer: Michael D. Hunter <mike.dynr@gmail.com>
URL: https://dynrr.github.io/, https://github.com/mhunter1/dynr
Contact: <dynr@googlegroups.com>
Depends: R (>= 3.0.0), ggplot2
Imports: MASS, Matrix, numDeriv, xtable, latex2exp, grid, reshape2, plyr, mice, magrittr, Rdpack, methods, fda, car, stringi, tibble, deSolve
Suggests: testthat, roxygen2 (>= 3.1), knitr, rmarkdown
VignetteBuilder: knitr
Description: Intensive longitudinal data have become increasingly prevalent in various scientific disciplines. Many such data sets are noisy, multivariate, and multi-subject in nature. The change functions may also be continuous, or continuous but interspersed with periods of discontinuities (i.e., showing regime switches). The package 'dynr' (Dynamic Modeling in R) is an R package that implements a set of computationally efficient algorithms for handling a broad class of linear and nonlinear discrete- and continuous-time models with regime-switching properties under the constraint of linear Gaussian measurement functions. The discrete-time models can generally take on the form of a state- space or difference equation model. The continuous-time models are generally expressed as a set of ordinary or stochastic differential equations. All estimation and computations are performed in C, but users are provided with the option to specify the model of interest via a set of simple and easy-to-learn model specification functions in R. Model fitting can be performed using single- subject time series data or multiple-subject longitudinal data. Ou, Hunter, & Chow (2019) <doi:10.32614/RJ-2019-012> provided a detailed introduction to the interface and more information on the algorithms.
SystemRequirements: GNU make
NeedsCompilation: yes
License: GPL-3
LazyLoad: yes
LazyData: yes
Collate: 'dynrData.R' 'dynrRecipe.R' 'dynrModelInternal.R' 'dynrModel.R' 'dynrCook.R' 'dynrPlot.R' 'dynrFuncAddress.R' 'dynrMi.R' 'dynrTaste.R' 'dynrVersion.R' 'dataDoc.R' 'dynrGetDerivs.R' 'dynrPredict.R'
RdMacros: Rdpack
Biarch: true
Version: 0.1.16-27
RoxygenNote: 5.0.1
Author: Lu Ou [aut], Michael D. Hunter [aut, cre] (<https://orcid.org/0000-0002-3651-6709>), Sy-Miin Chow [aut] (<https://orcid.org/0000-0003-1938-027X>), Linying Ji [aut], Meng Chen [aut], Hui-Ju Hung [aut], Jungmin Lee [aut], Yanling Li [aut], Jonathan Park [aut], Massachusetts Institute of Technology [cph], S. G. Johnson [cph], Benoit Scherrer [cph], Dieter Kraft [cph]

Index of help topics:

EMG                     Single-subject time series of facial
                        electromyography data
EMGsim                  Simulated single-subject time series to capture
                        features of facial electromyography data
LinearOsc               Simulated time series data for a deterministic
                        linear damped oscillator model
LogisticSetPointSDE     Simulated time series data for a stochastic
                        linear damped oscillator model with logistic
                        time-varying setpoints
NonlinearDFAsim         Simulated multi-subject time series based on a
                        dynamic factor analysis model with nonlinear
                        relations at the latent level
Oscillator              Simulated time series data of a damped linear
                        oscillator
Outliers                Simulated time series data for detecting
                        outliers.
PFAsim                  Simulated time series data of a multisubject
                        process factor analysis
PPsim                   Simulated time series data for multiple
                        eco-systems based on a predator-and-prey model
RSPPsim                 Simulated time series data for multiple
                        eco-systems based on a regime-switching
                        predator-and-prey model
TrueInit_Y14            Simulated multilevel multi-subject time series
                        of a Van der Pol Oscillator
VARsim                  Simulated time series data for multiple
                        imputation in dynamic modeling.
autoplot.dynrTaste      The ggplot of the outliers estimates.
coef.dynrModel          Extract fitted parameters from a dynrCook
                        Object
confint.dynrCook        Confidence Intervals for Model Parameters
diag,character-method   Create a diagonal matrix from a character
                        vector
dynr-package            Dynamic Models with Regime-Switching
dynr.config             Check that dynr in configured properly
dynr.cook               Cook a dynr model to estimate its free
                        parameters
dynr.data               Create a list of data for parameter estimation
                        (cooking dynr) using 'dynr.cook'
dynr.flowField          A Function to plot the flow or velocity field
                        for a one or two dimensional autonomous ODE
                        system from the phaseR package written by
                        Michael J. Grayling.
dynr.ggplot             The ggplot of the smoothed state estimates and
                        the most likely regimes
dynr.ldl                LDL Decomposition for Matrices
dynr.mi                 Multiple Imputation of dynrModel objects
dynr.model              Create a dynrModel object for parameter
                        estimation (cooking dynr) using 'dynr.cook'
dynr.plotFreq           Plot of the estimated frequencies of the
                        regimes across all individuals and time points
                        based on their smoothed regime probabilities
dynr.taste              Detect outliers in state space models.
dynr.taste2             Re-fit state-space model using the estimated
                        outliers.
dynr.trajectory         A Function to perform numerical integration of
                        the chosen ODE system, for a user-specified set
                        of initial conditions. Plots the resulting
                        solution(s) in the phase plane. This function
                        from the phaseR package written by Michael J.
                        Grayling.
dynr.version            Current Version String
dynrCook-class          The dynrCook Class
dynrDynamics-class      The dynrDynamics Class
dynrInitial-class       The dynrInitial Class
dynrMeasurement-class   The dynrMeasurement Class
dynrModel-class         The dynrModel Class
dynrNoise-class         The dynrNoise Class
dynrRecipe-class        The dynrRecipe Class
dynrRegimes-class       The dynrRegimes Class
dynrTrans-class         The dynrTrans Class
getdx                   A wrapper function to call functions in the fda
                        package to obtain smoothed estimated
                        derivatives at a specified order
internalModelPrep       Do internal model preparation for dynr
logLik.dynrCook         Extract the log likelihood from a dynrCook
                        Object
names,dynrCook-method   Extract the free parameter names of a dynrCook
                        object
names,dynrModel-method
                        Extract the free parameter names of a dynrModel
                        object
nobs.dynrCook           Extract the number of observations for a
                        dynrCook object
nobs.dynrModel          Extract the number of observations for a
                        dynrModel object
oscData                 Another simulated multilevel multi-subject time
                        series of a damped oscillator model
plot.dynrCook           Plot method for dynrCook objects
plotFormula             Plot the formula from a model
plotGCV                 A function to evaluate the generalized
                        cross-validation (GCV) values associated with
                        derivative estimates via Bsplines at a range of
                        specified smoothing parameter (lambda) values
predict.dynrModel       'predict' method for 'dynrModel' objects
prep.formulaDynamics    Recipe function for specifying dynamic
                        functions using formulas
prep.initial            Recipe function for preparing the initial
                        conditions for the model.
prep.loadings           Recipe function to quickly create factor
                        loadings
prep.matrixDynamics     Recipe function for creating Linear Dynamcis
                        using matrices
prep.measurement        Prepare the measurement recipe
prep.noise              Recipe function for specifying the measurement
                        error and process noise covariance structures
prep.regimes            Recipe function for creating regime switching
                        (Markov transition) functions
prep.tfun               Create a dynrTrans object to handle the
                        transformations and inverse transformations of
                        model paramters
printex                 The printex Method
summary.dynrCook        Get the summary of a dynrCook object
theta_plot              A function to plot simple slopes and region of
                        significance.
vcov.dynrCook           Extract the Variance-Covariance Matrix of a
                        dynrCook object
vdpData                 Another simulated multilevel multi-subject time
                        series of a Van der Pol Oscillator

Because the dynr package compiles C code in response to user input, more setup is required for the dynr package than for many others. We acknowledge that this additional setup can be bothersome, but we believe the ease of use for the rest of the package and the wide variety of models it is possible to fit with it will compensate for this initial burden. Hopefully you will agree!

See the installation vignette referenced in the Examples section below for installation instructions.

The naming convention for dynr exploits the pronunciation of the package name, dynr, pronounced the same as “dinner”. That is, the names of functions and methods are specifically designed to relate to things done surrounding dinner, such as gathering ingredients (e.g., the data), preparing recipes, cooking, and serving the finished product. The general procedure for using the dynr package can be summarized in five steps as below.

  1. Data are prepared using with the dynr.data() function.

  2. Recipes are prepared. To each part of a model there is a corresponding prep.*() recipe function. Examples of such prep.*() functions include: prep.measurement(), prep.matrixDynamics(), prep.formulaDynamics(), prep.initial(), prep.noise(), and prep.regimes().

  3. The function dynr.model() mixes the data and recipes together into a model object of class dynrModel.

  4. The model is cooked with dynr.cook().

  5. Results from model fitting and related estimation are served using functions such as summary(), plot(), dynr.ggplot() (or its alias autoplot()), plotFormula(), and printex().

Note

State-space modeling, dynamic model, differential equation, regime switching, nonlinear

Author(s)

NA

Maintainer: Michael D. Hunter <mike.dynr@gmail.com>

References

Chow S, Grimm KJ, Guillaume F, Dolan CV, McArdle JJ (2013). “Regime-switching bivariate dual change score model.” Multivariate Behavioral Research, 48(4), 463-502. doi: 10.1080/00273171.2013.787870.

Chow S, Zhang G (2013). “Nonlinear Regime-Switching State-Space (RSSS) Models.” Psychometrika: Application Reviews and Case Studies, 78(4), 740-768. doi: 10.1007/s11336-013-9330-8.

Ou L, Hunter MD, Chow S (2019). “What's for dynr: A package for linear and nonlinear dynamic modeling in R.” The R Journal, 11(1), 1-20.

Yang M, Chow S (2010). “Using state-space model with regime switching to represent the dynamics of Facial electromyography (EMG) data.” Psychometrika: Application and Case Studies, 74(4), 744-771. doi: 10.1007/s11336-010-9176-2.

Chow S, Ou L, Ciptadi A, Prince E, You D, Hunter MD, Rehg JM, Rozga A, Messinger DS (2018). “Representing sudden shifts in intensive dyadic interaction data using differential equation models with regime switching.” Psychometrika, 83, 476-510. doi: 10.1007/s11336-018-9605-1.

See Also

For other annotated tutorials using the dynr package see https://quantdev.ssri.psu.edu/resources/what%E2%80%99s-dynr-package-linear-and-nonlinear-dynamic-modeling-r

Examples

# For installation instructions see the package vignette below
## Not run: 
vignette(package='dynr', 'InstallationForUsers')

## End(Not run)
# This should open a pdf/html file to guide you through proper
#  installation and configuration.

#For illustrations of the functions in dynr, check out some of the demo examples in:
## Not run: 
demo(package='dynr')

## End(Not run)

#For example, to run the demo 'LinearSDE' type
# the following without the comment character (#) in front of it.
## Not run: 
demo('LinearSDE', package='dynr')

## End(Not run)

[Package dynr version 0.1.16-27 Index]