Learn R Programming

misty (version 0.6.7)

mplus.plot: Plot Mplus GH5 File

Description

This function uses the h5file function in the hdf5r package to read a Mplus GH5 file that is requested by the command PLOT: TYPE IS PLOT2 in Mplus to display trace plots, posterior distribution plots, autocorrelation plots, posterior predictive check plots based on the "bayesian_data" section, and the loop plot based on the "loop_data" section of the Mplus GH5 file. By default, the function displays trace plots if the "bayesian_data" section is available in the Mplus GH5 File. Otherwise, the function plots the loop plot if the "loop_data" section is available in the Mplus GH5 file.

Usage

mplus.plot(x, plot = c("none", "trace", "post", "auto", "ppc", "loop"),
           param = c("all", "on", "by", "with", "inter", "var", "r2", "new"),
           std = c("all", "none", "stdyx", "stdy", "std"), burnin = TRUE,
           point = c("all", "none", "m", "med", "map"),
           ci = c("none", "eti", "hdi"), chain = 1, conf.level = 0.95,
           hist = TRUE, density = TRUE, area = TRUE, alpha = 0.4,
           fill = "gray85", nrow = NULL, ncol = NULL,
           scales = c("fixed", "free", "free_x", "free_y"),
           xlab = NULL, ylab = NULL, xlim = NULL, ylim = NULL,
           xbreaks = ggplot2::waiver(), ybreaks = ggplot2::waiver(),
           xexpand = ggplot2::waiver(), yexpand = ggplot2::waiver(),
           palette = "Set 2", binwidth = NULL, bins = NULL,
           density.col = "#0072B2", shape = 21,
           point.col = c("#CC79A7", "#D55E00", "#009E73"),
           linewidth = 0.6, linetype = "dashed", line.col = "black",
           bar.col = "black", bar.width = 0.8, plot.margin = NULL,
           legend.title.size = 10, legend.text.size = 10, legend.box.margin = NULL,
           saveplot = c("all", "none", "trace", "post", "auto", "ppc", "loop"),
           file = "Mplus_Plot.pdf",
           file.plot = c("_TRACE", "_POST", "_AUTO", "_PPC", "_LOOP"),
           width = NA, height = NA, units = c("in", "cm", "mm", "px"),
           dpi = 600, check = TRUE)

Value

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

call

function call

type

type of analysis

x

Mplus GH5 file

args

specification of function arguments

data

list with posterior distribution of each parameter estimate in wide and long format (post), autocorrelation for each parameter estimate in wide and long format (auto), data for the posterior predictive check (ppc), and data for the loop plot (loop)

plot

list with the trace plots (trace, posterior distribution plots (post), autocorrelation plots (auto), posterior predictive check plots (ppc), and loop plot (loop)

Arguments

x

a character string indicating the name of the Mplus GH5 file (HDF5 format) with or without the file extension .gh5, e.g., "Mplus_Plot.gh5" or "Mplus_Plot". Alternatively, a misty.object of type mplus can be specified, i.e., result object of the mplus.plot() function.

plot

a character string indicating the type of plot to display, i.e., "none" for not displaying any plot, "trace" (default) for displaying trace plots, post for displaying posterior distribution plots, "auto" for displaying autocorrelation plots, "ppc" for displaying posterior predictive check plots, and "loop" for displaying the loop plot. The default setting is "trace" if the "bayesian_data" section is available in the Mplus GH5 file. Otherwise, the default setting switches to "loop".

param

character vector indicating which parameters to print for the trace plots, posterior distribution plots, and autocorrelation plots, i.e., "all" for all parameters, "on" (default), for regression slopes, "by" for factor loadings, "with" for covariances, "inter" for intercepts and thresholds, "var" for (residual) variances, "r2" for r-square, and "new" for parameters not in the analysis model specified in the NEW option. The default setting is "on" if regression slopes are available. Otherwise, the default setting switches to "by" and to "with" if factor loadings are not available.

std

a character vector indicating the standardized parameters to print for the trace plots, posterior distribution plots, and autocorrelation plots, i.e., "all" for all standardized parameters, "none" (default) for not printing any standardized parameters, "stdyx" for StdYX standardized parameters, "stdy" for StdY standardized parameters, and "std" for StdX standardized parameters.

burnin

logical: if FALSE, the first half of each chain is discarded as being part of the burnin phase when displaying trace plots. The default setting for plot = "trace" is TRUE. Note that the first half of each chain is always discarded when displaying posterior distribution plots (plot = "post") regardless of the setting of the argument burnin.

point

a character vector indicating the point estimate(s) to be displayed in the posterior distribution plots, i.e., "all" for all point estimates, "none" for not displaying any point estimates, "m" for the posterior mean estimate, "med" (default) for the posterior median estimate, and "map" for the maximum a posteriori estimate.

ci

a character string indicating the type of credible interval to be displayed in the posterior distribution plots, i.e., "none" for not displaying any credible intervals, "eti" (default) for displaying the equal-tailed intervals and "hdi" for displaying the highest density interval.

chain

a numerical value indicating the chain to be used for the autocorrelation plots. By default, the first chain is used.

conf.level

a numeric value between 0 and 1 indicating the confidence level of the credible interval (default is 0.95).

hist

logical: if TRUE (default), histograms are drawn in the posterior probability plots.

density

logical: if TRUE (default), density curves are drawn in the posterior probability plots.

area

logical: if TRUE (default), statistical not significant and statistical significant area is filled with a different color and vertical lines are drawn.

alpha

a numeric value between 0 and 1 for the alpha argument (default is 0.4) for the annotate, geom_histogram, geom_bar, and geom_ribbon function.

fill

a character string indicating the color for the "fill" argument (default is "gray85") for the annotate, geom_histogram, geom_bar, and geom_point functions.

nrow

a numeric value indicating the nrow argument (default is NULL) for the facet_wrap function.

ncol

a numeric value indicating the ncol argument (default is 2) for the facet_wrap function.

scales

a character string indicating the scales argument (default is "free") for the facet_wrap function.

xlab

a character string indicating the name argument for the scale_x_continuous function. Note that the default setting depends on the type of plot, e.g., "" for the trace plots and "Lag" for the autocorrelation plots.

ylab

a character string indicating the name argument for the scale_y_continuous function. Note that the default setting depends on the type of plot, e.g., "" for the trace plots and "Autocorrelation" for the autocorrelation plots.

xlim

a numeric vector with two elements indicating the limits argument (default it NULL) for the scale_x_continuous function.

ylim

a numeric vector with two elements indicating the limits argument (default it NULL) for the scale_y_continuous function.

xbreaks

a numeric vector indicating the breaks argument (default is ggplot2::waiver()) for the scale_x_continuous function.

ybreaks

a numeric vector indicating the breaks argument (default is ggplot2::waiver()) for the scale_y_continuous function.

xexpand

a numeric vector with two elements indicating the expand argument (default is (0.02, 0)) for the scale_x_continuous function.

yexpand

a numeric vector with two elements indicating the expand argument for the scale_y_continuous function. Note that the default setting depends on the type of plot, e.g., (0.02, 0) for the trace plots and expansion(mult = c(0, 0.05)) for the posterior distribution plots.

palette

a character string indicating the palette name (default is "Set 2") for the hcl.colors function. Note that the character string must be one of hcl.pals().

binwidth

a numeric value indicating the binwidth argument (default is to use the number of bins in bins argument) for the geom_histogram function.

bins

a numeric value indicating the bins argument (default is 30) for the geom_histogram function.

density.col

a character string indicating the color argument (default is "#0072B2") for the geom_density function.

shape

a numeric value indicating the shape argument (default is 21) for the geom_point function.

point.col

a character vector with three elements indicating the values argument (default is c("#CC79A7", "#D55E00", "#009E73")) for the scale_color_manual function.

linewidth

a numeric value indicating the linewidth argument (default is 0.6) for the geom_vline function.

linetype

a numeric value indicating the linetype argument (default is "dashed") for the geom_vline function.

line.col

a character string indicating the color argument (default is "black") for the geom_vline function.

bar.col

a character string indicating the color argument (default is "black") for the geom_bar function.

bar.width

a character string indicating the width argument (default = 0.8)for the geom_bar function.

plot.margin

a numeric vector indicating the plot.margin argument for the theme function. Note that the default setting depends on the type of the plot, e.g., c(4, 15, -10, 0) for the trace plots, and c(4, 15, 4, 4) for the autocorrelation plots.

legend.title.size

a numeric value indicating the legend.title argument (default is element_text(size = 10)) for the theme function.

legend.text.size

a numeric value indicating the legend.text argument (default is element_text(size = 10)) for the theme function.

legend.box.margin

a numeric vector indicating the legend.box.margin argument for the theme function. Note that the default setting depends on the type of plot, e.g., c(-16, 6, 6, 6) for the trace plots, and c(-25, 6, 6, 6) for the posterior distribution plots with displaying point estimates.

saveplot

a character vector indicating the plot to be saved, i.e., "all" for saving all plots, "none" (default) for not saving any plots, "trace" for saving the trace plots, post for the saving the posterior distribution plots, "auto" for saving the autocorrelation plots, "ppc" for saving the posterior predictive check plots, and "loop" for saving the loop plot.

file

a character string indicating the filename argument (default is "Mplus_Plot.pdf") including the file extension for the ggsave function. Note that one of ".eps", ".ps", ".tex", ".pdf" (default), ".jpeg", ".tiff", ".png", ".bmp", ".svg" or ".wmf" needs to be specified as file extension in the file argument.

file.plot

a character vector with five elements for distinguishing different types of plots. By default, the character string specified in the argument "file" ("Mplus_Plot") is concatenated with "_TRACE" ("Mplus_Plot_TRACE") for the trace plots, "_POST" ("Mplus_Plot_POST") for the posterior distribution plots, "_AUTO" ("Mplus_Plot_AUTO") for the autocorrelation plots, "_PPC" ("Mplus_Plot_PPC") for the posterior predictive check plots, and "_LOOP" ("Mplus_Plot_LOOP") for the loop plot.

width

a numeric value indicating the width argument (default is the size of the current graphics device) for the ggsave function.

height

a numeric value indicating the height argument (default is the size of the current graphics device) for the ggsave function.

units

a character string indicating the units argument (default is in) for the ggsave function.

dpi

a numeric value indicating the dpi argument (default is 600) for the ggsave function.

check

logical: if TRUE (default), argument specification is checked.

Author

Takuya Yanagida

References

Muthen, L. K., & Muthen, B. O. (1998-2017). Mplus User's Guide (8th ed.). Muthen & Muthen.

See Also

read.mplus, write.mplus, mplus, mplus.update, mplus.print, mplus.bayes, mplus.run, mplus.lca

Examples

Run this code
if (FALSE) {
#----------------------------------------------------------------------------
# Mplus Example 3.18: Moderated Mediation with a Plot of the Indirect Effect

#..........
# Trace Plots

# Example 1a: Default setting
mplus.plot("ex3.18.gh5")

# Example 1b: Exclude first half of each chain
mplus.plot("ex3.18.gh5", burnin = FALSE)

# Example 1c: Print all parameters
mplus.plot("ex3.18.gh5", param = "all")

# Example 1d: Print user-specified parameters
mplus.plot("ex3.18.gh5", param = "param")

# Example 1e: Arrange panels in three columns
mplus.plot("ex3.18.gh5", ncol = 3)

# Example 1f: Specify "Pastel 1" palette for the hcl.colors function
mplus.plot("ex3.18.gh5", palette = "Pastel 1")

#..........
# Posterior Distribution Plots

# Example 2a: Default setting, i.e., posterior median and equal-tailed interval
mplus.plot("ex3.18.gh5", plot = "post")

# Example 2b: Display posterior mean and maximum a posteriori
mplus.plot("ex3.18.gh5", plot = "post", point = c("m", "map"))

# Example 2c: Display maximum a posteriori and highest density interval
mplus.plot("ex3.18.gh5", plot = "post", point = "map", ci = "hdi")

# Example 2d: Do not display any point estimates and credible interval
mplus.plot("ex3.18.gh5", plot = "post", point = "none", ci = "none")

# Example 2d: Do not display histograms
mplus.plot("ex3.18.gh5", plot = "post", hist = FALSE)

#..........
# Autocorrelation Plots

# Example 3a: Default setting, i.e., first chain
mplus.plot("ex3.18.gh5", plot = "auto")

# Example 3b: Use second chain
mplus.plot("ex3.18.gh5", plot = "auto", chain = 2)

# Example 3b: Modify limits and breaks of the y-axis
mplus.plot("ex3.18.gh5", plot = "auto",
           ylim = c(-0.05, 0.05), ybreaks = seq(-0.1, 0.1, by = 0.025))

#..........
# Posterior Predictive Check Plots

# Example 4a: Default setting, i.e., 95% Interval
mplus.plot("ex3.18.gh5", plot = "ppc")

# Example 4b: Default setting, i.e., 99% Interval
mplus.plot("ex3.18.gh5", plot = "ppc", conf.level = 0.99)

#..........
# Loop Plot

# Example 5a: Default setting
mplus.plot("ex3.18.gh5", plot = "loop")

# Example 5b: Do not fill area and draw vertical lines
mplus.plot("ex3.18.gh5", plot = "loop", area = FALSE)

#..........
# Save Plots

# Example 6a: Save all plots in pdf format
mplus.plot("ex3.18.gh5", saveplot = "all")

# Example 6b: Save all plots in png format with 300 dpi
mplus.plot("ex3.18.gh5", saveplot = "all", file = "Mplus_Plot.png", dpi = 300)

# Example 6a: Save loop plot, specify width and height of the plot
mplus.plot("ex3.18.gh5", plot = "none", saveplot = "loop",
           width = 7.5, height = 7)

#----------------------------------------------------------------------------
# Plot from misty.object

# Create misty.object
object <- mplus.plot("ex3.18.gh5", plot = "none")

# Trace plot
mplus.plot(object, plot = "trace")

# Posterior distribution plot
mplus.plot(object, plot = "post")

# Autocorrelation plot
mplus.plot(object, plot = "auto")

# Posterior predictive check plot
mplus.plot(object, plot = "ppc")

# Loop plot
mplus.plot(object, plot = "loop")

#----------------------------------------------------------------------------
# Create Plots Manually

# Load ggplot2 package
library(ggplot2)

# Create misty object
object <- mplus.plot("ex3.18.gh5", plot = "none")

#..........
# Example 7: Trace Plots

# Extract data in long format
data.post <- object$data$post$long

# Extract ON parameters
data.trace <- data.post[grep(" ON ", data.post$param), ]

# Plot
ggplot(data.trace, aes(x = iter, y = value, color = chain)) +
  annotate("rect", xmin = 0, xmax = 15000, ymin = -Inf, ymax = Inf,
           alpha = 0.4, fill = "gray85") +
  geom_line() +
  facet_wrap(~ param, ncol = 2, scales = "free") +
  scale_x_continuous(name = "", expand = c(0.02, 0)) +
  scale_y_continuous(name = "", expand = c(0.02, 0)) +
  scale_colour_manual(name = "Chain",
                      values = hcl.colors(n = 2, palette = "Set 2")) +
  theme_bw() +
  guides(color = guide_legend(nrow = 1, byrow = TRUE)) +
  theme(plot.margin = margin(c(4, 15, -10, 0)),
        legend.position = "bottom",
        legend.title = element_text(size = 10),
        legend.text = element_text(size = 10),
        legend.box.margin = margin(c(-16, 6, 6, 6)),
        legend.background = element_rect(fill = "transparent"))

#..........
# Example 8: Posterior Distribution Plots

# Extract data in long format
data.post <- object$data$post$long

# Extract ON parameters
data.post <- data.post[grep(" ON ", data.post$param), ]

# Discard burn-in iterations
data.post <- data.post[data.post$iter > 15000, ]

# Drop factor levels
data.post$param <- droplevels(data.post$param,
                              exclude = c("[Y]", "[M]", "Y", "M", "INDIRECT", "MOD"))

# Plot
ggplot(data.post, aes(x = value)) +
  geom_histogram(aes(y = after_stat(density)), color = "black", alpha = 0.4,
                 fill = "gray85") +
  geom_density(color = "#0072B2") +
  geom_vline(data = data.frame(param = unique(data.post$param),
                               stat = tapply(data.post$value, data.post$param, median)),
             aes(xintercept = stat, color = "Median"), linewidth = 0.6) +
  geom_vline(data = data.frame(param = unique(data.post$param),
                               low = tapply(data.post$value, data.post$param,
                                            function(y) quantile(y, probs = 0.025))),
             aes(xintercept = low), linetype = "dashed", linewidth = 0.6) +
  geom_vline(data = data.frame(param = unique(data.post$param),
                               upp = tapply(data.post$value, data.post$param,
                                            function(y) quantile(y, probs = 0.975))),
             aes(xintercept = upp), linetype = "dashed", linewidth = 0.6) +
  facet_wrap(~ param, ncol = 2, scales = "free") +
  scale_x_continuous(name = "", expand = c(0.02, 0)) +
  scale_y_continuous(name = "Probability Density, f(x)",
                     expand = expansion(mult = c(0L, 0.05))) +
  scale_color_manual(name = "Point Estimate", values = c(Median = "#D55E00")) +
  labs(caption = "95% Equal-Tailed Interval") +
  theme_bw() +
  theme(plot.margin = margin(c(4, 15, -8, 4)),
        plot.caption = element_text(hjust = 0.5, vjust = 7),
        legend.position = "bottom",
        legend.title = element_text(size = 10),
        legend.text = element_text(size = 10),
        legend.box.margin = margin(c(-30, 6, 6, 6)),
        legend.background = element_rect(fill = "transparent"))

#..........
# Example 9: Autocorrelation Plots

# Extract data in long format
data.auto <- object$data$auto$long

# Select first chain
data.auto <- data.auto[data.auto$chain == 1, ]

# Extract ON parameters
data.auto <- data.auto[grep(" ON ", data.auto$param), ]

# Plot
ggplot(data.auto, aes(x = lag, y = cor)) +
  geom_bar(stat = "identity", alpha = 0.4, color = "black", fill = "gray85",
           width = 0.8) +
  facet_wrap(~ param, ncol = 2) +
  scale_x_continuous(name = "Lag", breaks = seq(1, 30, by = 2), expand = c(0.02, 0)) +
  scale_y_continuous(name = "Autocorrelation", limits = c(-0.1, 0.1),
                     breaks = seq(-0.1, 1., by = 0.05), expand = c(0.02, 0)) +
  theme_bw() +
  theme(plot.margin = margin(c(4, 15, 4, 4)))

#..........
# Example 10: Posterior Predictive Check (PPC) Plots

# Extract data
data.ppc <- object$data$ppc

# Scatter plot
ppc.scatter <- ggplot(data.ppc, aes(x = obs, y = rep)) +
  geom_point(shape = 21, fill = "gray85") +
  geom_abline(slope = 1) +
  scale_x_continuous("Observed", limits = c(0, 45), breaks = seq(0, 45, by = 5),
                     expand = c(0.02, 0)) +
  scale_y_continuous("Recpliated", limits = c(0, 45), breaks = seq(0, 45, by = 5),
                     expand = c(0.02, 0)) +
  theme_bw() +
  theme(plot.margin = margin(c(2, 15, 4, 4)))

# Histogram
ppc.hist <- ggplot(data.ppc, aes(x = diff)) +
  geom_histogram(color = "black", alpha = 0.4, fill = "gray85") +
  geom_vline(xintercept = mean(data.ppc$diff), color = "#CC79A7") +
  geom_vline(xintercept = quantile(data.ppc$diff, probs = 0.025),
             linetype = "dashed", color = "#CC79A7") +
  geom_vline(xintercept = quantile(data.ppc$diff, probs = 0.975),
             linetype = "dashed", color = "#CC79A7") +
  scale_x_continuous("Observed - Replicated", expand = c(0.02, 0)) +
  scale_y_continuous("Count", expand = expansion(mult = c(0L, 0.05))) +
  theme_bw() +
  theme(plot.margin = margin(c(2, 15, 4, 4)))

# Combine plots using the patchwork package
patchwork::wrap_plots(ppc.scatter, ppc.hist)

#..........
# Example 11: Loop Plot

# Extract data
data.loop <- object$data$loop

# Plot
plot.loop <- ggplot(data.loop, aes(x = xval, y = estimate)) +
  geom_line(linewidth = 0.6, show.legend = FALSE) +
  geom_line(aes(xval, low)) +
  geom_line(aes(xval, upp)) +
  scale_x_continuous("MOD", expand = c(0.02, 0)) +
  scale_y_continuous("INDIRECT", expand = c(0.02, 0)) +
  scale_fill_manual("Statistical Significance",
                    values = hcl.colors(n = 2, palette = "Set 2")) +
  theme_bw() +
  theme(plot.margin = margin(c(4, 15, -6, 4)),
        legend.position = "bottom",
        legend.title = element_text(size = 10),
        legend.text = element_text(size = 10),
        legend.box.margin = margin(-10, 6, 6, 6),
        legend.background = element_rect(fill = "transparent"))

# Significance area
for (i in unique(data.loop$group)) {

  plot.loop <- plot.loop + geom_ribbon(data = data.loop[data.loop$group == i, ],
                                       aes(ymin = low, ymax = upp, fill = sig), alpha = 0.4)

}

# Vertical lines
plot.loop + geom_vline(data = data.loop[data.loop$change == 1, ],
                       aes(xintercept = xval, color = sig), linewidth = 0.6,
                           linetype = "dashed", show.legend = FALSE)
}

Run the code above in your browser using DataLab