Documentation Center

  • Trial Software
  • Product Updates

Making Graphs Responsive with Data Linking

What Is Data Linking?

Linked plots are graphs in figure windows that visibly respond to changes in the current workspace variables they display and vice versa. This differs from the default behavior of graphs, which contain copies of variables they represent (their XData/YData/ZData) and must be explicitly replotted in order to update them when a displayed variable changes. For example, if variable y in the workspace appears in a linked plot and y is modified in the Command Window, the graphic representation of y in the linked plot updates within half a second to reflect the change.

If you use the Variables editor, you might be familiar with data linking. When variables change or go out of scope, the Variables editor updates itself. It continuously updates variables in the workspace when you add, change, or delete values. The Variables editor works the same way with linked plots.

You can programmatically update a plot after the elements in one variable change. For example, the following code calls refreshdata to update the plot after y changes.

x = 0:.1:8*pi;
y = sin(x);
h = plot(x,y)
set(h,'XDataSource','x');
set(h,'YDataSource','y');
y = sin(x.^3);
refreshdata

For more information on this manual technique, see the refreshdata reference page and Linking Graphs to Variables — Data Source Properties. Prior to data linking, you need to explicitly update your plots to reflect changes in your workspace variables, as illustrated in Linking vs. Refreshing Plots.

Why Use Linked Plots?

If the same variable appears in plots in multiple figures, you can link any of the plots to the variable. You can use linked plots in concert with Marking Up Graphs with Data Brushing, but also on their own. Linking plots lets you

  • Make graphs respond to changes in variables in the base workspace or within a function

  • Make graphs respond when you change variables in the Variables editor and Command Line

  • Modify variables through data brushing that affect different graphical representations of them at once

  • Create graphical "watch windows" for debugging purposes

Watch windows are useful if you program in the MATLAB® language. For example, when refining a data processing algorithm to step through your code, you can see graphs respond to changes in variables as a function executes statements.

How to Link Plots

When you create a figure, by default, data linking is off. You can put a figure into a linked state in any of three ways:

  • Click the Data Linking tool button on the figure toolbar.

  • Select Link from the figure Tools menu.

  • Call the linkdata MATLAB function, e.g., linkdata on.

  • To disable data linking, click the Data Linking tool button, deselect Tools > Link, or type linkdata off.

Once a figure is linked, its appearance changes; an information bar, called the Linked Plot information bar, appears beneath the figure toolbar to reflect its new linked state. It identifies all linked variables and gives you an opportunity to unlink or relink any of them. The information bar looks like this.

The linked plot information bar identifies a figure as being linked and displays relationships between graphic objects and the workspace variables they represent. Click the circular down arrow icon on its left side to display a legend that identifies the data source for each graphic object in a graph, as in the following example.

Dropping down the linked plot legend is useful when many data sources are linked to a graph at once. Like legends created with the legend function, it identifies graph components with variable expressions.

How Linked Plots Behave

Once linked to its data source(s), a figure acts as if you called the MATLAB function refreshdata every time a workspace variable it displays changes. That is, any series or group graphic objects contained in the figure can update its own XData, YData, or ZData properties and redraw itself when one of its data sources is modified. If the linked state is set to 'off' using the linkdata function, by deselecting the Data Linking toolbar button, or by deselecting Link on the figure's Tools menu, automatic refreshing stops.

When you turn linking on for a figure, the linking mechanism can usually identify the data sources for displayed graphs, but sometimes ambiguity exists about what variable or range of a variable has been plotted. At such times, the Linked Plot information bar informs you that graphics have no data sources and gives you a chance to identify them, as you can see here.

Click fix it to open a dialog box where you can specify the variables and ranges of any or all plotted variables, shown in the following image for a 3-D scatter plot.

In the Specify Data Source Properties dialog box, choose a source for XData, YData, and/or ZData from drop-down menus or type an expression. For 2-D plots, usually you must specify at least YData and for 3-D plots, ZData. In the next image, the expressions popdata(1:end-1,17), popdata(1:end-1,18), and popdata(1:end-1,19) are typed in, in order to identify the appropriate columns and to exclude the final row of the data matrix from the plot. The DisplayName property (used by the legend function) is also set to 'Pct Urban'.

    Tip   Save time by using the drop-down lists to select data sources unless you need to specify ranges of data or other expressions.

    Note:   You can create graphs that have no data sources. For example, plot(randn(100,1)) generates a line graph that has neither an XDataSource (the x-values are implicit) nor a YDataSource (no variable for y-values exists). Therefore, while you can brush such graphs, you cannot link them to data sources, because linking requires workspace data. Similarly, if you create a variable, graph it, and then clear the variable from the workspace you will be unable to link that plot.

When you brush a graph that is not linked to data sources, you brush the graphics only. The brushing affects only the figure you interact with. However, when you brush a linked plot, you are brushing the underlying variables. In this case, your brush marks also display on all linked plots that have the same data sources you brushed, as well as any display of that data which you have opened in the Variables editor. The color of the brush marks in all displays is the brush color you have selected for the figure in which you are brushing. This color can differ from the brush colors you have chosen to use in others display, and overrides those colors.

Linking vs. Refreshing Plots

Besides the linked plots feature, other MATLAB mechanisms connect graphic objects to data sources (workspace variables). The main techniques are:

  • Directly update the XData/YData/ZData properties of a graph.

  • Set a graph's XDataSource/YDataSource/ZDataSource and indirectly update XData/YData/ZData by calling refreshdata.

For an example of using these techniques to animate graphs, see Updating Plot Object Axis and Color Data in the MATLAB Graphics documentation. That section explains that data linking is not a method intended for animating data graphs.

Linking plots automates these tasks and keeps graphs continuously in sync with the variables they depict, making it the easiest technique to use. Data sources must still exist in the workspace, but you do not need to explicitly declare them for linked plots unless some ambiguity exists. The following code examples iteratively approximate pi, and illustrate the difference between declaring and refreshing data sources yourself and letting the linkdata function handle it for you.

Updating a Graph with refreshdataUpdating a Graph with linkdata
x1= [1 2];
y1 = [4 4];
ntimes = 100;
denom = 1;
k = -1;
subplot(1,2,1)
hp1 = plot(x1,y1);
xlabel('Updated with REFRESHDATA')
ylabel('\pi')
set(gca,'Xlim',[0 ntimes],...
        'Ylim',[2.5 4])
set(hp1,'XDataSource', 'x1')
set(hp1,'YDataSource', 'y1')
for t = 3:ntimes
    denom = denom + 2;
    x1(t) = t;
    y1(t) = 4*(y1(t-1)/4 + k/denom);
    refreshdata
    drawnow
    k = -k;
end
line([0 ntimes], [pi pi],'color','c')
x2= [1 2];
y2 = [4 4];
ntimes = 100;
denom = 1;
k = -1;
subplot(1,2,2)
plot(x2,y2);
xlabel('Updated with LINKDATA')
ylabel('\pi')
set(gca,'Xlim',[0 ntimes],...
        'Ylim',[2.5 4])
linkdata on
for t = 3:ntimes
    denom = denom + 2;
    x2(t) = t;
    y2(t) = 4*(y2(t-1)/4 + k/denom);
    k = -k;
end
line([0 ntimes], [pi pi],'color','c')

Differences are shown in italics. When you execute the code on the left, which uses refreshdata, it animates the approximation process. The code on the right uses linkdata and does not animate; it runs much faster. (A drawnow command is not needed, because data linking buffers update and refresh the graph at half-second intervals.) The graphic results, shown in the next image, are identical. Because both plots are in axes in the same figure, linking the second graph also links the first graph to its variables.

Using Linked Plot Controls

To minimize the Linked Plot information bar while remaining in linked mode, click the hide/show button on its right side; the button flips direction and the bar is hidden. Clicking the button again flips the arrow back and restores the Linked Plot information bar. Turning off linking cuts all data source connections and removes the Linked Plot information bar from the figure. However, the data source properties remain set, and the bar reappears whenever a linked state is restored by selecting Tools > Link, depressing the Linked Plot button, or calling the linkdata function. Whatever data sources were established previously will then reconnect (assuming those variables still exist in the same form).

The Data Source Button

The down arrow button on the left side of the Linked Plot information bar drops down a legend (similar to what the legend function produces but without Display Names). The legend identifies workspace variables associated with plot objects for the entire figure (legend works on a per-axes basis), such as these linked lineseries from the previous example, shown in the next image.

The drop-down legend names variable linked to the graphic objects in the figure. For items to appear there, a graph must have an XDataSource, YDataSource, or a ZDataSource property that MATLAB can evaluate without error. The icon for each list entry reflects the Color, Linestyle and Marker of the corresponding graphic object, making clear which graphic objects link to which variables. The drop-down legend is informational only; you can only dismiss it after reading it by clicking anywhere else on the figure.

The Edit Button

Clicking the Edit link on the information bar opens the Specify Data Source Properties modal dialog box for you to set the DisplayName, XDataSource, YDataSource, and ZDataSource properties of plot objects in the figure to columns or vectors of workspace variables. Changing a DisplayName updates text on a legend, if present for the variable, and has no other effects. The three columns on the right contain drop-down lists of workspace variables. You can also type variable names and ranges, or a MATLAB expression. When you change variables or their ranges on the fly with this dialog box, variables plotted against one another must be compatible types and have the same number of observations (as in any bivariate graph).

If you attempt to link a plot and linkdata can identify more than one possible workspace variable for one or more plot objects, the Specify Data Source Properties dialog box appears for you to resolve the ambiguity. If you choose not to or are unable to do so and cancel the dialog box, data linking is not established for those graphic objects.

When Data Links Fail

Updating a linked plot can fail if the strings in the XDataSource, YDataSource, or ZDataSource properties are incompatible with what is in the current workspace. Consequently, the corresponding XData, YData, and ZData cannot be updated. This happens most often because variables are cleared or no longer exist when the workspace changes (e.g., when you are debugging).

However, failing links do not affect the visual appearance of the object in the graph. Instead, a warning icon and message appears on the Linked Plot information bar when this occurs for any plotted data in the figure. The failing link warning is general, but you can identify which variables are affected by clicking the Data Source button. If you hide the Linked Plot information bar (by clicking its Hide button), the bar reappears when a data links fails, alerting you to the issue.

Was this topic helpful?