blimp.update: Blimp Input Updating

Description

This function updates specific input command sections of a misty.object of type blimp to create an updated Blimp input file, run the updated input file by using the blimp.run() function, and print the updated Blimp output file by using the blimp.print() function.

Usage

blimp.update(x, update, file = "Blimp_Input_Update.imp", comment = FALSE,
             replace.inp = TRUE, blimp.run = TRUE, posterior = FALSE,
             folder = "Posterior_",
             format = c("csv", "csv2", "xlsx", "rds", "RData"),
             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: misty.object object of type blimp
update: a character vector containing the updated Blimp input command sections
args: specification of function arguments
write: updated write command sections
result: list with result sections (result)

Arguments

x: misty.object object of type blimp.
update: a character vector containing the updated input command sections.
file: a character string indicating the name of the updated Blimp input file with or without the file extension .imp, e.g., "Blimp_Input_Update.imp" or "Blimp_Input_Update.imp".
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(), "xlsx" for write.xlsx(), "rds" for saveRDS(), and "RData" 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 headers (e.g., "ALGORITHMIC OPTIONS SPECIFIED:"), and for the header Outcome Variable: and Missing predictor: including variables names.
style: a character vector with two elements indicating the style used for headers (e.g., "ALGORITHMIC OPTIONS SPECIFIED:"), and for the header Outcome Variable: and Missing predictor: including variables names, i.e., regular, for regular text, bold for bold text, italic, for italic text, and underline for underline text.
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().
data: a matrix or data frame from which the variables names for the section VARIABLES are extracted when using the ... specification in the VARIABLES section.

Author

Takuya Yanagida

Details

Bimp Input Sections

The function is used to update following Blimp input sections:

DATA
VARIABLES
CLUSTERID
ORDINAL
NOMINAL
COUNT
WEIGHT
MISSING
LATENT
RANDOMEFFECT
TRANSFORM
BYGROUP
FIXED
CENTER
MODEL
SIMPLE
PARAMETERS
TEST
FCS
SIMUALTE
SEED
BURN
ITERATIONS
CHAINS
NIMPS
THIN
OPTIONS
OUTPUT
SAVE

The ---; Specification

The ---; specification is used to remove entire sections (e.g., CENTER: ---;) from the Blimp input. Note that ---; including the semicolon ; needs to be specified, i.e., --- without the semicolon ; will result in an error message.

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 1a: Update BURN and ITERATIONS section

# Specify Blimp input
input <- '
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
mod0 <- blimp(input, file = "Ex4.3.imp", clear = FALSE)

# Update sections
update1 <- '
BURN: 5000;
ITERATIONS: 20000;
'

# Run updated Blimp input
mod1 <- blimp.update(mod0, update1, file = "Ex4.3_update1.imp")

#----------------------------------------------------------------------------
# Example 1b: Remove CENTER section

# Remove section
update2 <- '
CENTER: ---;
'

# Run updated Blimp input
mod3 <- blimp.update(mod1, update2, file = "Ex4.3_update2.imp")
}

Run the code above in your browser using DataLab