Cursoring




Selecting the active trace


Simply click on the trace you wish to cursor. The cursor will move to the trace you clicked on and that trace will become active. The x and y-cursor edit boxes will change to the color of the new active trace and those edit boxes will be updated to contain the current x and y locations of the cursor. Although the color of the edit box will often be enough to let you know which trace is active it sometimes may be difficult to tell at a glance if there are many traces plotted. For this reason, a cursor ID tag is displayed just to the left of the y-cursor edit box. This will be especially helpful if you assigned meaningful trace names in the plt calling sequence. This cursor ID tag is also in the same color as the active trace.

Dragging the cursor

Click on a trace, hold down the mouse button, and drag the cursor left or right. The cursor will follow the mouse as you are dragging and the edit boxes will continually update with the current cursor location. Make sure you click directly on the trace. If you are not close enough to the trace when you click the mouse button, dragging the mouse will pan the display instead of moving the cursor. Once you start to drag the cursor, however, the cursor will follow the mouse x position even if the mouse moves far away from the line. This is the easiest and most natural way to move the cursor, and probably the only way you will use for small data sets. The other ways of moving the cursor (described below) become more attractive as the data set gets larger (perhaps over 500 points or so).

Typing in a cursor location

If you type a new value into the x-cursor edit box, the cursor will move to the ordered pair (x,y) on the active trace, where x is equal to, or as close as possible to the value you typed in. Likewise, if you type a new value into the y-cursor edit box, the cursor will move to the ordered pair (x,y) on the active trace, where y is equal to, or as close as possible to the value you typed in. In some cases, there may be more than one position on the active trace that meets the above condition. If that happens, the cursor will move to the first such position.

Clicking on the x-axis label

The advantage of this method is that it is very easy to move the cursor by the smallest amount possible (i.e. one data element) even when the data density is very high. Simply click on the x-axis label (for example "Milli-seconds" in the plot shown in the above Preliminaries section) and the cursor will move forward by one data element. And a right click will move in the reverse direction. This method is especially useful when the data order is not clear from the plot (unconnected markers for instance). If you are viewing the entire data set (i.e. the x axis is not zoomed in) then continuing to click after the cursor has reached the left or right edge will have no effect. However, if you are zoomed in, then the cursor will continue to move to the next data element beyond the edge of the display, but then the display will pan so that the cursor remains at the display edge.

A useful feature of the x-axis label is that if after the left or right click you hold down the mouse button, after a short delay (called the repeat delay) the cursor will continue to step left or right at the "repeat rate". When the x-axis is zoomed in, this provides a pleasing and smooth way to pan the display left or right. The default repeat rate is 0.03 seconds (i.e. 33Hz) but you like to pan slower or faster you can change the repeat rate. For example, to change the repeat rate to 0.01 seconds (i.e. 100Hz) use the command:

setappdata(findobj(gcf,'string','ABC'),'repeat',0.01)
(where "ABC" is the current x-axis label string).

The use of the 'repeat' application data property is explained more fully in the description of the edit pseudo object in the Pseudo objects section. You will see from that section that it is also possible to change the default repeat delay (which is 0.4 seconds)

The Cursor button group


In the lower-left corner of the display you will find these four cursor buttons.

The up and down arrow buttons on the left are the peak and valley finder buttons respectively. When you click on the ↑ button (peak finder), the cursor will move to the largest peak in the current display range of the active trace. The next click on the up arrow will move the cursor to the second-largest peak and so on. Moving the cursor by clicking on the trace or by using the cursor slider will reset the peak finder so that the next time you click on the up arrow the cursor again moves to the largest peak in the display range. An alternate way to reset the peak finder is to right click on the peak finder button. The ↓ button (valley finder) works the same as the peak finder except that the cursor moves to successive local minima.

Left clicking on the marker button (o) will toggle the line styles used for all traces in the figure (including subplots). The first click will change the style from lines to markers. The 2nd click will change the style to show both lines and markers, and the 3rd click will restore the traces to the original lines-only style.

Right clicking on the marker button will turn on the "lens" (magnifying) mode. To indicate that we are in lens mode, the button label "o" will become smaller. Right clicking on this button again will cancel the lens mode and the button label will return to its original size. To learn what the lens mode does read about the Lens mode in the zooming and pannings section.

Left clicking on the last button (Δ) enables the delta cursor mode (described below) while right clicking on the Δ button puts the figure into repositioning mode. In repositioning mode, all the figure elements will no longer perform their usual function but you will be able to drag the figure elements to new positions and sizes. The repositioning mode is described in more detail in several parts of the GUI building with plt section including here, here, and here

Delta cursors


Delta cursors are useful for measuring horizontal or vertical distances between two points on a trace. First, move the cursor to the desired reference point on the trace. Then press the Delta (∆) cursor button. The Delta button will turn black to indicate that we are in Delta cursor mode and the reference location will be marked with a large red plus (about 4 times bigger than the normal cursor). Next, click on a different point on the same trace (or drag the cursor to the desired location). The view will then look similar to the picture shown here. (You can also click on a point on a different trace -- the delta cursor will still work as expected.) You can read the current location of the cursor (the small yellow plus) in the usual way - i.e. the edit boxes just to the right of the grey x/y labels. In this case, the cursor x location is 88.0875 µseconds and the y location is 2.63571. The other two edit boxes show how far away the cursor is from the marked reference. In this example, it shows that the cursor at a location 30.0375 µseconds later than and 0.923871 units higher than the marked reference. Simply click on the delta cursor button again, and the reference mark will disappear, the delta cursor button returns to its normal color, and the usual cursor operation will return.

Average, RMS, Slope, & Distance readout


         

When you click on the cursor ID tag (Line 4 in this example) the ID tag changes to Avg and the edit box then shows the average y-value of all the points of the active trace that are within the current display x limits.

When you click on the ID tag a second time, the Avg changes to RMS, and the edit box then shows the rms value of the active trace. As with Avg, the rms calculation only includes points that are within the currently displayed x-axis limits. (In case you are not familiar with this commonly used form of averaging - rms stands for "root mean square" and is calculated by taking the square root of the average of the squares of the data values).

When you click on the ID tag a third time, the RMS changes  to y/x and the value in the y-cursor edit box changes to show the ratio of the y and x cursor values at the current cursor position (i.e. the slope of the line from the origin to the cursor). If delta cursors were enabled, an additional edit box appears to the right of the y-cursor edit box containing ΔY/ΔX, which is the slope of the line connecting the marked position to the current cursor. You can use this to estimate the slope of a trace at a particular point.

When you click on the ID tag a fourth time, the y/x changes  to √x2+y2 and the value in the y-cursor edit box changes to show distance from the origin to the cursor position (i.e. the magnitude of x+yi). If delta cursors were enabled, an additional edit box appears to the right of the y-cursor edit box showing the distance from the marked position to the current cursor position (i.e. the magnitude of ΔX+ΔYi).

Clicking the ID tag a fifth time (or clicking in the plot area) restores the cursor readout to show the usual Y value and the ID tag again shows the name of the cursored trace.

Dual cursor

The usual cursor can show the value of only one of the visible traces on the plot. With a dual cursor, two such values can be shown at the same time. This is especially useful when displaying two tightly linked values (for example, the magnitude and phase of a complex quantity). You specify a dual cursor for the Nth trace by including 'DualCur',N  in the parameter list. Then when you move the cursor, two y-value readouts are updated. The first one (the active trace) in the usual y value readout location (immediately to the right of the "y:" cursor label) and immediately to the right of that the second value (trace N) will appear. In the plot area, in addition to the normal cursor on the active trace, you will see the dual cursor on trace N (where N is the number specified as the DualCur argument). Just as with the regular cursor, the dual cursor will be shaped like a plus for a trace on the left axis or a circle for a trace on the right axis.

This example was created by including 'DualCur',5 in the parameter list so that the fifth trace (blue in this example) is always cursored along with the active trace. In this picture, Line 1 (green) has been selected as the active trace (by clicking on it) and so its y value is shown (also in green) in the usual y-readout location. As you move the active cursor back and forth along the x-axis, the dual cursor on trace 5 (the circle) tracks the back-and-forth movement so that it always remains vertically aligned with the main cursor on trace 1.

Instead of specifying a particular trace for the dual cursor, it is also possible to specify a particular offset so that the trace for the dual cursor can depend on which trace has the active cursor. For example, suppose I supplied the parameters 'DualCur',-4 . Then plt would add 4 to the line number associated with the active cursor and make that the dual cursor. (For example, if trace 3 was the active trace, trace 7 would be the dual trace.) If adding 4 pointed to a trace number larger than the number of defined traces, then the 4 would be subtracted from the active trace number to obtain the dual cursor trace.

Normally you set the DualCur parameter in the initial call to plt, however, if you can also interactively adjust this parameter by using the "Set dual cursor" submenu under the plt menu. The offset method of specifying the dual cursor (i.e. negative values of DualCur can't be selected using this submenu. (See details in the Menu Box section under the Menu Bar heading)

A complication happens when you are using the dual cursor and delta cursor features at the same time because the same auxiliary y readout location is used for both features. To resolve this conflict plt disables the dual cursor while delta cursors are being used.

The editz.m and afilt.m demo programs demonstrate the use of both the positive & negative DualCur parameter (respectively).

multiCursor

Usually, the single or dual cursors mentioned above are sufficient, but sometimes what you want is to cursor all the traces simultaneously. For the common situation where all the traces share the same x vector, the multiCursor shown to the right is effective. (If the x vectors for each trace are different, the multiCursor is unlikely to be very useful.)

To enable the multiCursor, first right-click on the y-cursor edit box, which will bring up the Yedit popup menu shown to the left. Then click on the 2nd menu item ("multiCursor") and a vertical line will appear on the plot at the current cursor location. Also, a circular marker will appear at all points where this vertical line crosses one of the traces. A string will also appear to the right of each of these markers showing the Y-value associated with the marker. All the methods of moving the cursor mentioned above will also move the multiCursor. If you want the multiCursor to follow the mouse as you drag it back and forth, you must first click on one of the traces (but not on the multiCursor) and then drag the mouse while holding down the mouse button.

The "multiCursor" menu item is a toggle, meaning that when you select it a second time the multiCursor will be disabled.

Usually, the multiCursor is enabled from the Yedit popup menu as shown above, however, if you wanted to the multiCursor to appear when your program starts up, you can include the string multiCur in the 'Options' parameter.

If you wanted to enable or disable the multiCursor from the command line or in a program use the command plt click Yedit 2; or its functional form plt('click','Yedit',2); (Equivalent to selecting the 2nd item in the popup shown above.)

The appearance of the multiCursor elements is probably suitable for most situations, but you can modify the appearance of the multiCursor by using the mcProps figure application data. This is best illustrated with an example. Suppose we follow the call to plt with the expression:

setappdata(gcf,'mcProps', ...
   {'|vis','off','+markersize',12, ...
    'fontsize',14,'tag',' \\leftarrow %4w'});

The cell array consists of property name/value pairs. The property names may have a prefix. So the first property ('visible') has the vertical bar prefix which signifies that the property should be applied to the vertical dotted line that is usually shown with the multiCursor. (So this name/value pair makes that dotted line invisible.) The next property ('markersize') has the plus sign prefix which indicates that this property should be applied to the markers. The next two properties (fontsize & tag) have no prefix and this indicates that the properties should be applied to the text objects associated with each marker. The tag property is a special case in that this is where the multiCursor formatting string is stored. So in this example, the text next to each marker will be a left arrow (tex character) followed by a four-character floating point string (using the w formatting code). One variation is that any of the values for the markers or text objects may be cell arrays. As an example, suppose there were 3 traces and you wanted the first trace to have a larger cursor text than the last two traces. Then you could replace the "14" above with {14;10;10}. Note that this cell array must be a column vector and its length must be equal to the number of traces.

If you need to read out values for all the traces at once but don't want the clutter of the many cursors on the plot, there are alternatives to the multiCursor. One of these is to bring up the "Cursor Data Window" by clicking on the Data tag in the MenuBox (described here). Yet another alternative is to make double use of the TraceID box to display cursor values as well as the TraceIDs. This can be using the 'Options','tidcuR' parameter which is described in the Options section. The fseries.m and pub2.m examples demonstrate how this can be done.

X-axis cursor slider


If the string 'Slider'  or 'S' appear in the 'Options' argument then this slider is inserted just below the cursor button group discussed above. The X-axis cursor slider has two different functions depending on whether the x axis has been expanded as follows:
The X axis is not expanded or is expanded by less than a factor of two. The X-axis cursor slider moves the cursor left or right by 1% of the data length when you click on the left or right slider arrows and left or right by 5% of the data length when you click in the trough area of the slider to the left or right of the slider button. The slider button itself is not used in this mode and remains fixed in the middle of the slider.
The X axis has been expanded by more than a factor of two The X-axis cursor slider makes it easy to quickly scroll through the data set or to pan to a particular location. Clicking on the left or right arrows moves the view window left or right by 10% of the visible range i.e. currently visible data will be scrolled out of view after 10 clicks. (Holding the mouse button down over these arrows results in a pleasing continuous scrolling effect.)  Clicking in the trough area to the left or right of the slider button moves the view window left or right by 100% of the visible range (i.e. currently visible data will be scrolled out of view for every click). Note that the slider button moves to show the relative position of the data currently in view. Also, you can do a quick pan by grabbing the slider button with the mouse and dragging it left or right. Dragging it as far as possible to the left or right causes the plot to pan to the beginning or end of the data and dragging it near the center of the slider pans the plot to show data near the middle of the data set. Note that all three panning methods (arrow, trough, button) keep the amount of data displayed constant (i.e. the difference between the upper and lower x-axis limits doesn't change). The data cursor is kept in the middle of the x-axis during this type of panning. (Note that in this situation the X-axis cursor slider performs a similar function as the xView slider described in the in the Zooming and panning section. Although the xView slider is more versatile in this role it does require some sacrifice in the vertical space available for the plot.)

Most of the cursor movement and display panning capabilities of this slider (as well as the xView slider) are also achieved using the x-axis label features described above. So you should experiment with these three methods to figure out which ones work best for any particular plot. One disadvantage of the x-axis label method over either of the slider methods is that without a dedicated graphical element for these functions, it's easy to forget that these panning and cursor movement capabilities exist.

Subplot cursors

Each subplot has its own cursor marker but the x-axis readout edit box is shared with the other subplots in the same column. The y-axis readout edit box is also shared with the other subplots in the same column when using the independent subplot mode. (In the linked mode, however, each cursor has its own y-axis edit box.) When using subplots the "Average, RMS, Slope, & Distance" modes mentioned above are not supported. Also, the following cursor features are supported only on the main (lower left) plot: As noted above, there are two subplot modes (set using the SubPlot parameter). With the linked mode, when you move a cursor, all the other cursors for subplots in the same column will move to the same x-axis location. (The cursors in other columns will not be affected.) Also when you change the x-axis limits of a plot (via any method including zooming and panning) then all the subplots in that column will be adjusted so they have the same x-axis limits. On the other hand, when using the independent mode, changing the cursor or axis limits in one subplot will never affect any of the other subplots.

Cursor data window

In addition to all the ways to extract data from a plot, there is one final method that is best when you want to see the values for all the traces at several x positions at once. To do this, simply click on the Data tag of the MenuBox and the cursor data window will appear. A complete description of this window and an example of what it looks like can be found in the Menu Box section.

Right-clicking on the y-axis label

When you right-click on the y-axis label, the menu box and all cursor objects disappear. This is useful for making screen captures of the plots since these objects are used for data exploration and are normally just a distraction in a hardcopy. Right-clicking again causes the objects to reappear. (The plt hideCur; command has the same effect.)

Right-clicking on the Cursor ID Tag


Left-clicking on the Cursor ID Tag has a quite different function described above, but right clicking on this tag is used when you would like to change the name of the currently selected trace. (The name that was specified in the TraceID parameter.) Granted, this need may be rare, but it is here if you need it.

After you have clicked on the trace that you want to change, its name will appear in the Cursor ID Tag. In this example the trace name is "err-constant" and we will change this name to "ErrorOffset". Click on the Y cursor edit box and enter the desired new name. It may be instinct to press "Enter" at this point but be careful not to do that.

Now right-click on Cursor ID Tag. As soon as you do this, you will see the name of the trace change, both in the Cursor ID Tag and in the TraceID box.