---
title: "Syntax"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Syntax}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
  %\DeclareUnicodeCharacter{2194}{$\leftrightarrow$}
  %\DeclareUnicodeCharacter{2192}{$\rightarrow$}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

The syntax is, for the most part, identical to that of **lavaan** (Rosseel, 2012). 
That being said, there are some **OpenMx** (Boker et al., 2011) specific elements.

## Loadings, Regressions, and Intercepts

The following specifies loadings of a latent variable `eta` on manifest variables `y1`-`y4`:

```
eta =~ y1 + y2 + y3
```
Regressions are specified with `~`:
```
xi  =~ x1 + x2 + x3
eta =~ y1 + y2 + y3
# predict eta with xi:
eta ~  xi
```
Add covariances with `~~`
```
xi  =~ x1 + x2 + x3
eta =~ y1 + y2 + y3
# predict eta with xi:
eta ~  xi
x1 ~~ x2
```
Intercepts are specified with `~1`
```
xi  =~ x1 + x2 + x3
eta =~ y1 + y2 + y3
# predict eta with xi:
eta ~  xi
x1 ~~ x2

eta ~ 1
```

> **Note**: In **lavaan**'s `sem`-function, the loading on the first item of each latent variable 
is constrained to one by default. Estimating this loading freely requires replacing
`xi  =~ x1 + x2 + x3` with `xi  =~ NA*x1 + x2 + x3`. In **mxsem**, a different approach
is used. When calling the `mxsem`-function set the argument `scale_loadings` to
`FALSE` to freely estimate all loadings.

## Parameter labels and constraints

Add labels to parameters as follows:
```
xi  =~ l1*x1 + l2*x2 + l3*x3
eta =~ l4*y1 + l5*y2 + l6*y3
# predict eta with xi:
eta ~  b*xi
```
Fix parameters by using numeric values instead of labels:
```
xi  =~ 1*x1 + l2*x2 + l3*x3
eta =~ 1*y1 + l5*y2 + l6*y3
# predict eta with xi:
eta ~  b*xi
```

## Bounds

Lower and upper bounds allow for constraints on parameters. For instance,
a lower bound can prevent negative variances.
```
xi  =~ 1*x1 + l2*x2 + l3*x3
eta =~ 1*y1 + l5*y2 + l6*y3
# predict eta with xi:
eta ~  b*xi
# residual variance for x1
x1 ~~ v*x1
# bound:
v > 0
```
Upper bounds are specified with v < 10. Note that the parameter label must always
come first. The following is not allowed: `0 < v` or `10 > v`.

## (Non-)linear constraints

Assume that latent construct `eta` was observed twice, where `eta1` is the first
observation and `eta2` the second. We want to define the loadings of `eta2`
on its observations as `l_1 + delta_l1`. If `delta_l1` is zero, we have measurement
invariance.

```
eta1 =~ l1*y1 + l2*y2 + l3*y3
eta2 =~ l4*y4 + l5*y5 + l6*y6
# define new delta-parameter
!delta_1; !delta_2; !delta_3
# redefine l4-l6
l4 := l1 + delta_1
l5 := l2 + delta_2
l6 := l3 + delta_3
```


Alternatively, implicit transformations can be used as follows:

```
eta1 =~ l1*y1 + l2*y2 + l3*y3
eta2 =~ {l1 + delta_1} * y4 + {l2 + delta_2} * y5 + {l3 + delta_3} * y6
```

This is inspired by the approach in **metaSEM** (Cheung, 2015).

## Definition variables

Definition variables allow for person-specific parameter constraints. Use the
`data.`-prefix to specify definition variables.
```
I =~ 1*y1 + 1*y2 + 1*y3 + 1*y4 + 1*y5
S =~ data.t_1 * y1 + data.t_2 * y2 + data.t_3 * y3 + data.t_4 * y4 + data.t_5 * y5

I ~ int*1
S ~ slp*1
```

## Model name

You can specify a model name using the following syntax:

```
# start with at least three equal signs:
=== model_name ===
I =~ 1*y1 + 1*y2 + 1*y3 + 1*y4 + 1*y5
S =~ data.t_1 * y1 + data.t_2 * y2 + data.t_3 * y3 + data.t_4 * y4 + data.t_5 * y5

I ~ int*1
S ~ slp*1
```

Note that **mxsem** will ignore **everything** above the three (or more) equal
signs! That is, the following will result in problems:

```
# the following two lines will be ignored:

I =~ 1*y1 + 1*y2 + 1*y3 + 1*y4 + 1*y5
S =~ data.t_1 * y1 + data.t_2 * y2 + data.t_3 * y3 + data.t_4 * y4 + data.t_5 * y5

# start with at least three equal signs:
=== model_name ===

I ~ int*1
S ~ slp*1
```


## Starting Values

mxsem differs from **lavaan** in the specification of starting values. Instead
of providing starting values in the model syntax, the `set_starting_values`
function is used.

## References

* Boker, S. M., Neale, M., Maes, H., Wilde, M., Spiegel, M., Brick, T., Spies, J., Estabrook, R., Kenny, S., Bates, T., Mehta, P., & Fox, J. (2011).
OpenMx: An Open Source Extended Structural Equation Modeling Framework. Psychometrika, 76(2), 306–317. https://doi.org/10.1007/s11336-010-9200-6
* Rosseel, Y. (2012). lavaan: An R package for structural equation modeling. Journal of Statistical Software, 48(2), 1–36. https://doi.org/10.18637/jss.v048.i02