Visualization¶

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 values using PsyNeuLinkView – a standalone application that interacts closely with the Python script in which a PsyNeuLink model is composed.

Note

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. The show_graph method of a Composition directly calls the show_graph method of its ShowGraph object, as do all links to documentation concerning show_graph.

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 OUTPUT 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 show_graph method.

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.

Display Attributes¶

The default attributes used to display different types of Components and their roles 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 shapes, arrow styles colors.

Shapes¶

Nested Composition: square

Mechanism:

default: oval
CYCLE: doublecircle
FEEDBACK_SENDER: octagon
CONTROLLER: doubleoctagon

Projection:

default: arrow
ControlProjection: box - ‘RANDOMIZATION_CONTROL_SIGNAL` : dashed line
MappingProjection that receives a LearningProjection when show_learning is True: diamond

Colors¶

Component-types¶

Control-related components: blue
Controller-related: purple
Learning-related components: orange
Inactive Projection: red
Active items (when animate = True in run): BOLD

Nodes¶

INPUT: green

OUTPUT: red

SINGLETON: brown

CONTROL: blue

CONTROLLER : purple

LEARNING : orange

Animation¶

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 run).

Note

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.

Examples¶

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 show_graph method. The figure below shows several examples.

Output of show_graph using different options

Composition graph examples — Displays of the Composition in the example above, generated using various options of its `show_graph` method. **Panel A** shows the graph with its Projections labeled and Component dimensions displayed. **Panel B** shows the `controller` for the Composition and its associated ObjectiveMechanism using the **show_controller** option (controller-related Components are displayed in blue by default). **Panel C** adds the Composition’s CompositionInterfaceMechanisms using the **show_cim** option. **Panel D** shows a detailed view of the Mechanisms using the **show_node_structure** option, that includes their Ports and their `roles` in the Composition. **Panel E** shows an even more detailed view using **show_node_structure** as well as **show_cim**.¶

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, comp:

>>> 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)

_images/Composition_show_graph_show_nested_fig.svg

Class Reference¶

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_graph method for displaying Composition.

Every Composition is assigned a ShowGraph object, with its show_graph method assigned to, and callable as Composition.show_graph().

Parameters

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 NodeRole associated with a dedicated shape.
feedback_shape (keyword : default 'septagon') – specifies the display shape of nodes that are assigned the NodeRole FEEDBACK_SENDER.
cycle_shape (keyword : default 'doublecircle') – specifies the display shape of nodes that are assigned the NodeRole CYCLE.
cim_shape (default 'square') – specifies the shape in which CompositionInterfaceMechanisms are displayed.
controller_shape (default 'doubleoctagon') – specifies the shape in which a Composition’s controller is displayed.
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 show_graph().
agent_rep_shape (default 'egg') – specifies the shape in which the agent_rep of 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 INPUT Nodes of the Composition are displayed.
probe_color (keyword : default 'pink',) – specifies the color in which PROBE Nodes of the Composition are displayed.
output_color (keyword : default 'red',) – specifies the color in which OUTPUT Nodes of the Composition are displayed.
input_and_output_color (keyword : default 'brown') – specifies the color in which nodes that are both an INPUT and an OUTPUT Node of the Composition are displayed.
control_color (keyword : default 'blue') – specifies the color in which ControlMechanisms (other than a Composition’s controller and ControlProjections are displayed.
controller_color (keyword : default 'purple') – specifies the color in which a Composition’s controller is displayed.
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 Compositions below the level specified in a call to show_graph().
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_composition option 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 show_graph().
bold_width (int : default 3,) – specifies the width of the outline for INPUT and OUTPUT Nodes 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.

Note

This method relies on graphviz python and system packages, which must be installed. The python package comes standard with PsyNeuLink pip install, but the system package must be installed separately. It can be downloaded at https://www.graphviz.org/download/.

Parameters

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 value or function of the Mechanism or its Ports.
- VALUES – show the value of the Mechanism and the value of each of its Ports.
- LABELS – show the value of the Mechanism and the value of each of its Ports, using any labels for the values of InputPorts and OutputPorts specified in the Mechanism’s input_labels_dict and output_labels_dict, respectively.
- FUNCTIONS – show the function of the Mechanism and the function of its InputPorts and OutputPorts.
- MECH_FUNCTION_PARAMS_ – show the parameters of the function for each Mechanism in the Composition (only applies if FUNCTIONS is True).
- PORT_FUNCTION_PARAMS_ – show the parameters of the function for each Port of each Mechanism in the Composition (only applies if FUNCTIONS is True).
- ROLES – show the role of the Mechanism in the Composition (but not any of the other information; use ALL to show ROLES with other information).
- ALL – shows the role, function, and value of 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 input_CIM, parameter_CIM, and output_CIM CompositionInterfaceMechanisms (CIMs).
show_controller (bool or AGENT_REP : default True) – specifies whether or not to show the Composition’s controller and associated objective_mechanism if it has one. If the controller is an OptimizationControlMechanism and it has an agent_rep, then specifying AGENT_REP also shows that. All control-related items are displayed in the color specified for controller_color.
show_learning (bool, LEARNABLE, SHOW_JUST_LEARNING_PROJECTIONS, or ALL : default False) – specifies whether or not to show the learning components of the Composition; they are all displayed in the color specified for learning_color. Projections that receive a LearningProjection are shown as a diamond-shaped node. If set to LEARNABLE, all LearningMechanisms are shown but only LearningProjections that are enabled are shown; if set to True or ALL, all Projections associated with learning are shown (that is, the LearningProjections as well as those from ProcessingMechanisms to LearningMechanisms that convey error and activation information; if set to SHOW_JUST_LEARNING_PROJECTIONS, the display is restricted to LearningProjections that are enabled.
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 projections attribute); 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 variable and value of 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 variable for each InputPort of the Mechanism; Output dimensions are shown above the name of the Mechanism; each number represents the dimension for value of each of OutputPort of the Mechanism.
- PROJECTIONS – shows MappingProjection matrix dimensions. 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 ‘source’: return the source code for the graphviz object None : return None

Returns

determined by output_fmt: - pdf – PDF: (placed in current directory); - gv or jupyter – Graphviz graph object; - gif – gif - source – str with content of G.body

Return type

pdf or Graphviz graph object