--- title: "lavaan.printer" author: "Shu Fai Cheung" output: rmarkdown::html_vignette vignette: > %\VignetteIndexEntry{lavaan.printer} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- ```{r, include = FALSE} knitr::opts_chunk$set( collapse = TRUE, comment = "#>" ) ``` # Introduction This article illustrates how to use the two main functions of `lavaan.printer`: - `parameterEstimates_table_list()` - `print_parameterEstimates_table_list()` These are the packages used in this article: ```{r} library(lavaan) library(lavaan.printer) ``` # For What Scenarios? These two functions are not for end-users. They are for package developers, and are intended to be used internally by `print`-methods or similar functions for the objects in other packages which generate customized parameter tables. - `parameterEstimates_table_list()`: creates a `parameterEstimates_table_list` object which is a list of data frames, organized based on the sections for parameter estimates in the `summary()` output of `lavaan`, such as factor loadings (`Latent Variables`) and covariances (`Covariances`). The data frames can be customized in a lot of ways, such as adding columns created by user-supplied functions, or adding header sections or footer sections. - `print_parameterEstimates_table_list()`: It prints a `parameterEstimates_table_list` object, with some degree of customization. Most of the customization should be done when calling `parameterEstimates_table_list()`. The cells are formatted as strings across sections when being printed to ensure that the column widths are consistent. # Scenarios ## Create a List of Data frames In the simplest case, `parameterEstimates_table_list()` can be used to generate the usual parameter estimates results of `lavaan`, but as a list of data frames, each corresponding to a section in the output (e.g., regression coefficients, factor loadings). Arguments for to `lavaan::parameterEstimates()` can be used when calling `parameterEstimates_table_list()`: ```{r} # Adapted from the example of cfa() model_cfa <- "visual =~ x1 + x2 + x3 textual =~ x4 + x5 + x6" fit <- cfa(model_cfa, data = HolzingerSwineford1939, group = "school") est <- parameterEstimates_table_list(fit, rsquare = TRUE) ``` Because it is intended to be used inside a print function, it does not have a print method itself. Call `print_parameterEstimates_table_list()` instead: ```{r} print_parameterEstimates_table_list(est) ``` The output looks similar to the `lavaan` output, except for some minor changes in column names (e.g., `CI.Lo` and `CI.Up` instead of `ci.lower` and `ci.upper`) to shorten the width of the print, to make room for additional columns developer may want to add. This is intentional: mimicking the `lavaan` style to minimize the need for the users to learn anything new in reading the output. These options are available in `print_parameterEstimates_table_list()`: - `nd`: Control the number of digits after the decimal. Default is 3. - `by_group`: For multiple-group models, whether the tables are grouped by groups first, as in `lavaan`. Default is `TRUE`. Setting this to `FALSE` facilitates comparing groups on estimates, especially when a model has a lot of parameters. - `drop_cols`: A character vector of columns to be dropped. Any columns can be dropped. Can be used to drop columns that cannot be removed when calling `summary()` or `lavaan::parameterEstimates()`, or columns to be dropped only when being printed. - `na_str`: The string to be used for blank cells, such as the standard errors of fixed parameters. Default is `" "`. This is an example of these arguments: ```{r} print_parameterEstimates_table_list(est, nd = 2, by_group = FALSE, drop_cols = "Z", na_str = "--") ``` ## Insert a Column Computed From Another Column Suppose we would like to insert a column of symbols (e.g., `"*"` and `"**"`) into the parameter estimates table based on the `pvalue` column, to denote whether a parameter is significant, This is the function: ```{r} add_sig <- function(object, breaks = c(1, .05, .01, .001, -Inf), labels = c("***", "** ", "* ", " ")) { tmp <- object[, "pvalue", drop = TRUE] if (!is.null(tmp)) { tmp[is.na(tmp)] <- 1 tmp2 <- cut(tmp, breaks = breaks, labels = labels) i <- match("pvalue", colnames(object)) out <- data.frame(object[, 1:i], Sig = tmp2, object[, seq(i + 1, ncol(object))]) } out } ``` This can be done by the argument `est_funs`: ```{r} model_cfa <- "visual =~ x1 + x2 + x3 textual =~ x4 + x5 + x6" fit <- cfa(model_cfa, data = HolzingerSwineford1939[1:100, ]) est <- parameterEstimates_table_list(fit, est_funs = list(add_sig)) print_parameterEstimates_table_list(est) ``` Note that `est_funs` must be a list, even if only one function is supplied. ## Add a Header or Footer Section Header or footer functions can be used to include a header or footer section. The first argument will be one of the following object: - If the input object of `parameterEstimates_table_list()` is a `lavaan` object, then the function is called with the first argument being the *parameter* *estimates* table generated by `lavaan::parameterEstimates()`) with `output = "text", header = TRUE`. - If the input object of `parameterEstimates_table_list()` is a data-frame-like object, such as a modified output of `lavaan::parameterEstimates()` generated by other functions, then the function is called with this object as the first argument. Header and footer sections can then be created using attributes stored in this object. The following is a simple function to print the missing data handling method, stored in the output of `lavaan::parameterEstimates()` when printed with `output = "text", header = "TRUE"`. The attribute `section_title` is used to set the title for this section. By default, `print()` will be used to print a section. ```{r} lavaan_missing <- function(x) { out0 <- attr(x, "missing") out1 <- data.frame(Option = "Missing", Setting = out0) attr(out1, "section_title") <- "Additional Information:" out1 } ``` This is a function to add some footnotes. The output is a character vector, which should be printed by `cat()`. This can be done by setting the attribute `print_fun` to `"cat"`. If the print function is `cat()`, the section is printed with `sep = "\n"` by default. ```{r} footnotes <- function(x) { out0 <- c("- This is footnote 1.", paste("- This is footnote 2, a very very very very very", "very very very very very very very very very very", "very very long one. Wrapped by default")) attr(out0, "section_title") <- "Footnote:" attr(out0, "print_fun") <- "cat" out0 } ``` These functions can then be used in `header_funs` and `footer_funs`: ```{r} model_cfa <- "visual =~ x1 + x2 + x3" fit <- cfa(model_cfa, data = HolzingerSwineford1939) est <- parameterEstimates_table_list(fit, header_funs = list(lavaan_missing), footer_funs = list(footnotes)) print_parameterEstimates_table_list(est) ``` Like `est_funs`, the value of `header_funs` (and `footer_funs`) must be list. # Further Information There are other ways to customize the output when calling `parameterEstimates_table_list()`. For example: - Drop one or more columns. - Rename one or more columns. - Set arguments when calling functions in `est_funs`, `header_funs`, and `footer_funs`. Please refer to the help page of `parameterEstimates_table_list()` for details. # Issues If you have any suggestions and found any bugs, please feel feel to open a [GitHub issue](https://github.com/sfcheung/lavaan.printer/issues ). Thanks.