How to use mplush5
This is a guide on how to use the mplush5 library.
What is an h5 file?
An h5/hdf5 file is a type of file that is used to store large amounts of data. The data are stored in a hierarchical data format. Mplus uses this format to save the numeric results of the model to an external file.
Why do we need these functions?
It is possible to read an h5 file directly into R. However, these files are large and difficult to navigate. Also, the structure of the h5 file changes by the modeling options used in Mplus. Because of this, it is difficult to find the desired results.
Below is an example of an h5 file.
ex3_1 <- system.file("extdata", "ex3_1.h5", package = "mplush5")
raw_h5 <- rhdf5::h5dump(ex3_1, load=TRUE)
str(raw_h5)
#> List of 8
#> $ Confidence Intervals of Model Results :List of 2
#> ..$ Results : num [1:4, 1:7] 0.863 0.535 0.399 0.788 0.888 ...
#> ..$ Statements: chr [1:4, 1:4] " "| __truncated__ " "| __truncated__ "Intercepts "| __truncated__ "Residual Variances "| __truncated__ ...
#> $ Confidence Intervals of Standardized Model Results:List of 3
#> ..$ STD Standardization :List of 2
#> .. ..$ Results : num [1:4, 1:7] 0.863 0.535 0.399 0.788 0.888 ...
#> .. ..$ Statements: chr [1:4, 1:4] " "| __truncated__ " "| __truncated__ "Intercepts "| __truncated__ "Residual Variances "| __truncated__ ...
#> ..$ STDY Standardization :List of 2
#> .. ..$ Results : num [1:4, 1:7] 0.567 0.349 0.253 0.321 0.581 ...
#> .. ..$ Statements: chr [1:4, 1:4] " "| __truncated__ " "| __truncated__ "Intercepts "| __truncated__ "Residual Variances "| __truncated__ ...
#> ..$ STDYX Standardization:List of 2
#> .. ..$ Results : num [1:4, 1:7] 0.591 0.337 0.253 0.321 0.606 ...
#> .. ..$ Statements: chr [1:4, 1:4] " "| __truncated__ " "| __truncated__ "Intercepts "| __truncated__ "Residual Variances "| __truncated__ ...
#> $ Input instructions : chr [1:17(1d)] "TITLE: "| __truncated__ "this is an example of a simple linear "| __truncated__ " regression for a continuous observed "| __truncated__ " dependent variable with two covariates "| __truncated__ ...
#> $ Model Fit Information :List of 2
#> ..$ Description: chr [1:19(1d)] "Number of Free Parameters "| __truncated__ "H0 Loglikelihood "| __truncated__ "H1 Loglikelihood "| __truncated__ "Akaike (AIC) "| __truncated__ ...
#> ..$ Value : num [1:19(1d)] 4 -694 -694 1397 1414 ...
#> $ Model Results :List of 2
#> ..$ Results : num [1:4, 1:4] 0.9695 0.649 0.511 0.9413 0.0415 ...
#> ..$ Statements: chr [1:4, 1:4] " "| __truncated__ " "| __truncated__ "Intercepts "| __truncated__ "Residual Variances "| __truncated__ ...
#> $ R-Square :List of 2
#> ..$ Results : num [1, 1:4] 0.609 0.0273 22.3164 0
#> ..$ Statements: chr [1, 1:4] "Observed Variable "| __truncated__ "Y1 "| __truncated__ " "| __truncated__ "Y1 "| __truncated__
#> $ Standardized Model Results :List of 3
#> ..$ STD Standardization :List of 2
#> .. ..$ Results : num [1:4, 1:4] 0.9695 0.649 0.511 0.9413 0.0415 ...
#> .. ..$ Statements: chr [1:4, 1:4] " "| __truncated__ " "| __truncated__ "Intercepts "| __truncated__ "Residual Variances "| __truncated__ ...
#> ..$ STDY Standardization :List of 2
#> .. ..$ Results : num [1:4, 1:4] 0.6248 0.4183 0.3293 0.391 0.0223 ...
#> .. ..$ Statements: chr [1:4, 1:4] " "| __truncated__ " "| __truncated__ "Intercepts "| __truncated__ "Residual Variances "| __truncated__ ...
#> ..$ STDYX Standardization:List of 2
#> .. ..$ Results : num [1:4, 1:4] 0.6534 0.4092 0.3293 0.391 0.0243 ...
#> .. ..$ Statements: chr [1:4, 1:4] " "| __truncated__ " "| __truncated__ "Intercepts "| __truncated__ "Residual Variances "| __truncated__ ...
#> $ Summary of Analysis :List of 4
#> ..$ Input data file(s) :List of 1
#> .. ..$ Data files: chr [1(1d)] "ex3_1_aa78f01013fe7acb644cf7c3710aa050.dat "| __truncated__
#> ..$ Number of observations : int [1(1d)] 500
#> ..$ Observed dependent variables :List of 1
#> .. ..$ Continuous: chr [1(1d)] "Y1 "| __truncated__
#> ..$ Observed independent variables:List of 1
#> .. ..$ Observed independent variables: chr [1:2(1d)] "X1 "| __truncated__ "X3 "| __truncated__Saving an h5 file
Before using any functions in this package, you need to have an h5 file available. This code shows how to use MplusAutomation to run a Mplus model. Note in the savedata option, “H5RESULTS” is used to specify the h5 file.
mod <- MplusAutomation::mplusObject(
TITLE = "this is an example of a simple linear
regression for a continuous observed
dependent variable with two covariates",
MODEL = "y1 ON x1 x3;",
OUTPUT = "standardized; cinterval;",
SAVEDATA = "H5RESULTS = ex3_1.h5;",
rdata = ex3_1_df
)
MplusAutomation::mplusModeler(mod, modelout = "ex3_1.inp", run = 1)First step
The first function to use is mplus.view.results(). This
function lists what is available in the h5 function. Mplus writes
different pieces of information to the h5 file depending on the type of
model and options specified, so not all of the functions in this package
can be used on every h5 file.
ex3_1 <- system.file("extdata", "ex3_1.h5", package = "mplush5")
mplus.view.results(ex3_1)
#>
#> Use the following functions to view the available results.
#>
#> - Input instructions
#> - mplus.print.input.instructions
#> - Summary of Analysis
#> - mplus.print.summary.analysis
#> - Model Fit Information
#> - mplus.print.model.fit.information
#> - Model Results
#> - mplus.print.model.results
#> - Confidence Intervals of Model Results
#> - mplus.print.confidence.intervals
#> - Standardized Model Results
#> - mplus.print.standardized.model.results
#> - Confidence Intervals of Standardized Model Results
#> - mplus.print.standardized.confidence.intervals
#> - R-Square
#> - mplus.print.rsquareSubsequent steps
The mplus.view.results() function above shows that for
this h5 file, the following functions can be used:
To use any of these functions just specify the path to the h5 file.
The following code shows how to use the
mplus.print.model.results() function to get the model
results.
ex3_1 <- system.file("extdata", "ex3_1.h5", package = "mplush5")
results <- mplus.print.model.results(ex3_1)
results
#> Section Statement Estimate S.E. Estimate/S.E.
#> 1 Y1 ON X1 0.9694732 0.04150770 23.35646
#> 2 Y1 ON X3 0.6490355 0.04437483 14.62621
#> 3 Intercepts Y1 0.5109621 0.04342922 11.76540
#> 4 Residual Variances Y1 0.9412942 0.05953521 15.81072
#> Two-Tailed P-Value
#> 1 0
#> 2 0
#> 3 0
#> 4 0Other approaches
The h5 file is not the only way to access results from Mplus. The
MplusAutomation package has a function readModels() that
reads and parses the Mplus output file. The following code shows how to
get the same information using readModels().
ex3_1.out <- system.file("extdata", "ex3_1.out", package = "mplush5")
ex3_1_output <- MplusAutomation::readModels(ex3_1.out)
ex3_1_output[["parameters"]][["unstandardized"]]
#> paramHeader param est se est_se pval
#> 1 Y1.ON X1 0.969 0.042 23.356 0
#> 2 Y1.ON X3 0.649 0.044 14.626 0
#> 3 Intercepts Y1 0.511 0.043 11.765 0
#> 4 Residual.Variances Y1 0.941 0.060 15.811 0