There are three ways to visualize models composed in PsyNeuLink: statically, using the
show_graph method of a Composition; using the animate argument of a Composition’s
run method to output a gif showing the sequence with which its Nodes
are executed (see example); or interactively to configure
the display and plot Component
a standalone application that interacts closely with the Python script in which a PsyNeuLink model is composed.
The PsyNeuLinkView application is still under development; at present, it can be used to display a Composition and arrange its Components. Its functionality is being actively expanded, and it should soon be able to display animated plots of Component values as a Composition executes. It can be accessed here.
At present, use of the Composition’s
show_graph method and the animate argument of its
run method are the primary ways to visualize a Composition. The former is described below,
including examples of its use.
Use of the show_graph Method¶
Every Composition has a
show_graph method that can be used to generate a graphical display
of the Composition and, optionally, any nested Compositions within it. Each Node of the Composition is represented as a node in the graph, and Projections between
them as edges.
Every Composition is assigned a
ShowGraph object, that is implemented in the free-standing showgraph.py module.
show_graph method of a Composition directly calls the
show_graph method of its
ShowGraph object, as do all links to documentation concerning
By default, all nodes within a Composition, including any Compositions nested within it, are
shown, each displayed as an oval (if the node is a Mechanism) or a rectangle (if it is a nested Composition),
and labeled by its name. Each Composition’s
INPUT Nodes are shown in green, its
Nodes are shown in red, and any that are both (i.e., are
SINGLETONs) are shown in brown. Projections shown as
unlabeled arrows, as illustrated for the Composition in the examples. However,
these and other attributes of the graph can be modified using arguments in the call to the
Display structure – how much information is displayed for a Composition and any nested within it can be modified using the show_xxx arguments; for example, show_node_structure determines how much detail is shown about each Node; show_nested determines whether nested Compositions are shown embedded within their enclosing Compositions or as separate insets, and how many levels of nesting to show; show_controller determines whether or not to show a Composition’s controller; and show_learning determines whether or not to show its learning compnents. These are listed as the arguments for the show_graph <ShowGraph.show_graph>` method below.
Display attributes – the colors, shapes and arrow styles used in the display can be modified using the show_graph_attributes argument of a Composition’s constructor, as described below.
The default attributes used to display different types of Components and their
within a Composition are listed below. These can be customized using the show_graph_attributes argument of a
Composition’s constructor, in a dict with keys that are any of the parameters listed in
ShowGraph, and values
that are any supported by GraphViz for
Nested Composition: square
ControlProjection: box - ‘RANDOMIZATION_CONTROL_SIGNAL` : dashed line
MappingProjection that receives a LearningProjection when show_learning is True: diamond
Control-related components: blue
Learning-related components: orange
Inactive Projection: red
Active items (when animate = True in
An animation can be generated of the execution of a Composition by using the animate argument of the Composition’s
run method. The animation show a graphical display of the Composition, with each of its
the Components highlighted in the sequence that they are executed. The animate can be passed a dict containing
any of the options described above to customize the display, as well as several others used to customize the animation
(see animate argument under
At present, animation of the Components within a nested Composition is not supported; the box surrounding the nested Composition is highlighted when it is executed, followed by the next Component(s) to execute.
>>> from psyneulink import * >>> a = ProcessingMechanism( name='A', ... size=3, ... output_ports=[RESULT, MEAN] ... ) >>> b = ProcessingMechanism( ... name='B', ... size=5 ... ) >>> c = ProcessingMechanism( ... name='C', ... size=2, ... function=Logistic(gain=pnl.CONTROL) ... ) >>> comp = Composition( ... name='Comp', ... enable_controller=True ... ) >>> comp.add_linear_processing_pathway([a,c]) >>> comp.add_linear_processing_pathway([b,c]) >>> ctlr = OptimizationControlMechanism( ... name='Controller', ... monitor_for_control=[(pnl.MEAN, a)], ... control_signals=(GAIN, c), ... agent_rep=comp ... ) >>> comp.add_controller(ctlr)
Note that the Composition’s
controller is not shown by default. However this
can be shown, along with other information, using options in the Composition’s
method. The figure below shows several examples.
Output of show_graph using different options
If a Composition has one ore more Compositions nested as Nodes within it, these can be shown using the
show_nested option. For example, the pathway in the script below contains a sequence of Mechanisms
and nested Compositions in an outer Composition,
>>> mech_stim = ProcessingMechanism(name='STIMULUS') >>> mech_A1 = ProcessingMechanism(name='A1') >>> mech_B1 = ProcessingMechanism(name='B1') >>> comp1 = Composition(name='comp1') >>> comp1.add_linear_processing_pathway([mech_A1, ... mech_B1]) >>> mech_A2 = ProcessingMechanism(name='A2') >>> mech_B2 = ProcessingMechanism(name='B2') >>> comp2 = Composition(name='comp2') >>> comp2.add_linear_processing_pathway([mech_A2, ... mech_B2]) >>> mech_resp = ProcessingMechanism(name='RESPONSE') >>> comp = Composition() >>> comp.add_linear_processing_pathway([mech_stim, ... comp1, comp2, ... mech_resp]) >>> comp.show_graph(show_nested=True)
- class psyneulink.core.compositions.showgraph.ShowGraph(composition, direction='BT', mechanism_shape='oval', feedback_shape='octagon', cycle_shape='doublecircle', cim_shape='rectangle', controller_shape='doubleoctagon', composition_shape='rectangle', agent_rep_shape='egg', default_projection_arrow='normal', learning_projection_shape='diamond', control_projection_arrow='box', default_node_color='black', active_color='bold', input_color='green', probe_color='pink', output_color='red', input_and_output_color='brown', control_color='blue', controller_color='purple', learning_color='orange', composition_color='pink', inactive_projection_color='red', default_width=1, active_thicker_by=2, bold_width=3, input_rank='source', control_rank='min', learning_rank='min', output_rank='max')¶
ShowGraph object with
show_graphmethod for displaying Composition.
Every Composition is assigned a ShowGraph object, with its
show_graphmethod assigned to, and callable as Composition.show_graph().
direction (keyword : default 'BT') – specifies the orientation of the graph (input -> output): - ‘BT’: bottom to top; - ‘TB’: top to bottom; - ‘LR’: left to right; - ‘RL`: right to left.
mechanism_shape (keyword : default 'oval') – specifies the display shape of nodes that are not assigned a
NodeRoleassociated with a dedicated shape.
feedback_shape (keyword : default 'septagon') – specifies the display shape of nodes that are assigned the
cycle_shape (keyword : default 'doublecircle') – specifies the display shape of nodes that are assigned the
cim_shape (default 'square') – specifies the shape in which CompositionInterfaceMechanisms are displayed.
controller_shape (default 'doubleoctagon') – specifies the shape in which a Composition’s
composition_shape (default 'rectangle') – specifies the shape in which nodes that represent nested Compositions are displayed when show_nested is specified as False or a Composition is nested below the level specified in a call to
agent_rep_shape (default 'egg') – specifies the shape in which the
agent_repof an OptimizationControlMechanism is displayed.
default_projection_arrow (keywrod : default 'normal') – specifies the shape of the arrow used to display MappingProjections.
learning_projection_shape (default 'diamond') – specifies the shape in which
LearningProjetionss are displayed.
control_projection_arrow (default 'box') – specifies the shape in which the head of a ControlProjection is displayed.
default_node_color (keyword : default 'black') – specifies the color in which nodes not assigned another color are displayed.
active_color (keyword : default BOLD) – specifies how to highlight the item(s) specified in the active_items argument of a call to
show_graph: either a color recognized by GraphViz, or the keyword BOLD.
input_color (keyword : default 'green',) – specifies the color in which
INPUTNodes of the Composition are displayed.
probe_color (keyword : default 'pink',) – specifies the color in which
PROBENodes of the Composition are displayed.
output_color (keyword : default 'red',) – specifies the color in which
OUTPUTNodes of the Composition are displayed.
input_and_output_color (keyword : default 'brown') – specifies the color in which nodes that are both an
OUTPUTNode of the Composition are displayed.
control_color (keyword : default 'blue') – specifies the color in which ControlMechanisms (other than a Composition’s
controllerand ControlProjections are displayed.
controller_color (keyword : default 'purple') – specifies the color in which a Composition’s
learning_color (keyword : default 'orange') – specifies the color in which the learning components are displayed.
composition_color (keyword : default 'pink') – specifies the color in which nodes that represent
nested Compositionsbelow the level specified in a call to
inactive_projection_color (keyword : default 'red') – specifies the color in which Projections not active within the Composition are displayed, when the
show_projections_not_in_compositionoption is True.
default_width (int : default 1) – specifies the width to use for the outline of nodes and the body of Projection arrows.
active_thicker_by (int : default 2) – specifies the amount by which to increase the width of the outline of Components specified in the active_items argument of a call to
bold_width (int : default 3,) – specifies the width of the outline for
OUTPUTNodes of the Composition.
- show_graph(show_all=False, show_node_structure=False, show_nested='nested', show_nested_args='all', show_cim=False, show_controller=True, show_learning=False, show_headers=True, show_types=False, show_dimensions=False, show_projection_labels=False, show_projections_not_in_composition=False, active_items=None, output_fmt='pdf', context=None, *args, **kwargs)¶
Show graphical display of Components in a Composition’s graph. See show_graph for additional details.
This method relies on graphviz, which must be installed and imported (standard with PsyNeuLink pip install)
show_all (bool : default False) – if False, defer to specification of all other arguments; if True, override all show_XXX arguments, automatically specifying them with their most informative settings.
show_node_structure (bool, VALUES, LABELS, FUNCTIONS, MECH_FUNCTION_PARAMS, PORT_FUNCTION_PARAMS, ROLES, or ALL : default False) –
show a detailed representation of each Mechanism in the graph, including its Ports; can have any of the following settings alone or in a list:
True– show Ports of Mechanism, but not information about the
functionof the Mechanism or its Ports.
VALUES – show the
valueof the Mechanism and the
valueof each of its Ports.
LABELS – show the
valueof the Mechanism and the
valueof each of its Ports, using any labels for the values of InputPorts and OutputPorts specified in the Mechanism’s
FUNCTIONS – show the
functionof the Mechanism and the
functionof its InputPorts and OutputPorts.
MECH_FUNCTION_PARAMS_ – show the parameters of the
functionfor each Mechanism in the Composition (only applies if FUNCTIONS is True).
PORT_FUNCTION_PARAMS_ – show the parameters of the
functionfor each Port of each Mechanism in the Composition (only applies if FUNCTIONS is True).
ROLES – show the
roleof the Mechanism in the Composition (but not any of the other information; use ALL to show ROLES with other information).
ALL – shows the role,
valueof the Mechanisms in the Composition and their Ports (using labels for the values, if specified – see above), including parameters for all functions.
show_nested (bool | int | NESTED | INSET : default NESTED) – specifies whether or not to show nested Compositions and, if so, how many levels of nesting to show (NESTED, True or int) – with Projections shown directly from Components in an enclosing Composition to and from ones in the nested Composition; or each nested Composition as a separate inset (INSET). NESTED specifies all levels of nesting shown; 0 specifies none (same as False), and a non-zero integer species that number of nested levels to shown. Compsitions nested at the specified level are shown as a node (pink box by default). and ones below the specified level are not shown at all.
show_nested_args (bool | dict : default ALL) – specifies arguments in call to show_graph passed to nested Composition(s) if show_nested is specified. A dict can be used to specify any of the arguments allowed for show_graph to be used for the nested Composition(s); ALL passes all arguments specified for the main Composition to the nested one(s); True uses the default values of show_graph args for the nested Composition(s).
show_cim (bool : default False) – specifies whether or not to show the Composition’s
show_controller (bool or AGENT_REP : default True) – specifies whether or not to show the Composition’s
objective_mechanismif it has one. If the controller is an OptimizationControlMechanism and it has an agent_rep, then specifying AGENT_REP will also show that. All control-related items are displayed in the color specified for controller_color.
show_learning (bool or ALL : default False) – specifies whether or not to show the learning components of the Composition; they will all be displayed in the color specified for learning_color. Projections that receive a LearningProjection will be shown as a diamond-shaped node. If set to ALL, all Projections associated with learning will be shown: the LearningProjections as well as from ProcessingMechanisms to LearningMechanisms that convey error and activation information; if set to
True, only the LearningPojections are shown.
show_projection_labels (bool : default False) – specifies whether or not to show names of projections.
show_projections_not_in_composition (bool : default False) – specifies whether or not to show Projections that are not active in the current Composition (and, accordingly, are not listed in its
projectionsattribute); these are shown in red.
show_headers (bool : default True) – specifies whether or not to show headers in the subfields of a Mechanism’s node; only takes effect if show_node_structure is specified (see above).
show_types (bool : default False) – specifies whether or not to show type (class) of Mechanism in each node label.
show_dimensions (bool : default False) –
specifies whether or not to show dimensions for the
valueof each Component in the graph (and/or MappingProjections when show_learning is
True); can have the following settings:
MECHANISMS – shows Mechanism input and output dimensions. Input dimensions are shown in parentheses below the name of the Mechanism; each number represents the dimension of the
variablefor each InputPort of the Mechanism; Output dimensions are shown above the name of the Mechanism; each number represents the dimension for
valueof each of OutputPort of the Mechanism.
PROJECTIONS – shows MappingProjection
matrixdimensions. Each is shown in (<dim>x<dim>…) format; for standard 2x2 “weight” matrix, the first entry is the number of rows (input dimension) and the second the number of columns (output dimension).
ALL – eqivalent to
True; shows dimensions for both Mechanisms and Projections (see above for formats).
active_items (List[Component] : default None) – specifies one or more items in the graph to display in the color specified by active_color*.
output_fmt (keyword or None : default 'pdf') – ‘pdf’: generate and open a pdf with the visualization; ‘jupyter’: return the object (for working in jupyter/ipython notebooks); ‘gv’: return graphviz object ‘gif’: return gif used for animation None : return None
determined by **output_fmt: -
jupyter– Graphviz graph object; -
gif– gif -
source– str with content of G.body
- Return type