Positioning Annotations in Data Space :: Annotating Graphs (MATLAB®)

Learn more about MATLAB

Positioning Annotations in Data Space

Example — Pinning Text Arrows and Ellipses

Annotation objects (arrow, doublearrow, textarrow, ellipse, line, rectangle, and textbox) are attached to figures rather than to axes. By default, they have normalized figure coordinates when first created. For information about figure coordinates, see Positioning Figures. Although this enables you to place annotation objects anywhere within a figure, it also makes it difficult to precisely locate them on graphs so that they relate to data space coordinates (the x,y units of plotted data). You can position annotations in data space by transforming the data space coordinates to normalized figure coordinates. This example shows how to do this using a function called dsxy2figxy, which is an M-file that accompanies this documentation. (It is not a MATLAB function.) You specify data space coordinates that an annotation object should occupy as arguments to the function. The function returns the figure coordinates where the annotation should be placed.

Make the function dsxy2figxy available to you in one of the following ways:
- Click here to open function dsxy2figxy in the MATLAB editor, and then save it to your current folder or elsewhere on the MATLAB path.
- Execute the following command to add the folder where function dsxy2figxy is stored to the MATLAB path.
```
addpath([docroot '/techdoc/creating_plots/examples'])
```

Create sine function data and make a line plot of it:

x1 = 1:.1:4*pi;
y1 = sin(x1)./sqrt(x1);
figure
plot(x1,y1)
axis tight

Interactively place a text arrow on the graph with ginput, which places a cross-hair cursor on the axes for users to select point locations. This function returns x,y coordinate pairs in data space.

You can use ginput to interactively locate a text arrow annotation. When called as follows, it accepts two clicks before exiting:

disp('Click graph to place arrow; first tail, then head:')
[axx axy] = ginput(2);   % Returns list of x, list of y in data space
% Transform from data space to figure space
[arrowx,arrowy] = dsxy2figxy(gca, axx, axy);
har = annotation('textarrow',arrowx,arrowy);
content = sprintf('(%4.2f,%4.2f)',axx(2), axy(2));
% Plot anno text centered at the tail of the arrow
set(har,'String',content,'Fontsize',8)

Now place an ellipse on the axes

To place ellipses, you need a coordinate box (position rectangle) instead of two x,y tuples. The function dsxy2figxy computes and returns a position rectangle if it is called with one:

disp('Click in the axes to define the bounding box of an ellipse:')
[axx axy] = ginput(2);      % Returns list of x, list of y in data space
abox(1) = min(axx); abox(2) = min(axy);     % Get minimum x and y coords
abox(3) = abs(axx(1)-axx(2));               % Get box width
abox(4) = abs(axy(1)-axy(2));               % Get box height
% Transform from data space to figure space
[bbox] = dsxy2figxy(gca, abox);
% Plot the ellipse where you clicked
annotation('ellipse',bbox);

Here is the M-help for dsxy2figxy.

  dsxy2figxy -- Transform point or position from data space 
  coordinates into normalized figure coordinates 
  Transforms [x y] or [x y width height] vectors from data space
  coordinates to normalized figure coordinates in order to locate
  annotation objects within a figure. These objects are: arrow,
  doublearrow, textarrow, ellipse, line, rectangle, textbox 
 
  Syntax:
     [figx figy] = dsxy2figxy([x1 y1],[x2 y2])  % GCA is used
     figpos      = dsxy2figxy([x1 y1 width height])
     [figx figy] = dsxy2figxy(axes_handle, [x1 y1],[x2 y2])
     figpos      = dsxy2figxy(axes_handle, [x1 y1 width height])
 
  Usage: Obtain a position on a plot in data space and  
         apply this function to locate an annotation there, e.g., 
    [axx axy] = ginput(2); (input is in data space)
    [figx figy] = dsxy2figxy(gca, axx, axy);  (now in figure space)
    har = annotation('textarrow',figx,figy); 
    set(har,'String',['(' num2str(axx(2)) ',' num2str(axy(2)) ')']) 
 
    Copyright 2006-2009 The MathWorks, Inc.

If you resize the figure, the annotations can change shape but continue to point to the same locations on the graph. This is because they and the figure use normalized coordinates. However, if you shift the axes up, down, left, or right within the figure—as you can in plot edit mode—the annotations remain fixed in figure space and do not move with the axes. The following section explains how to ensure that annotations stay connected to the data with which you have associated them.

Anchoring Annotations to Data Points

To enable annotations to remain anchored when you reposition axes (for example, when panning across the axes), you can manually pin them to locations on data graphs:

Enter plot edit mode by pushing the arrow button on the figure toolbar.
Click the arrow you placed on the graph to select it.
Right-click the arrow and choose Pin to axes from the context menu.

The black handles of the arrow become hollow to indicate that the object has been pinned.
Now when you change the position or shape of the axes, the arrow remains attached to the graph, but the oval does not.

The result of pinning annotations manually is functionally the same as computing locations for them in data space, except it requires user interaction and registers the annotation to the axes instead of to the figure. For more information, see Pinning the Arrowhead End, Pinning Rectangles and Ellipses, and Pinning the Textbox.

Adding Arrows and Lines to Graphs

Basic Plotting Commands

Recommended Products

Get MATLAB trial software

Includes the most popular MATLAB recorded presentations with Q&A sessions led by MATLAB experts.

Get the Interactive Kit