sem (version 3.1-16)

pathDiagram: Draw Path Diagram

Description

pathDiagram creates a description of the path diagram for a structural-equation-model or SEM-specification object to be processed by the graph-drawing program dot.

Usage

pathDiagram(model, ...)
# S3 method for sem
pathDiagram(model, file = "pathDiagram", 
    style = c("ram", "traditional"),
    output.type = c("html", "graphics", "dot"), graphics.fmt = "pdf", 
    dot.options = NULL,
    size = c(8, 8), node.font = c("Helvetica", 14),
    edge.font = c("Helvetica", 10), digits = 2, 
    rank.direction = c("LR", "TB"),
    min.rank = NULL, max.rank = NULL, same.rank = NULL,
    variables = model$var.names, var.labels, parameters, par.labels,
    ignore.double = TRUE, ignore.self = FALSE, error.nodes = TRUE,
    edge.labels = c("names", "values", "both"),  
    edge.colors = c("black", "black"),
    edge.weight = c("fixed", "proportional"),
    node.colors = c("transparent", "transparent", "transparent"),
    standardize = FALSE, ...)
# S3 method for semmod
pathDiagram(model, obs.variables, ...)
math(text, html.only=FALSE, hat=FALSE)

Value

pathDiagram invisibly returns a character vector containing dot commands.

math returns a character vector containing suitable HTML markup.

Arguments

model

a structural-equation-model or SEM-specification object produced by sem, or, respectively, specifyEquations, specifyModel, or cfa.

...

arguments passed down, e.g., from the semmod method to the sem method.

file

a file name, by default "pathDiagram", given without an extension, to which to write the dot description of the path diagram if output.type "graphics" or "dot" is selected, and for the graphics output file (with appropriate extension) if "graphics" output is selected, in which case a ".dot" file and a graphics file of type specified by the graphics.fmt argument (below); file may include a path specification.

style

"ram" (the default) for a RAM path diagram including self-directed double-headed arrows representing variances, including error variances; or "traditional" for a path diagram including nodes representing error variables.

output.type

if "html" (the default), the path diagram will open in the user"s default web browser; if "dot", a file containing dot commands will be written; if "graphics", both .dot and graphics files will be written.

graphics.fmt

a graphics format recognized by the dot program; the default is "pdf"; graphics.fmt is also used for the extension of the graphics file that is created.

dot.options

options to be passed to the dot program, given as a character string.

size

the size of the graph, in inches.

node.font

font name and point-size for printing variable names.

edge.font

font name and point-size for printing arrow names or values.

digits

number of digits after the decimal point (default, 2) to which to round parameter estimates.

rank.direction

draw graph left-to-right, "LR", the default, or top-to-bottom, "TB".

min.rank

a character string listing names of variables to be assigned minimum rank (order) in the graph; the names should be separated by commas.

max.rank

a character string listing names of variables to be assigned maximum rank in the graph; the names should be separated by commas.

same.rank

a character string or vector of character strings of variables to be assigned equivalent rank in the graph; names in each string should be separated by commas.

variables

variable names; defaults to the variable names in model. If specified, the variable names should be in the same order as in model.

var.labels

a character vector with labels to be used in lieu of (some of) the variables names, for greater flexibility in labelling nodes in the graph --- e.g., the labels can be created with the math function. The elements of the vector must have names corresponding to variables in the model.

parameters

parameter names; defaults to the parameter names in model. If specified, the parameter names should be in the same order as in model.

par.labels

a character vector with labels to be used in lieu of (some of) the parameter names, for greater flexibility in labelling edges in the graph --- e.g., the labels can be created with the math function. The elements of the vector must have names corresponding to parameters in the model.

ignore.double

if TRUE, the default, double-headed arrows, representing variances and covariances, are not graphed.

ignore.self

if TRUE (the default is FALSE), and ignore.double=FALSE, self-directed double-headed arrows representing error variances are suppressed; note that if ignore.double=TRUE, all double-headed arrows, including self-directed arrows, are suppressed.

error.nodes

if TRUE (the default) and style="traditional", show the nodes representing error variables.

edge.labels

"names" to label arrows with parameter names; "values" to label arrows with parameter estimates, or "both".

edge.colors

two-element character vector giving colors of positive and negative arrows respectively; the default is c("black", "black").

edge.weight

if "proportional" (the default is "fixed"), the thickness of edges is proportional to the absolute size of the corresponding parameter estimate; this is generally sensible only if standardize=TRUE.

node.colors

a two- or three-element character vector giving colors of nodes representing exogenous, endogenous, and error variables (for traditional path diagrams) consecutively; the default is "transparent" for all three; if a two colors are given, error variables are colored as exogenous (the first color.

standardize

if TRUE, display standardized coefficients; default is FALSE.

obs.variables

a character vector with the names of the observed variables in the model.

text

a character string or vector of character strings to be translated into node or edge label symbols. If a vector of character strings is supplied, then the elements of the vector should be named with the corresponding variable (node) or parameter (edge) name.

html.only

If TRUE (the default is FALSE), the character strings in text are to be treated as an HTML character codes, in which case the prefix "#" and suffix ";" are appended to each. Otherwise, text should only contain the names of lowercase or uppercase Greek letters, such as "alpha" or "Alpha". The full set of Greek letters recognized is given in the file Greek.txt in the package's etc subdirectory -- or type sem:::Greek at the R command prompt. In either case, the symbols may be followed by numeric subscripts in curly braces consisting of numerals (e.g., "beta_{12}"), and/or numeric superscripts (e.g., "sigma^{2}", "sigma_{1}^{2}"). Superscripts and subscripts may also include most lowercase or uppercase letters. Depending upon your OS, subscripts and superscripts may only work properly with HTML output from pathDiagram, not with graphics output produced by dot.

hat

If TRUE (the default is FALSE), a hat (circumflex) is placed over the symbols in text; this feature doesn't produce a visually appealing result.

Author

John Fox , Adam Kramer, and Michael Friendly

Details

pathDiagram creates a description of the path diagram for a structural-equation-model or SEM-specification object to be processed by the graph-drawing program dot, which can be called automatically; see Koutsofios and North (2002) and https://www.graphviz.org/. To obtain graphics output directly, the dot program must be on the system search path.

Alternatively, HTML output can be created in a web browser without an independent installation of dot using facilities in the DiagrammeR package.

The math function can be used to create node (variable) and edge (arrow) labels with symbols such as Greek letters, subscripts, and superscripts.

The semmod method of pathDiagram sets up a call to the sem method.

The various arguments to pathDiagram can be used to customize the diagram, but if there are too many constraints on node placement, dot may fail to produce a graph or may produce a distorted graph. pathDiagram can create both RAM-style diagrams, in which variances are represented as self-directed arrows, and traditional path diagrams, in which error variables appear explicitly as nodes. As is conventional, latent variables (including error variables) are represented as ellipses and observed variables as rectangles; double-headed arrows represent covariances (and in RAM diagrams, variances) and single-headed arrows represent structural coefficients.

References

Koutsofios, E., and North, S. C. (2002) Drawing graphs with dot. https://graphviz.org/documentation/.

See Also

sem, specifyEquations, specifyModel, cfa

Examples

	if (interactive()) {
# The Duncan, Haller, and Portes Peer-Influences Model

R.DHP <- readMoments(diag=FALSE, names=c("ROccAsp", "REdAsp", "FOccAsp", 
                "FEdAsp", "RParAsp", "RIQ", "RSES", "FSES", "FIQ", "FParAsp"),
                text="
    .6247                                                              
    .3269  .3669                                                        
    .4216  .3275  .6404                                      
    .2137  .2742  .1124  .0839                                
    .4105  .4043  .2903  .2598  .1839                          
    .3240  .4047  .3054  .2786  .0489  .2220                    
    .2930  .2407  .4105  .3607  .0186  .1861  .2707              
    .2995  .2863  .5191  .5007  .0782  .3355  .2302  .2950        
    .0760  .0702  .2784  .1988  .1147  .1021  .0931 -.0438  .2087  
")

model.dhp <- specifyModel(text="
    RParAsp  -> RGenAsp, gam11,  NA
    RIQ      -> RGenAsp, gam12,  NA
    RSES     -> RGenAsp, gam13,  NA
    FSES     -> RGenAsp, gam14,  NA
    RSES     -> FGenAsp, gam23,  NA
    FSES     -> FGenAsp, gam24,  NA
    FIQ      -> FGenAsp, gam25,  NA
    FParAsp  -> FGenAsp, gam26,  NA
    FGenAsp  -> RGenAsp, beta12, NA
    RGenAsp  -> FGenAsp, beta21, NA
    RGenAsp  -> ROccAsp,  NA,       1
    RGenAsp  -> REdAsp,  lam21,  NA
    FGenAsp  -> FOccAsp,  NA,       1
    FGenAsp  -> FEdAsp,  lam42,  NA
    RGenAsp <-> RGenAsp, ps11,   NA
    FGenAsp <-> FGenAsp, ps22,   NA
    RGenAsp <-> FGenAsp, ps12,   NA
    ROccAsp <-> ROccAsp, theta1, NA
    REdAsp  <-> REdAsp,  theta2, NA
    FOccAsp <-> FOccAsp, theta3, NA
    FEdAsp  <-> FEdAsp,  theta4, NA
")

sem.dhp <- sem(model.dhp, R.DHP, 329,
    fixed.x=c("RParAsp", "RIQ", "RSES", "FSES", "FIQ", "FParAsp"))
    
pathDiagram(sem.dhp, min.rank="RIQ, RSES, RParAsp, FParAsp, FSES, FIQ", 
                     max.rank="ROccAsp, REdAsp, FEdAsp, FOccAsp",
                     same.rank="RGenAsp, FGenAsp",
                     edge.labels="values")
    
pathDiagram(model.dhp,
    obs.variables=c("RParAsp", "RIQ", "RSES", "FSES", "FIQ", 
        "FParAsp", "ROccAsp", "REdAsp", "FOccAsp", "FEdAsp"),
    style="traditional", 
    node.colors=c("pink", "lightblue", "lightgreen"),
    min.rank="RIQ, RSES, RParAsp, FParAsp, FSES, FIQ",
    max.rank="ROccAsp, REdAsp, FEdAsp, FOccAsp",
    same.rank="RGenAsp, FGenAsp",
    var.labels=c(RParAsp="Respondent Parental Aspiration", 
        RIQ="Respondent IQ",
        RSES="Respondent SES",
        FSES="Friend SES",
        FIQ="Friend IQ",
        FParAsp="Friend Parental Aspiration",
        ROccAsp="Respondent Occupational Aspiration",
        REdAsp="Respondent Educational Aspiration",
        RGenAsp="Respondent General Aspiration",
        FOccAsp="Friend Occupational Aspiration",
        FEdAsp="Friend Educational Aspiration",
        FGenAsp="Friend General Aspiration",
        math(c(RGenAsp.error="xi_{1}",
        FGenAsp.error="xi_{2}",
        ROccAsp.error="epsilon_{1}",
        REdAsp.error="epsilon_{2}",
        FOccAsp.error="epsilon_{3}",
        FEdAsp.error="epsilon_{4}"))),
    par.labels=math(c(gam11="gamma_{11}",
        gam12="gamma_{12}",
        gam13="gamma_{13}",
        gam14="gamma_{14}",
        gam23="gamma_{23}",
        gam24="gamma_{24}",
        gam25="gamma_{25}",
        gam26="gamma_{26}",
        beta12="beta_{12}",
        beta21="beta_{21}",
        lam21="lambda_{21}",
        lam42="lambda_{42}",
        ps11="psi_{11}",
        ps22="psi_{22}",
        ps12="psi_{12}",
        theta1="theta_{1}",
        theta2="theta_{2}",
        theta3="theta_{3}",
        theta4="theta_{4}")))
        
    # the following example contributed by Michael Friendly:
    
union <- readMoments(diag=TRUE,
    names=c('y1', 'y2', 'y3', 'x1', 'x2'), text="
14.610
-5.250  11.017
-8.057  11.087   31.971
-0.482   0.677    1.559   1.021
-18.857  17.861   28.250   7.139  215.662
")

union.mod <- specifyEquations(covs=c("x1, x2"), text="
y1 = gam12*x2
y2 = beta21*y1 + gam22*x2
y3 = beta31*y1 + beta32*y2 + gam31*x1
")

union.sem <- sem(union.mod, union, N=173)

dot <- pathDiagram(union.sem, style="traditional",  
    ignore.double=FALSE, error.nodes=FALSE,
    edge.labels="values", 
    min.rank=c("Years", "Age"), 
    max.rank=c("Sentiment", "Sentiment.error"),
    same.rank=c("Deference, Deference.error", "Activism, Activism.error"),
    variables=c("Deference", "Activism", "Sentiment", "Years", "Age"),
    edge.colors=c("black", "red"),
    node.colors = c("pink", "lightblue"))

cat(paste(dot, collapse="\n")) # dot commands

    }