blimp: Create, Run, and Print Blimp Models

Description

This wrapper function creates a Blimp input file, runs the input file by using the blimp.run() function, and prints the Blimp output file by using the blimp.print() function.

Usage

blimp(x, file = "Blimp_Input.imp", data = NULL, comment = FALSE, replace.inp = TRUE,
      blimp.run = TRUE, posterior = FALSE, folder = "Posterior_",
      format = c("csv", "csv2", "excel", "rds", "workspace"), clear = TRUE,
      replace.out = c("always", "never", "modified"), Blimp = detect.blimp(),
      result = c("all", "default", "algo.options", "data.info", "model.info",
                 "warn.mess", "out.model", "gen.param"),
      exclude = NULL, color = c("none", "blue", "violet"),
      style = c("bold", "regular"), not.result = TRUE, write = NULL,
      append = TRUE, check = TRUE, output = TRUE)

Value

Returns an object of class misty.object, which is a list with following entries:

call: function call
type: type of analysis
x: a character vector containing the Blimp input text
args: specification of function arguments
write: write command sections
result: list with result sections (result)

Arguments

x: a character string containing the Blimp input text.
file: a character string indicating the name of the Blimp input file with or without the file extension .imp, e.g., "Blimp_Input.imp" or "Blimp_Input.imp".
data: a matrix or data frame from which the variables names for the section VARIABLES are extracted.
comment: logical: if FALSE (default), comments (i.e., text after the # symbol) are removed from the input text specified in the argument x.
replace.inp: logical: if TRUE (default), an existing input file will be replaced.
blimp.run: logical: if TRUE, the input file specified in the argument file containing the input text specified in the argument x is run using the blimp.run() function.
posterior: logical: if TRUE, the posterior distribution including burn-in and post-burn-in phase for all parameters are saved in long format in a file called posterior.* in the folder specified in the argument folder and .imp file name in the format specified in the argument format.
folder: a character string indicating the prefix of the folder for saving the posterior distributions. The default setting is folder = "Posterior_".
format: a character vector indicating the file format(s) for saving the posterior distributions, i.e., "csv" (default) for write.csv(), "csv2" for write.csv2(), "excel" for write.xlsx(), "rds" for saveRDS(), and "workspace" for write().
clear: logical: if TRUE (default), the console is cleared after estimating each model.
replace.out: a character string for specifying three settings: "always" (default), which runs all models, regardless of whether an output file for the model exists, "never", which does not run any model that has an existing output file, and "modified", which only runs a model if the modified date for the input file is more recent than the output file modified date.
Blimp: a character string for specifying the name or path of the Blimp executable to be used for running models. This covers situations where Blimp is not in the system's path, or where one wants to test different versions of the Blimp program. Note that there is no need to specify this argument for most users since it has intelligent defaults.
result: a character vector specifying Blimp result sections included in the output (see 'Details' in the blimp.print function).
exclude: a character vector specifying Blimp input command or result sections excluded from the output (see 'Details' in the blimp.print function).
color: a character vector with two elements indicating the colors used for the main headers (e.g., "ALGORITHMIC OPTIONS SPECIFIED:"), and for the headers Outcome Variable: and Missing predictor:, Latent Variable:, and Covariance Matrix:.
style: a character vector with two elements indicating the style used for headers (e.g., "ALGORITHMIC OPTIONS SPECIFIED:"), and for the main headers (e.g., "ALGORITHMIC OPTIONS SPECIFIED:"), and for the headers Outcome Variable: and Missing predictor:, Complete variable:, Latent Variable:, and Covariance Matrix:.
not.result: logical: if TRUE (default), character vector indicating the result sections not requested are shown on the console.
write: a character string naming a file for writing the output into a text file with file extension ".txt" (e.g., "Output.txt").
append: logical: if TRUE (default), output will be appended to an existing text file with extension .txt specified in write, if FALSE existing text file will be overwritten.
check: logical: if TRUE (default), argument specification is checked.
output: logical: if TRUE (default), output is shown on the console by using the function blimp.print().

Author

Takuya Yanagida

Details

VARIABLES Section

The VARIABLES section used to assign names to the variables in the data set can be specified by using the data argument:

Write Blimp Data File: In the first step, the Blimp data file is written by using the write.mplus() function, e.g. write.mplus(data1, file = "data1.dat").
Specify Blimp Input: In the second step, the Blimp input is specified as a character string. The VARIABLES option is left out from the Blimp input text, e.g., input <- 'DATA: data1.dat;\nMODEL: y ~ x1@b1 x2@b2 d2;'.
Run Blimp Input: In the third step, the Blimp input is run by using the blimp() function. The argument data needs to be specified given that the VARIABLES section was left out from the Blimp input text in the previous step, e.g., blimp(input, file = "Ex4.3.imp", data = data1).

Note that unlike Mplus, Blimp allows to specify a CSV data file with variable names in the first row. Hence, it is recommended to export the data from R using the write.csv() function to specify the data file in the DATA section of the Blimp input file without specifying the VARIABLES section.

References

Keller, B. T., & Enders, C. K. (2023). Blimp user’s guide (Version 3). Retrieved from www.appliedmissingdata.com/blimp

Examples

Run this code

if (FALSE) {
#----------------------------------------------------------------------------
# Example 1: Write data, specify input without VARIABLES section, and run input

# Write Data File
# Note that row.names = FALSE needs to be specified
write.csv(data1, file = "data1.csv", row.names = FALSE)

# Specify Blimp input
input1 <- '
DATA: data1.csv;
ORDINAL: d;
MISSING: 999;
FIXED: d;
CENTER: x1 x2;
MODEL: y ~ x1 x2 d;
SEED: 90291;
BURN: 1000;
ITERATIONS: 10000;
'

# Run Blimp input
blimp(input1, file = "Ex4.3.imp")

#----------------------------------------------------------------------------
# Example 2: Write data, specify input with VARIABLES section, and run input

# Write Data File
write.mplus(data1, file = "data1.dat", input = FALSE)

# Specify Blimp input
input2 <- '
DATA: data1.dat;
VARIABLES: id v1 v2 v3 y x1 d x2 v4;
ORDINAL: d;
MISSING: 999;
FIXED: d;
CENTER: x1 x2;
MODEL: y ~ x1 x2 d;
SEED: 90291;
BURN: 1000;
ITERATIONS: 10000;
'

# Run Blimp input
blimp(input2, file = "Ex4.3.imp")

#----------------------------------------------------------------------------
# Example 3: Alternative specification using the data argument

# Write Data File
write.mplus(data1, file = "data1.dat", input = FALSE)

# Specify Blimp input
input3 <- '
DATA: data1.dat;
ORDINAL: d;
MISSING: 999;
FIXED: d;
CENTER: x1 x2;
MODEL: y ~ x1 x2 d;
SEED: 90291;
BURN: 1000;
ITERATIONS: 10000;
'

# Run Blimp input
blimp(input3, file = "Ex4.3.imp", data = data1)
}

Run the code above in your browser using DataLab