GraphPlot - Graph plot appearance and behavior - MATLAB (original) (raw)

GraphPlot Properties

Graph plot appearance and behavior

GraphPlot properties control the appearance and behavior of plotted graphs. By changing property values, you can modify aspects of the graph display. Use dot notation to refer to a particular object and property:

G = graph([1 1 1 1 5 5 5 5],[2 3 4 5 6 7 8 9]); h = plot(G); c = h.EdgeColor; h.EdgeColor = 'k';

Color

expand all

Node color, specified as one of these values:

Example: plot(G,'NodeColor','k') creates a graph plot with black nodes.

Control how the NodeColor property is set, specified as one of these values:

If you change the value of the NodeColor orNodeCData property manually, MATLAB changes the value of the NodeColorMode property to'manual'.

Edge color, specified as one of these values:

Example: plot(G,'EdgeColor','r') creates a graph plot with red edges.

Control how the EdgeColor property is set, specified as one of these values:

If you change the value of the EdgeColor orEdgeCData property manually, MATLAB changes the value of the EdgeColorMode property to'manual'.

Color data of node markers, specified as a vector with length equal to the number of nodes in the graph. The values in NodeCData map linearly to the colors in the current colormap, resulting in different colors for each node in the plotted graph.

Color data of edge lines, specified as a vector with length equal to the number of edges in the graph. The values in EdgeCData map linearly to the colors in the current colormap, resulting in different colors for each edge in the plotted graph.

Series index, specified as a positive whole number or "none". This property is useful for reassigning the node or edge colors of severalGraphPlot objects so that they match each other. By default, theSeriesIndex property of a GraphPlot object is a number that corresponds to its order of creation, starting at 1. MATLAB uses the number to calculate indices for assigning colors when you call plotting functions. The indices refer to the rows of the arrays stored in theColorOrder property of the axes.

A SeriesIndex value of"none" corresponds to a neutral color that does not participate in the indexing scheme. (since R2023b)

MATLAB automatically updates the node and edge colors of theGraphPlot object when you change its SeriesIndex, or when you change the ColorOrder property on the axes. However, the following conditions must be true for the changes to have any effect:

Node and Edge Styling

expand all

Node marker symbol, specified as one of the values listed in this table, or as a cell array or string vector of such values. The default is to use circular markers for the graph nodes. Specify a cell array of character vectors or string vector to use different markers for each node.

Marker Description Resulting Marker
"o" Circle Sample of circle marker
"+" Plus sign Sample of plus sign marker
"*" Asterisk Sample of asterisk marker
"." Point Sample of point marker
"x" Cross Sample of cross marker
"_" Horizontal line Sample of horizontal line marker
"|" Vertical line Sample of vertical line marker
"square" Square Sample of square marker
"diamond" Diamond Sample of diamond marker
"^" Upward-pointing triangle Sample of upward-pointing triangle marker
"v" Downward-pointing triangle Sample of downward-pointing triangle marker
">" Right-pointing triangle Sample of right-pointing triangle marker
"<" Left-pointing triangle Sample of left-pointing triangle marker
"pentagram" Pentagram Sample of pentagram marker
"hexagram" Hexagram Sample of hexagram marker
"none" No markers Not applicable

Example: '+'

Example: 'diamond'

Node marker size, specified as a positive value in point units or as a vector of such values. Specify a vector to use different marker sizes for each node in the graph. The default value of MarkerSize is 4 for graphs with 100 or fewer nodes, and2 for graphs with more than 100 nodes.

Example: 10

Line style, specified as one of the line styles listed in this table, or as a cell array or string vector of such values. Specify a cell array of character vectors or string vector to use different line styles for each edge.

Character(s) Line Style Resulting Line
'-' Solid line Sample of a solid line
'--' Dashed line Sample of a dashed line
':' Dotted line Sample of a dotted line
'-.' Dash-dotted line Sample of a dash-dotted line
'none' No line No line

Edge line width, specified as a positive value in point units, or as a vector of such values. Specify a vector to use a different line width for each edge in the graph.

Example: 0.75

Transparency of graph edges, specified as a scalar value between 0 and1 inclusive. A value of 1 means fully opaque and0 means completely transparent (invisible).

Example: 0.25

Arrow size, specified as a positive value in point units or as a vector of such values. As a vector, ArrowSize specifies the size of the arrow for each edge in the graph. The default value of ArrowSize is 7 for graphs with 100 or fewer nodes, and 4 for graphs with more than 100 nodes.

ArrowSize only affects directed graphs.

Example: 15

Position of arrow along edge, specified as a value in the range [0 1] or as a vector of such values with length equal to the number of edges. A value near 0 places arrows closer to the source node, and a value near 1 places arrows closer to the target node. The default value is 0.5 so that the arrows are halfway between the source and target nodes.

ArrowPosition only affects directed graphs.

Toggle display of arrows on directed edges, specified as 'off' or'on', or as numeric or logical 1 (true) or 0 (false). A value of'on' is equivalent to true, and'off' is equivalent to false. Thus, you can use the value of this property as a logical value. The value is stored as an on/off logical value of type matlab.lang.OnOffSwitchState.

For directed graphs the default value is 'on' so that arrows are displayed, but you can specify a value of 'off' to hide the arrows on the directed edges. For undirected graphs ShowArrows is always'off'.

Position

expand all

Note

XData and YData must be specified together so that each node has a valid (x,y) coordinate. Optionally, you can specify ZData for 3-D coordinates.

x-coordinate of nodes, specified as a vector with length equal to the number of nodes in the graph.

Note

XData and YData must be specified together so that each node has a valid (x,y) coordinate. Optionally, you can specify ZData for 3-D coordinates.

y-coordinate of nodes, specified as a vector with length equal to the number of nodes in the graph.

Note

XData and YData must be specified together so that each node has a valid (x,y) coordinate. Optionally, you can specify ZData for 3-D coordinates.

z-coordinate of nodes, specified as a vector with length equal to the number of nodes in the graph.

Node and Edge Labels

expand all

Node labels, specified as a numeric vector or cell array of character vectors. The length of NodeLabel must be equal to the number of nodes in the graph. By defaultNodeLabel is a cell array containing the node IDs for the graph nodes:

Example: {'A', 'B', 'C'}

Example: [1 2 3]

Example: plot(G,'NodeLabel',G.Nodes.Name) labels the nodes with their names.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | cell

Selection mode for node labels, specified as 'auto' (default) or'manual'. Specify NodeLabelMode as'auto' to populate NodeLabel with the node IDs for the graph nodes (numeric node indices or node names). Specifying NodeLabelMode as 'manual' does not change the values inNodeLabel.

Node label color, specified as one of these values:

Example: plot(G,'NodeLabel',C,'NodeLabelColor','m') creates a graph plot with magenta node labels.

Edge labels, specified as a numeric vector or cell array of character vectors. The length of EdgeLabel must be equal to the number of edges in the graph. By defaultEdgeLabel is an empty cell array (no edge labels are displayed).

Example: {'A', 'B', 'C'}

Example: [1 2 3]

Example: plot(G,'EdgeLabels',G.Edges.Weight) labels the graph edges with their weights.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | cell

Selection mode for edge labels, specified as 'manual' (default) or'auto'. Specify EdgeLabelMode as'auto' to populate EdgeLabel with the edge weights inG.Edges.Weight (if available), or the edge indicesG.Edges(k,:) (if no weights are available). SpecifyingEdgeLabelMode as 'manual' does not change the values inEdgeLabel.

Edge label color, specified as one of these values:

Example: plot(G,'EdgeLabel',C,'EdgeLabelColor','m') creates a graph plot with magenta edge labels.

Interpretation of text characters, specified as one of these values:

TeX Markup

By default, MATLAB supports a subset of TeX markup. Use TeX markup to add superscripts and subscripts, modify the font type and color, and include special characters in the text.

Modifiers remain in effect until the end of the text. Superscripts and subscripts are an exception because they modify only the next character or the characters within the curly braces. When you set the interpreter to "tex", the supported modifiers are as follows.

Modifier Description Example
^{ } Superscript "text^{superscript}"
_{ } Subscript "text_{subscript}"
\bf Bold font "\bf text"
\it Italic font "\it text"
\sl Oblique font (usually the same as italic font) "\sl text"
\rm Normal font "\rm text"
\fontname{specifier} Font name — Replace_specifier_ with the name of a font family. You can use this in combination with other modifiers. "\fontname{Courier} text"
\fontsize{specifier} Font size —Replace_specifier_ with a numeric scalar value in point units. "\fontsize{15} text"
\color{specifier} Font color — Replace_specifier_ with one of these colors: red, green,yellow, magenta,blue, black,white, gray,darkGreen, orange, orlightBlue. "\color{magenta} text"
\color[rgb]{specifier} Custom font color — Replace_specifier_ with a three-element RGB triplet. "\color[rgb]{0,0.5,0.5} text"

This table lists the supported special characters for the"tex" interpreter.

Character Sequence Symbol Character Sequence Symbol Character Sequence Symbol
\alpha α \upsilon υ \sim ~
\angle ∠ \phi ϕ \leq ≤
\ast * \chi χ \infty ∞
\beta β \psi ψ \clubsuit ♣
\gamma γ \omega ω \diamondsuit ♦
\delta δ \Gamma Γ \heartsuit ♥
\epsilon ϵ \Delta Δ \spadesuit ♠
\zeta ζ \Theta Θ \leftrightarrow ↔
\eta η \Lambda Λ \leftarrow ←
\theta θ \Xi Ξ \Leftarrow ⇐
\vartheta ϑ \Pi Π \uparrow ↑
\iota ι \Sigma Σ \rightarrow →
\kappa κ \Upsilon ϒ \Rightarrow ⇒
\lambda λ \Phi Φ \downarrow ↓
\mu µ \Psi Ψ \circ º
\nu ν \Omega Ω \pm ±
\xi ξ \forall ∀ \geq ≥
\pi π \exists ∃ \propto ∝
\rho ρ \ni ∍ \partial ∂
\sigma σ \cong ≅ \bullet •
\varsigma ς \approx ≈ \div ÷
\tau τ \Re ℜ \neq ≠
\equiv ≡ \oplus ⊕ \aleph ℵ
\Im ℑ \cup ∪ \wp ℘
\otimes ⊗ \subseteq ⊆ \oslash ∅
\cap ∩ \in ∈ \supseteq ⊇
\supset ⊃ \lceil ⌈ \subset ⊂
\int ∫ \cdot · \o ο
\rfloor ⌋ \neg ¬ \nabla ∇
\lfloor ⌊ \times x \ldots ...
\perp ⊥ \surd √ \prime ´
\wedge ∧ \varpi ϖ \0 ∅
\rceil ⌉ \rangle 〉 \mid |
\vee ∨ \langle 〈 \copyright ©

LaTeX Markup

To use LaTeX markup, set the Interpreter property to'latex'. Use dollar symbols around the text, for example, use'$\int_1^{20} x^2 dx$' for inline mode or '$$\int_1^{20} x^2 dx$$' for display mode.

The displayed text uses the default LaTeX font style. The FontName,FontWeight, and FontAngle properties do not have an effect. To change the font style, use LaTeX markup.

The maximum size of the text that you can use with the LaTeX interpreter is 1200 characters.

For more information about the LaTeX system, see The LaTeX Project website at https://www.latex-project.org/.

Font

expand all

Font name for node labels, specified as a supported font name or'FixedWidth'. For labels to display and print properly, you must choose a font that your system supports. The default font depends on the specific operating system and locale. For example, Windows® and Linux® systems in English localization use the Helvetica font by default.

To use a fixed-width font that looks good in any locale, specify'FixedWidth'.

Example: 'Cambria'

Font size for node labels, specified as a positive number or a vector of positive numbers. If NodeFontSize is a vector, then each element specifies the font size of one node label. The default font size depends on the specific operating system and locale.

Thickness of text in node labels, specified as 'normal','bold', or as a string vector or cell array of character vectors specifying 'normal' or 'bold' for each node.

Not all fonts have a bold font weight.

Data Types: cell | char | string

Character slant of text in node labels, specified as 'normal','italic', or as a string vector or cell array of character vectors specifying 'normal' or 'italic' for each node.

Not all fonts have both font styles.

Data Types: cell | char | string

Font name for edge labels, specified as a supported font name or'FixedWidth'. For labels to display and print properly, you must choose a font that your system supports. The default font depends on the specific operating system and locale. For example, Windows and Linux systems in English localization use the Helvetica font by default.

To use a fixed-width font that looks good in any locale, specify'FixedWidth'.

Example: 'Cambria'

Font size for edge labels, specified as a positive number or a vector of positive numbers. If EdgeFontSize is a vector, then each element specifies the font size of one edge label. The default font size depends on the specific operating system and locale.

Thickness of text in edge labels, specified as 'normal','bold', or as a string vector or cell array of character vectors specifying 'normal' or 'bold' for each edge.

Not all fonts have a bold font weight.

Data Types: cell | char | string

Character slant of text in edge labels, specified as 'normal','italic', or as a string vector or cell array of character vectors specifying 'normal' or 'italic' for each edge.

Not all fonts have both font styles.

Data Types: cell | char | string

Legend

expand all

Text used by the legend, specified as a character vector. The text appears next to an icon of the GraphPlot.

Example: 'Text Description'

For multiline text, create the character vector using sprintf with the new line character \n.

Example: sprintf('line one\nline two')

Alternatively, you can specify the legend text using the legend function.

If you edit interactively the character vector in an existing legend, then MATLAB updates the DisplayName property to the edited character vector.

This property is read-only.

Legend icon display style, returned as an Annotation object. Use this object to include or exclude the GraphPlot from a legend.

  1. Query the Annotation property to get theAnnotation object.
  2. Query the LegendInformation property of theAnnotation object to get the LegendEntry object.
  3. Specify the IconDisplayStyle property of theLegendEntry object to one of these values:
    • 'on' — Include the GraphPlot object in the legend as one entry (default).
    • 'off' — Do not include the GraphPlot object in the legend.
    • 'children' — Include only children of the GraphPlot object as separate entries in the legend.

If a legend already exists and you change theIconDisplayStyle setting, then you must call legend to update the display.

Interactivity

expand all

Data tip content, specified as a DataTipTemplate object. You can control the content that appears in a data tip by modifying the properties of the underlying DataTipTemplate object. For a list of properties, seeDataTipTemplate Properties.

For an example of modifying data tips, see Create Custom Data Tips.

Note

The DataTipTemplate object is not returned byfindobj or findall, and it is not copied by copyobj.

Callbacks

expand all

Mouse-click callback, specified as one of these values:

Use this property to execute code when you click the GraphPlot. If you specify this property using a function handle, then MATLAB passes two arguments to the callback function when executing the callback:

For more information on how to use function handles to define callback functions, see Create Callbacks for Graphics Objects.

Note

If the PickableParts property is set to 'none' or if the HitTest property is set to 'off', then this callback does not execute.

Example: @myCallback

Example: {@myCallback,arg3}

Creation callback, specified as one of these values:

Use this property to execute code when you create the GraphPlot. Setting the CreateFcn property on an existing GraphPlot has no effect. You must define a default value for this property, or define this property using a Name,Value pair during GraphPlot creation. MATLAB executes the callback after creating the GraphPlot and setting all of its properties.

If you specify this callback using a function handle, then MATLAB passes two arguments to the callback function when executing the callback:

For more information on how to use function handles to define callback functions, see Create Callbacks for Graphics Objects.

Example: @myCallback

Example: {@myCallback,arg3}

Deletion callback, specified as one of these values:

Use this property to execute code when you delete the GraphPlot. MATLAB executes the callback before destroying the GraphPlot so that the callback can access its property values.

If you specify this callback using a function handle, then MATLAB passes two arguments to the callback function when executing the callback:

For more information on how to use function handles to define callback functions, see Create Callbacks for Graphics Objects.

Example: @myCallback

Example: {@myCallback,arg3}

Callback Execution Control

expand all

Callback queuing specified as 'queue' or 'cancel'. The BusyAction property determines how MATLAB handles the execution of interrupting callbacks.

Note

There are two callback states to consider:

Whenever MATLAB invokes a callback, that callback attempts to interrupt a running callback. TheInterruptible property of the object owning the running callback determines if interruption is allowed. If interruption is not allowed, then theBusyAction property of the object owning the interrupting callback determines if it is discarded or put in the queue.

If the ButtonDownFcn callback of the GraphPlot tries to interrupt a running callback that cannot be interrupted, then theBusyAction property determines if it is discarded or put in the queue. Specify the BusyAction property as one of these values:

Ability to capture mouse clicks, specified as one of these values:

This property is read-only.

Parent/Child

expand all

Parent of GraphPlot, specified as an axes, group, or transform object.

Visibility of GraphPlot object handle in theChildren property of the parent, specified as one of these values:

If the GraphPlot object is not listed in theChildren property of the parent, then functions that obtain object handles by searching the object hierarchy or querying handle properties cannot return it. This includes get, findobj, gca, gcf, gco, newplot, cla, clf, and close.

Hidden object handles are still valid. Set the rootShowHiddenHandles property to 'on' to list all object handles regardless of their HandleVisibility property setting.

Identifiers

expand all

This property is read-only.

Type of graphics object, returned as 'graphplot'. Use this property to find all objects of a given type within a plotting hierarchy, such as searching for the type using findobj.

Tag to associate with the GraphPlot, specified as a character vector. Tags provide a way to identify graphics objects. Use this property to find all objects with a specific tag within a plotting hierarchy, for example, searching for the tag using findobj.

Example: 'January Data'

Data Types: char

Data to associate with the GraphPlot object, specified as a scalar, vector, matrix, cell array, character array, table, or structure. MATLAB does not use this data.

To associate multiple sets of data or to attach a field name to the data, use thegetappdata and setappdata functions.

Example: 1:100

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | logical | char | struct | table | cell

Version History

Introduced in R2015b

expand all

Opt out of automatic color selection for GraphPlot objects by setting theSeriesIndex property to "none". When you specify"none", the GraphPlot object has a neutral color.

To enable automatic color selection again, set the SeriesIndex property to a positive whole number.

Control how GraphPlot objects vary in color by setting theSeriesIndex property. This property is useful when you want to match the colors of different objects in the axes.

Starting in R2020a, using the UIContextMenu property to assign a context menu to a graphics object or UI component is not recommended. Use theContextMenu property instead. The property values are the same.

There are no plans to remove support for the UIContextMenu property at this time. However, the UIContextMenu property no longer appears in the list returned by calling the get function on a graphics object or UI component.