mechanism {epicmodel} | R Documentation |
Investigate mechanisms
Description
Creates graphs that visiualize the mechanisms behind each sufficient cause using the DiagrammeR
package.
new_mechanism()
and validate_mechanism()
define the epicmodel_mechanism
S3 class, which is created by mechanism()
.
plot()
renders the graphs in the RStudio Viewer.
print()
prints the legend for node labels in the console.
Usage
mechanism(scc, modules = TRUE, module_colors = NULL)
new_mechanism(x = list())
validate_mechanism(x)
## S3 method for class 'epicmodel_mechanism'
plot(x, reverse = TRUE, ...)
## S3 method for class 'epicmodel_mechanism'
print(x, ...)
Arguments
scc |
For |
modules |
For |
module_colors |
For |
x |
|
reverse |
For |
... |
Additional arguments for generics |
Details
The graphs
One graph per sufficient cause is created. The graphs display steps as nodes and IF/IFNOT relations as edges. Nodes will not be
labeled with their IDs or descriptions due to limited space, but with newly created labels. These labels are based on the type of node and are
listed together with the step description in the legend
(accessed by print()
). Step descriptions are also accessible via tooltips in the
graph. Just put your cursor on the node labels.
There are 4 different types of nodes:
-
Component causes
: Labeled"CC"
, squares, gray border -
Interventions
: Labeled"I"
, triangles, gray border -
End steps
: Labeled"E"
, circles, black border -
Other steps
: Labeled"S"
, circles, gray border
There are 2 types of edges:
-
IF conditions
: gray arrows -
IFNOT conditions
: red and T-shaped
epicmodel_mechanism
objects
epicmodel_mechanism
objects are created by mechanism()
. They are lists containing 2 elements:
legend
A data.frame with up to 3 variables:
-
Label
: Contains the labels used in the graphs. -
Module
: Contains the name of the module to which this step belongs. Only available ifmodules = TRUE
inmechanism()
and if the SCC model actually uses modules (specified in elementsc_use_modules
ofepicmodel_scc
objects). -
Step
: A description of the corresponding step.
-
graph
A list of length equal to the number of sufficient causes. Each element contains another list with 2 elements:
-
ndf
: A data.frame containing information about nodes in the graph (seeDiagrammeR::node_aes()
). -
edf
: A data.frame containing information about edges in the graph (seeDiagrammeR::edge_aes()
).
-
ndf
Data.frames containing the following variables:
-
id
: Node ID used internally byDiagrammeR
to define edges (from
andto
inedf
data.frames). -
type
: Type of node as defined byepicmodel
. Possible options are:cc
(component cause),int
(intervention),end
(step that is part of an outcome definition),other
(all other steps). -
label
: The label displayed in the graph and listed in variableLabel
oflegend
. -
tooltip
: The text displayed when putting the cursor on top of the node label. Corresponds to the step descriptions in variableStep
oflegend
. -
shape
: The shape of the node.square
for typecc
,triangle
for typeint
, andcircle
for typesend
andother
. -
color
: Color of the node border. Gray for typescc
,int
, andother
, and black for typeend
. -
fillcolor
: Color of the background, which is similar for all steps in the same module. If modules are not considered,fillcolor
is white for all nodes. -
fontcolor
: Color of the node label. Always black.
-
edf
Data.frames containing the following variables:
-
id
: Edge ID used internally byDiagrammeR
. -
from
: Node ID of the node from which the edge starts. -
to
: Node ID of the node at which the edge ends. -
rel
: Type of edge as defined byepicmodel
. Possible options are:if
(from
node is in IF condition ofto
node),ifnot
(from
node is in IFNOT condition ofto
node). -
arrowhead
: Type of arrow.normal
for relif
andtee
for relifnot
. -
arrowsize
: Size of arrow. 1 for relif
and 1.2 for relifnot
. -
color
: Color of arrow. Gray for relif
and#A65141
for relifnot
.
-
Value
-
mechanism()
: An object of classepicmodel_mechanism
. Useplot()
to plot the graphs in the RStudio Viewer. Useprint()
to print the legend in the console. Useexport_mechanism()
to save the graphs as PNG, PDF, SVG, or PostScript. -
new_mechanism()
: An object of classepicmodel_mechanism
. -
validate_mechanism()
: An object of classepicmodel_mechanism
that has been checked to have the correct structure. -
plot.epicmodel_mechanism()
: Renders the graphs in the RStudio Viewer. -
print.epicmodel_mechanism()
: Prints the legend of theepicmodel_mechanism
object in the console.
See Also
-
export_mechanism()
for saving the plots -
DiagrammeR::node_aes()
for a list of node-related variables inDiagrammeR
-
DiagrammeR::edge_aes()
for a list of edge-related variables inDiagrammeR
Examples
# Create some SCC model
steplist_checked <- check_steplist(steplist_rain)
scc_model <- create_scc(steplist_checked)
# Derive mechanisms
mech <- mechanism(scc_model)
# new_mechanism() and validate_mechanism() are used inside mechanism()
# nonetheless, you can check its structure using validate_mechanism()
validate_mechanism(mech)
# Plot the mechanisms
plot(mech)
# Print the legend
print(mech)
mech