MATLAB®

Data Cursor — Displaying Data Values Interactively

What Is a Data Cursor?

Data cursors enable you to read data directly from a graph by displaying the values of points you select on plotted lines, surfaces, images, and so on. You can place multiple datatips in a plot and move them interactively. If you save the figure, the datatips in it are saved, along with any other annotations present.

When data cursor mode is enabled, you can

• Click on any graphics object defined by data values and display the x, y, and z (if 3-D) values of the nearest data point.

• Interpolate the values of points between data points.

• Display multiple data tips on graphs.

• Display the data values in a cursor window that you can locate anywhere in the figure window or as a data tip (small text box) located next to the data point.

• Export data values as workspace variables.

• Print or export the graph with data tip or cursor window displayed for annotation purposes.

• Edit the data tip display function to customize what information is displayed and how it is presented

• Select a different data tip display function

Back to Top

Enabling Data Cursor Mode

Select the data cursor icon in the figure toolbar or select the Data Cursor item in the Tools menu.

Once you have enabled data cursor mode, clicking the mouse on a line or other graph object displays data values of the point clicked. Clicking elsewhere does not create or update data tips. To place additional data tips, as the picture below shows, see Creating Multiple Data Tips, below. In the picture, the black squares are located at points selected by the Data Cursor tool, and the data tips next to them display the x and y-values of those points.

The illustrations below use traffic count data stored in count.dat:

load count.dat
plot(count)

Moving the Marker

You can move the marker using the arrow keys and the mouse. The up and right arrows move the marker to data points having greater index values in the data arrays. The down and left arrow keys move the marker to data points having lesser index values. When you set Selection Style to Mouse Position using the tool's context menu, you can drag markers and position them anywhere along a line. However, you cannot drag markers between different line or other series on a plot. The cursor changes to crossed arrows when it comes close enough to a marker for you to drag the datatip, as shown below:

Positioning the Datatip Text Box

You can position the data tip text box in any one of four positions with respect to the data point: upper right (the default), upper left, lower left, and lower right.

To position the datatip, press, but do not release the mouse button while over the datatip text box and drag it to one of the four positions, as shown below:

You can reposition a datatip, but not its text box, using the arrow keys as well.

Dragging the Datatip to Different Locations

You can drag the datatip to different locations on the graph object by clicking down on the datatip and dragging the mouse. You can also use the arrow keys to move the datatip.

Note   Surface plots and 3-D bar graphs can contain NaN values. If you drag a datatip to a location coded as NaN, the datatip will disappear (because its coordinates become (NaN,NaN,NaN)). You can continue to drag it invisibly, however, and it will reappear when it is over a non-NaN location. However, if you create a new datatip while the previous current one is invisible, the previous one cannot be retrieved.

Datatips on Image Objects

Datatips on images display the x- and y-coordinates as well as the RGB values and a color index (for indexed images), as show below:

Datatips on 3-D Objects

You can use datatips to read data points on 3-D graphs as well. In 3-D views, data tips display the x-, y- and z-coordinates.

Creating Multiple Data Tips

Normally, there is only one datatip displayed at one time. However, you can display multiple datatips simultaneously on a graph. This is a simple way to annotate a number of points on a graph.

Use the following procedure to create multiple datatips.

1. Enable data cursor mode from the figure toolbar. The cursor changes to a cross.

2. Click on the graph to insert a datatip.

3. Right-click to display the context menu. Select Create New Datatip.

   

4. Click on the graph to place the second datatip.

   

Deleting Datatips

You can remove the most recently added datatip or all datatips. When in data cursor mode, right-click to display the context menu.

• Select Delete Current Datatip or press the Delete key to remove the last datatip that you added.

• Select Delete All Datatips to remove all datatips.

Customizing Data Cursor Text

You can customize the text displayed by the data cursor using the datacursormode function. Use the last two items in the Data Cursor context menu to for this purpose:

• Edit Text Update Function — Opens an editor window to let you modify the function currently being used to place text in datatips

• Select Text Update Function — Opens an input file dialog for you to navigate to and select an M-file to use to format text in datatips you subsequently create

When you select Edit Text Update Function for the first time, an editor window opens with the default text update callback, which consists of the following code:

function output_txt = myfunction(obj,event_obj)
% Display the position of the data cursor
% obj          Currently not used (empty)
% event_obj    Handle to event object
% output_txt   Data cursor text string (string or cell array of strings).

pos = get(event_obj,'Position');
output_txt = {['X: ',num2str(pos(1),4)],...
    ['Y: ',num2str(pos(2),4)]};

% If there is a Z-coordinate in the position, display it as well
if length(pos) > 2
    output_txt{end+1} = ['Z: ',num2str(pos(3),4)];
end

You can modify this code to display properties of the graphics object other than position. If you want to do so, you should first save this code to an M-file before changing it, and select that file if you want to revert to default datatip displays during the same session.

If for example you save it as def_datatip_cb.m, and then modify the code and save it to another M-file, you can then choose between the default behavior and customized behavior by choosing Select Text Update Function from the context menu and selecting one of the callbacks you saved.

See the Examples section of the datacursormode reference page for more information on using data cursor objects and update functions. Also see the example of customizing datatip text in Using Datatips to Explore Graphs in the MATLAB^® Data Analysis documentation.

Back to Top

Display Style — Datatip or Cursor Window

By default, the data cursor displays values as a datatip (small text box located next to the data point). You can also display a single data value in a cursor window that is anchored within the figure window. You can place multiple datatips on a graph, which makes this display style useful for annotations.

The cursor window style is particularly useful when you want to drag the data cursor to explore image and surface data; numeric information in the window updates without obscuring the any of the figure's symbology.

To use the cursor window, change the display style as follows:

1. While in data cursor mode, right-click to display the context menu.

2. Mouse over the Display Style item.

3. Select Window Inside Figure.

   

   Note   If you change the data cursor Display Style from Datatip to Window Inside Figure with the context menu, only the most recent data tip is displayed; all other existing data tips are removed because the window can display only one datatip at a time.

Back to Top

Selection Style — Select Data Points or Interpolate Points on Graph

By default, the data cursor displays the values of the data point nearest to the point you click with the mouse, and the data marker snaps to this point. The data cursor can also determine the values of points that lie in between the data defining the graph, by linearly interpolating between the two data points closest to the location you click the mouse.

Enabling Interpolation Mode

If you want to be able to select any point along a graph and display its value, use the following procedure:

1. While in data cursor mode, right-click to display the context menu.

2. Mouse over the Selection Style item.

3. Select Mouse Position.

   

Note that interpolation mode is not honored when you are using the arrow keys to move a datatip to a new location.

Back to Top

Exporting Data Value to Workspace Variable

You can export the values displayed with the data cursor to MATLAB workspace variables. To do this, display the right-click context menu while in data cursor mode and select Export Cursor Data to Workspace.

The Export Cursor Data to Workspace dialog then displays for you to name the workspace variable.

Clicking OK creates a MATLAB structure with the specified name in your base workspace, containing the following fields:

• Target — Handle of the graphics object containing the data point

• Position — x- and y- (and z-) coordinates of the data cursor location in axes data units

Line and lineseries objects have an additional field:

• DataIndex — A scalar index into the data arrays that correspond to the nearest data point. The value is the same for each array.

For example, if you saved the workspace variable as cursor_info, then you would access the position data by referencing the Position field.

cursor_info.Position
ans =
    0.4189 	0.1746 	0

Back to Top

Ways to Explore Graphical Data

Enlarging the View