improved semtree control documentation

Author: brandmaier

.Rbuildignore

@@ -19,4 +19,5 @@ cran-comments.md
 ^\.github$
 ^\.httr-oauth$
 error.log
-vignettes/vignette-cache
+vignettes/vignette-cache
+inst/extdata/cache.rds

R/scoreSplit.R

@@ -36,7 +36,7 @@ ScoreSplit <- function(model = NULL, mydata = NULL, control = NULL,
   # label scores from lavaan models
   # removes duplicate parameter names
   if (control$sem.prog == "lavaan") {
-    unique_par_names <- unique(names(lavaan:::coef(model)))
+    unique_par_names <- unique(names(lavaan::coef(model)))
     colnames(Scores) <- unique_par_names
   }
 

R/semtree.control.R

@@ -18,49 +18,51 @@
 #' 
 #' 
 #' @aliases semtree.control print.semtree.control semtree_control
-#' @param method Default: 'naive'. One out of
-#' \code{c("score","fair","naive")} for either an unbiased two-step
-#' selection algorithm,  a naive take-the-best, or a
-#' score-based testing scheme.
-#' @param min.N Default: 10. Minimum sample size per a node, used to determine
-#' whether to continue splitting a tree or establish a terminal node.
-#' @param max.depth Default: NA. Maximum levels per a branch. Parameter for
+#' @param method Default: 'naive'. One of
+#' \code{c("score","fair","naive")} for a score-based testing
+#' scheme, an unbiased multi-step selection algorithm, or a naive
+#' take-the-best strategy.
+#' @param min.N Integer. Default: `NULL` heuristically selects this number based on the number of parameters in the model. Minimum sample size per
+#' node used to determine whether splitting can continue. It is recommended to set `min.N` explicitly.
+#' @param max.depth Integer. Default: NA. Maximum levels per a branch. Parameter for
 #' limiting tree growth.
-#' @param alpha Default: 0.05. Significance level for splitting at a given
+#' @param alpha Numeric. Default: 0.05. Significance level for splitting at a given
 #' node.
-#' @param alpha.invariance Default: NA. Significance level for invariance
+#' @param Numeric. alpha.invariance Default: NA. Significance level for invariance
 #' tests. If NA, the value of alpha is used.
 #' @param exclude.heywood Default: TRUE. Reports whether there is an
 #' identification problem in the covariance structure of an SEM tested.
-#' @param progress.bar Default: NA. Option to disable the progress bar for tree
-#' growth.
-#' @param verbose Default: FALSE. Option to turn on or off \emph{all} model
+#' @param progress.bar Boolean. Default: TRUE. Option to enable or disable the progress
+#' bar for tree growth.
+#' @param verbose Boolean. Default: FALSE. Option to turn on or off \emph{all} model
 #' messages during tree growth.
-#' @param bonferroni Default: FALSE. Correct for multiple tests with Bonferroni
+#' @param bonferroni Boolean. Default: FALSE. Correct for multiple tests with Bonferroni
 #' type correction. p-values are adjusted for the number of variables tested.
-#' @param seed Default: NA. Set a random number seed for repeating random fold
-#' generation in tree analysis.
+#' @param seed Default: `NA`. Set a random-number seed to make randomized parts
+#' of tree analysis reproducible (for example, in fair splitting or subsampling
+#' procedures).
 #' @param custom.stopping.rule Default: NA. Otherwise, this can be a boolean
 #' function with a custom stopping rule for tree growing.
 #' @param exclude.code Default: NA. NPSOL error code for exclusion from model
 #' fit evaluations when finding best split. Default: Models with errors during
 #' fitting are retained.
 #' @param mtry Default: NA. Number of sample columns to use in SEMforest
 #' analysis.
-#' @param report.level Default: 0. Values up to 99 can be used to increase the
-#' number of onscreen reports for semtree analysis.
-#' @param use.all Treatment of missing variables. By default, missing values
+#' @param report.level Integer. Default: 0. Values up to 99 increase console reporting
+#' detail during tree growth and can help diagnose fitting or split-selection
+#' issues.
+#' @param use.all Boolean. Treatment of missing variables. By default, missing values
 #' stay in a decision node. If TRUE, cases are distributed according to a
 #' maximum likelihood principle to the child nodes.
 #' @param linear If TRUE (default), the structural equation model is assumed to
 #' not contain any nonlinear parameter constraints and scores are computed
 #' analytically, resulting in a shorter runtime. Only relevant for models fitted
 #' with OpenMx.
-#' @param min.bucket Minimum bucket size. This is the minimum size any node
+#' @param min.bucket Integer. Minimum bucket size. This is the minimum size any node
 #' must have, such that a given split is considered valid. Minimum bucket size
 #' is a lower bound to the sample size in the terminal nodes of a tree.
 #' @param missing Missing value treatment. Default is ignore
-#' @param use.maxlr Use MaxLR statistic for split point selection (as proposed by Arnold et al., 2021). This corrects the bias in the LR statistics incurred by testing multiple split points within one variable.
+#' @param use.maxlr Boolean. Use MaxLR statistic for split point selection (as proposed by Arnold et al., 2021). This corrects the bias in the LR statistics incurred by testing multiple split points within one variable.
 #' @param strucchange.from Strucchange argument. See their package
 #' documentation.
 #' @param strucchange.to Strucchange argument. See their package documentation.
@@ -70,14 +72,17 @@
 #' provided to \code{\link{semtree}}.
 #' @param ctsem_sd If FALSE (default) no standard errors of CT model parameters
 #' are computed. Requesting standard errors increases runtime. 
-#' @param loglik  Character. Algorithm to compute log likelihood. The 'default' algorithm 
-#' depends on the chosen SEM package. It is 'mvn' for lavaan and 'model' for all
-#' other packages. 'model'refers to a model-based computation. 
-#' This is preferable because it is more general. As an alternative, 'mvn' computes 
-#' the log likelihood based on the
+#' @param loglik  Character.Character. Algorithm to compute log likelihood. `"default"`
+#' depends on the chosen SEM package: `"mvn"` for lavaan and `"model"` for
+#' all other packages. `"model"` refers to model-based computation and is more
+#' general. `"mvn"` computes likelihood from the multivariate normal density
+#' using model-implied means and covariance matrices.
 #' multivariate normal density and the model-implied mean and covariance matrix.
 #' @param check.convergence Boolean. Should convergence be checked when growing a tree. Default: TRUE
-#' @param chunk.random.samples Integer. Default 0 means that
+#' @param chunk.random.samples Integer. Controlling split-point subsampling for
+#' `method = "naive"`. `0` (default) evaluates all eligible split points.
+#' Values `> 0` evaluate random chunks of split points, which can speed up tree
+#' growth on very large datasets at the cost of a less exhaustive search.
 #' @return A control object containing a list of the above parameters.
 #' @author Andreas M. Brandmaier, John J. Prindle, Manuel Arnold
 #' @seealso \code{\link{semtree}}

README.Rmd

@@ -54,6 +54,22 @@ Package vignettes (shipped with the package) contain documentation on how to use
 browseVignettes("semtree")
 ```
 
+## 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:

README.md

@@ -55,6 +55,35 @@ package:
 
     browseVignettes("semtree")
 
+## 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:

tests/testthat/logfile.R

@@ -0,0 +1,19 @@
+n <- 500
+set.seed(233453)
+x = rnorm(n)
+var_ordered <- ordered( sample(c(1,2,3,4), 
+                               size=n, prob=rep(.25,4), 
+                               replace = TRUE))
+var_ordered_named <- ordered( sample(c(1,2,3,4), 
+                                     size=n, prob=rep(.25,4),
+                                     replace = TRUE),
+                              labels=c("one","two","three","four"))
+x <- x * ifelse( (var_ordered_named=="one"), .5, 10) 
+df <- data.frame(x, var_ordered_named)
+model = "x ~~ x"
+fitted_model <- lavaan::lavaan(model, df)
+tree = semtree(fitted_model, df, control=semtree_control())
+
+forest = semforest(fitted_model, df, control=semforest_control(logfile=FALSE))
+forest = semforest(fitted_model, df, control=semforest_control(logfile=TRUE))
+forest = semforest(fitted_model, df, control=semforest_control(logfile=))