graphplot

Plot Markov chain directed graph

Syntax

graphplot(mc)

graphplot(mc,Name,Value)

graphplot(ax,___)

h = graphplot(___)

Description

graphplot(mc) creates a plot of the directed graph (digraph) of the discrete-time Markov chain mc. Nodes correspond to the states of mc. Directed edges correspond to nonzero transition probabilities in the transition matrix mc.P.

graphplot(mc,Name,Value) uses additional options specified by one or more name-value arguments. Options include highlighting transition probabilities, communicating classes, and specifying class properties of recurrence/transience and period. Also, you can plot the condensed digraph instead, with communicating classes as supernodes.

graphplot(ax,___) plots on the axes specified by ax instead of the current axes (gca) using any of the input argument combinations in the previous syntaxes. The option ax can precede any of the input argument combinations in the previous syntaxes.

h = graphplot(___) returns the handle to the digraph plot. Use h to modify properties of the plot after you create it.

Examples

Plot Digraph of Markov Chain

Consider this theoretical, right-stochastic transition matrix of a stochastic process.

$$P=\left[\begin{array}{ccccccc}0& 0& 1/2& 1/4& 1/4& 0& 0\\ 0& 0& 1/3& 0& 2/3& 0& 0\\ 0& 0& 0& 0& 0& 1/3& 2/3\\ 0& 0& 0& 0& 0& 1/2& 1/2\\ 0& 0& 0& 0& 0& 3/4& 1/4\\ 1/2& 1/2& 0& 0& 0& 0& 0\\ 1/4& 3/4& 0& 0& 0& 0& 0\end{array}\right].$$

Create the Markov chain that is characterized by the transition matrix P.

P = [ 0   0  1/2 1/4 1/4  0   0 ;
      0   0  1/3  0  2/3  0   0 ;
      0   0   0   0   0  1/3 2/3;
      0   0   0   0   0  1/2 1/2;
      0   0   0   0   0  3/4 1/4;
     1/2 1/2  0   0   0   0   0 ;
     1/4 3/4  0   0   0   0   0 ];
mc = dtmc(P);

Plot a directed graph of the Markov chain.

figure;
graphplot(mc);

Identify Communicating Classes in Digraph

Consider this theoretical, right-stochastic transition matrix of a stochastic process.

$$P=\left[\begin{array}{cccc}0.5& 0.5& 0& 0\\ 0.5& 0& 0.5& 0\\ 0& 0& 0& 1\\ 0& 0& 1& 0\end{array}\right].$$

Create the Markov chain that is characterized by the transition matrix P. Name the states Regime 1 through Regime 4.

P = [0.5 0.5 0 0; 0.5 0 0.5 0; 0 0 0 1; 0 0 1 0];
mc = dtmc(P,'StateNames',["Regime 1" "Regime 2" "Regime 3" "Regime 4"]);

Plot a directed graph of the Markov chain. Identify the communicating classes in the digraph and color the edges according to the probability of transition.

figure;
graphplot(mc,'ColorNodes',true,'ColorEdges',true)

States 3 and 4 compose a communicating class with period 2. States 1 and 2 are transient.

Suppress State Labels

Create a "dumbbell" Markov chain containing 10 states in each "weight" and three states in the "bar."

• Specify random transition probabilities between states within each weight.

• If the Markov chain reaches the state in a weight that is closest to the bar, then specify a high probability of transitioning to the bar.

• Specify uniform transitions between states in the bar.

rng(1); % For reproducibility
w = 10;                              % Dumbbell weights
DBar = [0 1 0; 1 0 1; 0 1 0];        % Dumbbell bar
DB = blkdiag(rand(w),DBar,rand(w));  % Transition matrix

% Connect dumbbell weights and bar
DB(w,w+1) = 1;                       
DB(w+1,w) = 1; 
DB(w+3,w+4) = 1; 
DB(w+4,w+3) = 1;

db = dtmc(DB);

Plot a directed graph of the Markov chain. Return the plot handle.

figure;
h = graphplot(db);

Observe that the state labels are difficult to read. Remove the labels entirely.

h.NodeLabel = {};

Input Arguments

mc — Discrete-time Markov chain

dtmc object

Discrete-time Markov chain with NumStates states and transition matrix P, specified as a dtmc object. P must be fully specified (no NaN entries).

ax — Axes on which to plot

Axes object

Axes on which to plot, specified as an Axes object.

By default, graphplot plots to the current axes (gca).

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: 'ColorEdges',true,'ColorNodes',true colors the edges to indicate transition probabilities and colors the nodes based on their communicating class.

LabelNodes — Flag for labeling nodes using state names

true (default) | false

Flag for labeling nodes using state names, specified as the comma-separated pair consisting of 'LabelNodes' and a value in this table.

Value	Description
true	Label nodes using the names in mc.StateNames.
false	Label nodes using state numbers.

Example: 'LabelNodes',false

Data Types: logical

ColorNodes — Flag for coloring nodes based on communicating class

false (default) | true

Flag for coloring nodes based on communicating class, specified as the comma-separated pair consisting of 'ColorNodes' and a value in this table.

Value	Description
true	Nodes in the same communicating class have the same color. Solid markers represent nodes in recurrent classes, and hollow markers represent nodes in transient classes. The legend contains the periodicity of recurrent classes.
false	All nodes have the same color.

Example: 'ColorNodes',true

Data Types: logical

LabelEdges — Flag for labeling edges with transition probabilities

false (default) | true

Flag for labeling edges with the transition probabilities in the transition matrix mc.P, specified as the comma-separated pair consisting of 'LabelEdges' and a value in this table.

Value	Description
true	Label edges with transition probabilities rounded to two decimal places.
false	Do not label edges.

Example: 'LabelEdges',true

Data Types: logical

ColorEdges — Flag for coloring edges to indicate transition probabilities

false (default) | true

Flag for coloring edges to indicate transition probabilities, specified as the comma-separated pair consisting of 'ColorEdges' and a value in this table.

Value	Description
true	Color edges to indicate transition probabilities. Include a color bar, which summarizes the color coding.
false	Use the same color for all edges.

Example: 'ColorEdges',true

Data Types: logical

Condense — Flag for condensing the graph

false (default) | true

Flag for condensing the graph, with each communicating class represented by a single supernode, specified as the comma-separated pair consisting of 'Condense' and a value in this table.

Value	Description
true	Nodes are supernodes containing communicating classes. Node labels list the component states of each supernode. An edge from supernode i to supernode j indicates a nonzero probability of transition from some state in supernode i to some state in supernode j. Transition probabilities between supernodes are not well defined, and graphplot disables edge information.
false	Nodes are states in mc.

Example: 'Condense',true

Data Types: logical

Output Arguments

h — Handle to graph plot

graphics object

Handle to the graph plot, returned as a graphics object. h is a unique identifier, which you can use to query or modify properties of the plot.

Tips

• To produce the directed graph as a MATLAB^® digraph object and use additional functions of that object, enter:

  G = digraph(mc.P)

• For readability, the 'LabelNodes' name-value pair argument allows you to turn off lengthy node labels and replace them with node numbers. To remove node labels completely, set h.NodeLabel = {};.

• To compute node information on communicating classes and their properties, use classify.

• To extract a communicating class in the graph, use subchain.

• The condensed graph is useful for:

  • Identifying transient classes (supernodes with positive outdegree)

  • Identifying recurrent classes (supernodes with zero outdegree)

  • Visualizing the overall structure of unichains (chains with a single recurrent class and any transient classes that transition into it)

References

[1] Gallager, R.G. Stochastic Processes: Theory for Applications. Cambridge, UK: Cambridge University Press, 2013.

[2] Horn, R., and C. R. Johnson. Matrix Analysis. Cambridge, UK: Cambridge University Press, 1985.

[3] Jarvis, J. P., and D. R. Shier. "Graph-Theoretic Analysis of Finite Markov Chains." In Applied Mathematical Modeling: A Multidisciplinary Approach. Boca Raton: CRC Press, 2000.

Version History

Introduced in R2017b