-
Notifications
You must be signed in to change notification settings - Fork 13
Expand file tree
/
Copy pathREADME.Rmd
More file actions
139 lines (96 loc) · 6.74 KB
/
Copy pathREADME.Rmd
File metadata and controls
139 lines (96 loc) · 6.74 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
---
title: "Read Me"
output: md_document
---
semtree
======
```{r echo=FALSE}
knitr::opts_chunk$set(
comment = "#>",
collapse = TRUE
)
knitr::opts_chunk$set(fig.path = "README_files/")
```
<!-- badges: start -->
[](https://doi.org/10.5281/zenodo.1116294)
[](https://cran.r-project.org/package=semtree)
[](https://github.com/r-hub/cranlogs.app)
[](https://github.com/brandmaier/semtree/actions/workflows/R-CMD-check.yaml)
<!-- badges: end -->
[](https://www.gnu.org/licenses/gpl-3.0)
## What is this?
An R package for estimating Structural Equation Model (SEM) Trees and Forests. They are a fusion of SEM and decision trees, or SEM and random forests respectively. While SEM is a confirmatory modeling technique, SEM trees and forests allow to explore whether there are predictors that provide further information about an initial, theory-based model. Potential use cases are the search for potential predictors that explain individual differences, finding omitted variables in a model, or exploring measurement invariance over a large set of predictors. A recent overview is in our latest book chapter in the SEM handbook (Brandmaier & Jacobucci, 2023).
## Install
Install the latest stable version from CRAN:
```{r eval=FALSE}
install.packages("semtree")
```
To install the latest semtree package directly from GitHub, copy the following line into R:
```{r, eval=FALSE}
library(devtools)
devtools::install_github("brandmaier/semtree")
# even better: install with package vignette (extra documentation)
devtools::install_github("brandmaier/semtree",force=TRUE, build_opts = c())
```
## Usage
Package documentation and use-cases with runnable R code can be found on our github pages: [https://brandmaier.github.io/semtree/](https://brandmaier.github.io/semtree/).
Package vignettes (shipped with the package) contain documentation on how to use the package. Simply type this in R once you have loaded the package:
```{r eval=FALSE}
browseVignettes("semtree")
```
## Example
First, we load the `birthwt` data frame from the `MASS` package, which contains risk
factors associated with low infant birth weight. We extract the variables
presence of uterine irritability (ui), history of hypertension (ht), smoke status during pregnancy (smoke) and birth weight (btw):
```{r eval=TRUE, echo=TRUE}
library(semtree)
bw <- with(MASS::birthwt, {
ui <- factor(ui, labels=c("no","yes"))
ht <- factor(ht, labels=c("no","yes"))
smoke <- factor(smoke, labels=c("no","yes"))
data.frame( bwt, uterine_irritability=ui, hypertension=ht, smoke, num_premature_labours=ptl, physician_visits=ftv )
})
```
Next, we set up a simple univariate `model` that estimates mean and variance
of birth weight
```{r eval=TRUE, echo=TRUE}
model <- lavaan::lavaan("bwt~~bwt; bwt~1")
```
Last, we estimate a SEM tree with a maximum depth of two, a significance
criterion of 1% and splits based on score-based tests, and plot the resulting
tree:
```{r eval=FALSE, echo=TRUE}
ctrl <- semtree_control(method="score", max.depth = 2, alpha = 0.01)
tree <- semtree(model = model, data = bw, control = ctrl)
plot(tree)
```
```{r birthwt, eval=TRUE, echo=FALSE}
ctrl <- semtree_control(method="score", max.depth = 2, alpha = 0.01)
tree <- semtree(model = model, data = bw, control = ctrl)
plot(tree)
```
## Robustness checklist for end users
To make analyses with `semtree` more robust and reproducible, we recommend the following:
1. **Set a seed in `semtree_control(seed = ...)`** before tree growth so randomized split procedures are reproducible.
2. **Set explicit stopping rules** (`min.N`, optionally `min.bucket`, and `max.depth`) instead of relying on defaults.
3. **Choose split method intentionally** (`naive`, `fair`, or `score`) and report the choice in manuscripts.
4. **Use conservative split testing where appropriate** with `bonferroni = TRUE` when many predictors are screened.
5. **Inspect convergence behavior** by keeping `check.convergence = TRUE` and increasing `report.level` for diagnostics.
6. **Handle missing split variables explicitly** (`missing`, `use.all`) and document your choice.
7. **Pick and report likelihood computation** (`loglik = "model"` vs `"mvn"`) especially when comparing engines.
8. **Use pruning for interpretation** to avoid over-reading deep, unstable branches (`prune(tree, max.depth = ...)`).
9. **Validate findings with forests** (`semforest`) to check whether important predictors recur across trees.
10. **Archive session metadata** (at the very least document `sessionInfo()`, package versions, and control settings) alongside analysis outputs, or use packages such as `reproducibleRchunks` or `repro` to improve reproducibility chances.
## References
Theory and method:
- Brandmaier, A. M., & Jacobucci, R. C. (2023). Machine-learning approaches to structural equation modeling. In R. H. Hoyle (Ed.), Handbook of structural equation modeling (2nd rev. ed., pp. 722–739). Guilford Press.
- Arnold, M., Voelkle, M.C., and Brandmaier, A.M. (2021). Score-guided structural equation model trees. _Frontiers in psychology_, 11, 564403.
- Brandmaier, A. M., Driver, C., & Voelkle, M. C. (2019). Recursive partitioning in continuous time analysis. In K. van Montfort, J. Oud, & M. C. Voelkle (Eds.), Continuous time modeling in the behavioral and related sciences. New York: Springer.
- Brandmaier, A. M., Prindle, J. J., McArdle, J. J., & Lindenberger, U. (2016). Theory-guided exploration with structural equation model forests. _Psychological Methods_, 21, 566-582. \doi{doi:10.1037/met0000090}
- Brandmaier, A. M., von Oertzen, T., McArdle, J. J., & Lindenberger, U. (2014). Exploratory data mining with structural equation model trees. In J. J. McArdle & G. Ritschard (Eds.), Contemporary issues in exploratory data mining in the behavioral sciences (pp. 96-127). New York: Routledge.
- Brandmaier, A. M., von Oertzen, T., McArdle, J. J., & Lindenberger, U. (2013). Structural equation model trees. _Psychological Methods_, 18, 71-86. \doi{doi:10.1037/a0030001}
Applied examples (there are many more):
Brandmaier, A. M., Ram, N., Wagner, G. G., & Gerstorf, D. (2017). Terminal decline in well-being: The role of multi-indicator constellations of physical health and psychosocial correlates. Developmental Psychology.