Quantcast

Documentation Center

  • Trial Software
  • Product Updates

linkdata

Automatically update graphs when variables change

Syntax

linkdata on
linkdata off
linkdata
linkdata(figure_handle,...)
linkobj = linkdata(figure_handle)

Description

linkdata on turns on data linking for the current figure.

linkdata off turns data linking off.

linkdata by itself toggles the state of data linking.

linkdata(figure_handle,...) applies the function to the specified figure handle.

linkobj = linkdata(figure_handle) returns a linkdata object for the specified figure. The object has one read-only property, Enable, the string 'on' or 'off', depending on the linked state of the figure.

Data linking connects graphs in figure windows to variables in the base or a function's workspace via their XDataSource, YDataSource, and ZDataSource properties. When you turn on data linking for a figure, MATLAB® compares variables in the current (base or function caller) workspace with the XData, YData, and ZData properties of graphs in the affected figure to try to match them. When a match is found, the appropriate XDataSource, YDataSource and/or ZDataSource for the graph are set to strings that name the matching variables.

Any subsequent changes to linked variables are reflected in graphs that use them as data sources and in the Variables editor, if the linked variables are displayed there. Conversely, any changes to plotted data values made at the command line, in the Variables editor, or with the Brush tool (such as deleting or replacing data points), are immediately reflected in the workspace variables linked to the data points.

When a figure containing graphs is linked and any variable identified as XDataSource, YDataSource, and/or ZDataSource changes its values in the workspace, all graphs displaying it in that and other linked figures automatically update. This operation is equivalent to automatically calling the refreshdata function on the corresponding figure when a variable changes.

Linked figure windows identify themselves by the appearance of the Linked Plot information bar at the top of the window. When linkdata is off for a figure, the Linked Plot information bar is removed. If linkdata cannot unambiguously identify data sources for a graph in a linked figure, it reports this via the Linked Plot information bar, which gives the user an opportunity to identify data sources. The information bar displays a warning icon and a message, No graphics have data sources and also prompts fix it. Clicking fix it opens the Specify Data Source Properties dialog box for identifying variable names and ranges of data sources used in the graph.

Examples

Example 1

Create two variables, graph them as areaseries, and link the plot to them:

x = 1:20;
y = rand(20,3);
area(x,y)
linkdata on

Change values for linked variable y in the workspace:

y(10,:) = 0;

The area graph immediately updates.

Example 2

Delete a figure if it is not linked, based on a returned linkdata object:

fig = figure;
ld = linkdata(fig)
ld = 
     graphics.linkdata

if strcmp(ld.Enable,'off')
    delete(fig)
end

Example 3

If a graphing function can display a complex variable, you can link such plots. To do so, you need to describe the data sources as expressions to separate the real and imaginary parts of the variable. For example,

x = eig(randn(20,20));
whos
  Name       Size      Bytes  Class     Attributes
  x         20x1         320  double    complex   

yields a complex vector. You can use plot to display the real portion as x and the imaginary portion as y, then link the graph to the variable:

plot(x)
linkdata

However, linkdata cannot unambiguously identify the graph's data sources, and you must tell it by typing real(x) and imag(x) into the Specify Data Source Properties dialog box that displays when you click fix it in the Linked Plot information bar.

To avoid having to type the data source names in the dialog box, you can specify them when you plot:

plot(x,'XDataSource','real(x)','YDataSource','imag(x)')

If you subsequently change values of x programmatically or manually, the plot updates accordingly.

    Note:   Although you can use data brushing on linked plots of complex data, your brush marks only appear in the plot you are brushing, not in other plots or in the Variables editor. This is because function calls, such as real(x) and imag(x), that you specify as data sources are not interpreted when brushing graphed data.

More About

expand all

Tips

Types of Variables You Can Link

You can use linkdata to connect a graph with scalar, vector and matrix numeric variables of any class (including complex, if the graphing function can plot it) — essentially any data for which isnumeric equals true. See Example 3 for instructions on linking complex variables. You can also link plots to numeric fields within structures. You can specify MATLAB expressions as data sources, for example, sqrt(y)+1.

Restoring Links that Break

Refreshing data on a linked plot fails if the strings in the XDataSource, YDataSource, or ZDataSource properties, when evaluated, are incompatible with what is in the current workspace, such that the corresponding XData, YData, or ZData are unable to respond. The visual appearance of the object in the graph is not affected by such failures, so graphic objects show no indication of broken links. Instead, a warning icon and the message Failing links appear on the Linked Plot information bar along with an Edit button that opens the Specify Data Sources dialog box.

Linking Rapidly Changing Data

linkdata buffers updates to data and dispatches them to plots at roughly half-second intervals. This makes data linking not suitable for smoothly animating changes in data values unless they are updated in loops that are forced to execute two times per second or less.

One consequence of buffering link updates is that linkdata might not detect changes in data streams it monitors. If you are running a function that uses assignin or evalin to update workspace variables, linkdata can sometimes fail to process updates that change values but not the size and class of workspace variables. Such failures only happen when the function itself updates the plot.

Linking Brushed Graphs

If you link data sources to graphs that have been brushed, their brushing marks can change or vanish. This is because the workspace variables in those graphs now dictate which, if any, observations are brushed, superseding any brushing annotations that were applied to their graphical data (YData, etc.). For more details, see How Data Linking Affects Data Brushing in the brush reference page.

See Also

| | |

Was this topic helpful?