Overview – psychonetrics

Table of Contents

The main psychonetrics workflow is to first create a model (e.g., using lvm()), which will be unevaluated at first. The model can be edited if needed (e.g., fix additional parameters), and subsequently evaluated using the runmodel function. Afterwards, the model can be inspected for fit, parameters, modification indices, etc., and adjusted and rerun if required.

Note: psychonetrics is heavily inspired (but independent) by the lavaan package, and aims to obtain the same numeric results as lavaan.

Model families

There are several model families in psychonetrics. Currently, all implemented families make use of the Gaussian distribution, and are therefore models for continuous data (binary data models such as Ising models are expected in a future version). In each of these families, different models can be obtained by modeling variance-covariance structures directly or through a Gaussian graphical model (GGM), precision matrix, or Cholesky decomposition.

Variance-covariance structure models

The varcov family is the family of models that only model a variance-covariance matrix. Its main model function is varcov(). The type argument controls how the variance-covariance matrix is modeled:

type = "cov" will model the variance-covariance matrix directly.
type = "chol" will model the variance-covariance matrix as a Cholesky decomposition.
type = "prec" will model the variance-covariance matrix as a precision matrix.
type = "ggm" will model the variance-covariance matrix as a Gaussian graphical model.

The following model matrices are used:

mu: The means vector
sigma: The variance-covariance matrix (only when type = "cov")
lowertri: The Cholesky matrix (only when type = "Chol")
kappa: The precision matrix (only when type = "prec")
omega: The partial correlation matrix (only when type = "ggm")
delta: The GGM scaling matrix (only when type = "cov")

Finally, there are some wrapper functions:

cholesky() sets type = "chol"
precision() sets type = "prec"
ggm() sets type = "ggm"

Latent variable models

The lvm family is the family of models for general latent variable models. By default, it utilizes the structural equation modeling framework (SEM), and allows also for latent network models and residual network models. Its main model function is lvm(). The latent argument controls how the latent (residual/exogenous) variance-covariance matrix is modeled, and the residual argument controls how the residual variance-covariance matrix is modeled. These can be set to as "cov", "chol", "prec", or "ggm" as explained above.

The following model matrices are used:

tau: The intercept vector
tau_eta: The intercept vector of latent variables
lambda: The factor loadings matrix
beta: The structural relations matrix
sigma_zeta, lowertri_zeta, kappa_zeta, omega_zeta , and delta_zeta for the options of the latent variance-covariance structure (depending on latent)
sigma_epsilon, lowertri_epsilon, kappa_epsilon, omega_epsilon , and delta_epsilon for the options of the residual variance-covariance structure (depending on residual)

Finally, there are some wrapper functions:

lnm() sets latent = "ggm"
rnm() sets residual = "ggm"
lrnm() sets latent = "ggm" and residual = "ggm"
latentgrowth() for simpler specification of latent growth models
bifactor() for simpler specification of bifactor models

Lag-1 vector auto-regression models

The var1 family is the family of models for vector auto-regression (VAR) models for single subject time-series. The contemporaneous argument controls how the contemporaneous (residual) variance-covariance matrix is modeled, which can be set to to "cov", "chol", "prec", or "ggm" (graphical VAR) as explained above.

The following model matrices are used:

mu: The means vector
beta: The temporal coefficients
sigma_zeta, lowertri_zeta, kappa_zeta, omega_zeta , and delta_zeta for the options of the latent variance-covariance structure (depending on contemporaneous)

This family uses several arguments as used before by graphicalVAR and mlVAR:

beepvar: Use this if you have numbered beeps and did not include missing beeps in your data. E.g, if you have beeps 1, 2 and 4, you don’t want to model lag-1 temporal relations between 2 and 4. Note that this can lead to severe missingness if not used correctly.
dayvar: Use this if you have days and do not want to include night effects in your data. Note that this can lead to severe missingness if not used correctly, if you only have one observation per day this will make all your data missing!
idvar: This can be used to automatically within-person center and pool all data of participants as a single subject. This can be used to estimate a fixed-effects structure only.

There is only one wrapper function, ggm(), which sets contemporaneous = "ggm".lnm() sets latent = "ggm"

Dynamical latent variable models (panel data)

The dlvm1 family stands for lag-1 dynamical latent variable model, and is a family of models for panel data with at least three waves of measurement. It allows for modeling a factor model that takes into account separation of within- and between-subject variance structures. There are four arguments that control the type, within_latent to control the within-person latent variance-covariance structure, between_latent to control the between-person latent variance-covariance structure, within_residual to control the within-person residual structure, and between_residual to control the between-person residual structure. these can be set to to "cov", "chol", "prec", or "ggm" (graphical VAR) as explained above. The vars argument has to be used to set the design using a matrix: rows indicate variables, columns indicate waves of data, and the elements indicate the names of variables in the data corresponding to a variable at a certain wave (wide format). An NA can be used to specify a variable that was missing at a certain wave.

The following model matrices are used:

tau: The intercept vector
mu_eta: The means vector of latent variables
lambda: The factor loadings matrix
beta: The temporal relations matrix (note, not structural relations as in lvm)
sigma_zeta_within, lowertri_zeta_within, kappa_zeta_within, omega_zeta_within , and delta_zeta_within for the options of the within-subject latent variance-covariance structure (depending on within_latent)
sigma_epsilon_within, lowertri_epsilon_within, kappa_epsilon_within, omega_epsilon_within , and delta_epsilon_within for the options of the within-subject residual variance-covariance structure (depending on within_residual)
sigma_zeta_between, lowertri_zeta_between, kappa_zeta_between, omega_zeta_between , and delta_zeta_between for the options of the between-subject latent variance-covariance structure (depending on between_latent)

sigma_epsilon_between, lowertri_epsilon_between, kappa_epsilon_between, omega_epsilon_between , and delta_epsilon_between for the options of the between-subject residual variance-covariance structure (depending on between_residual)

There are three wrapper functions:

panelgvar() sets within_latnet = "ggm", between_latent = "ggm", and forces the factor loadings matrix to be an identity matrix and the residual structures to be empty. This can be used to model an observed variables graphical VAR.
panelvar() forces the factor loadings matrix to be an identity matrix and the residual structures to be empty. This can be used to model an observed variables VAR.
panel_lvgvar() sets within_latnet = "ggm", between_latent = "ggm".

Dynamical latent variable models (time-series data)

The tsdlvm1 family stands for the lag-1 dynamical latent variable model for time-series data, and combines the var1 framework with the lvm framework (although structural contemporaneous relations are not yet supported). The contemporaneous argument controls how the latent (residual/innovation) contemporaneous structure is modeled, and the residual argument controls how the residual variance-covariance matrix is modeled. These can be set to as "cov", "chol", "prec", or "ggm" as explained above. The family furthermore uses the same arguments as var1 to handle time-series data (dayvar, beepvar, and idvar).

The following model matrices are used:

tau: The intercept vector
tau_mu: The means vector of latent variables
lambda: The factor loadings matrix
beta: The temporal relations matrix
sigma_zeta, lowertri_zeta, kappa_zeta, omega_zeta , and delta_zeta for the options of the latent contemporaneous variance-covariance structure (depending on contemporaneous)
sigma_epsilon, lowertri_epsilon, kappa_epsilon, omega_epsilon , and delta_epsilon for the options of the residual variance-covariance structure (depending on residual)

There is only one wrapper function, ts_lvgvar, which sets contemporaneous = "ggm".

Estimators

Several estimators are now implemented, which can be set in the model functions using the estimator argument:

"ML": Maximum likelihood estimation of complete data (missing is handled by listwise deletion by default)
"FIML": Full-information maximum likelihood estimation
"ULS": Unweighted least-squares estimation
"WLS": Weighted least squares estimation, using the inverse of the asymptotic covariance matrix as input. Requires raw data and no missings.
"DWLS": Diagonally weighted least squares, same as WLS, but only uses the diagonal of the weights matrix.

Utility functions

The following functions can be used to evaluate or change a model:

runmodel: Runs the model
stepup: Step-up model search along modification indices
prune: Prune non-significant effects and re-estimate (step-down search)
fixpar: Fix a parameter to some value
freepar: Allow a parameter to be freely estimated
groupequal: Set a parameter equal across groups
groupfree: Set a parameter free to estimate across groups
parequal: Set equality constrains
generate: Generate data from the estimated model
bootstrap: Bootstrap the data in a model

Inspection functions

These functions allow for further inspection of the model:

print: General print method
fit: Print a list of fit measures
MIs: Print a list of modification indices
parameters: Print a list of parameter estimates
compare: Compare multiple psychonetrics models
getmatrix: Extract a model matrix