# 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 – features (such as the colors and shapes) in which different types of nodes are displayed can be modified by assigning a dictionary of attribute:values pairs to the show_graph_configuration argument of the Composition’s constructor. These are listed as the arguments for the ShowGraph object (used to display the graph) in the class reference below.

## Examples¶

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

## 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', output_color='red', input_and_output_color='brown', control_color='blue', controller_color='purple', learning_color='orange', composition_color='pink', 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.

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. 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. 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_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, active_items=None, output_fmt='pdf', context=None, **kwargs)

Show graphical display of Components in a Composition’s graph.

Note

This method relies on graphviz, which must be installed and imported (standard with PsyNeuLink pip install)

Parameters: 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 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_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 (x…) 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: - pdf – PDF: (placed in current directory); - gv or jupyter – Graphviz graph object; - gif – gif - source – str with content of G.body pdf or Graphviz graph object