Data editing

plt has the capability to modify the plotted data, either one point at a time or over a specified range. If your data was plotted as an intensity map using the image pseudo object, use the methods described in the second section below (3d data editing). Otherwise use the methods described in the first section (2d data editing).

2d data editing

Data entry is accomplished by entering the coordinates via the keyboard or by using the mouse when keyboard accuracy is not required. (An alternate method of data editing appropriate for short data sequences is described in the Menu box section.)

The first step is to click on the trace containing the data that you wish to edit. The second step is to right-click on the Ycursor edit box. (This is the edit box closest to the lower right corner of the figure.) When you do that, a popup menu will appear with a list of the 10 choices shown here. The first three items in this menu, don't really have anything to do with data editing, but this was a convenient place to put them. When you select the first menu item (Properties) one of three different property editing windows will appear depending on how it is selected. When you left-click on "Properties" a window appears which allows you to modify the color and other properties of the currently selected line and its cursor. If before clicking on "Properties" you enable delta cursor mode (Δ button) then a property windows appears which allows you to edit all the lines at once. This is often appropriate for the color property, but it also may be useful for some of the other trace properties, such as linewidth. And finally, if instead of left-clicking you right-click on "Properties" then a window appears that allows you to edit the figure colors. This is the easiest method of accessing the three property editing windows, although for historical reasons there are two additional ways of opening these windows. One is via the "Colors/Lines" selection of the menu bar and the other is via right-clicking the "Mark" tag in the menu box. Both of these methods are mentioned in the Menu box section which also has a full description of the three different property editing windows and how to use them.

The second menu choice (multiCursor) toggles the multiCursor mode which is described here in the Cursoring section and third menu choice (xView slider) toggles the xView slider which is described here in the Zooming and panning section

The fourth menu choice (Cancel) is useful if you opened this popup menu accidentally or when you want to abort an already initiated data editing operation. An additional feature of the Cancel selection, is that if you right click on it (instead of the usual left click) the the previous editing operation will be undone. This may involve reverting many data items to the original when you are using the Range editing described below. This is only a single level undo so you can't undo multiple edit operations.

The remaining six selections in this popup contain the actual data editing commands. The descriptions below are written for completeness rather than brevity so don't be scared off. The commands are intuitive, so you may be better off skipping the descriptions at first in favor of experimentation. The six editing commands are divided into these two types:

Modify

The modify commands change the x or y (or both) coordinates of a single data point by moving the edit cursor with the mouse. After a modify command, the the lengths of the x and y vectors normally don't change ... however there are two exceptions to this. The first is called the "delete mode" which is activated by dragging the edit cursor to any point outside the axis boundary. The point dragged will be removed causing the lengths of the x and y vectors to decrease by one. The 2nd exception is called the "insert mode". The insert mode is activated by dragging the edit cursor with the right mouse button instead of the usual left button. With the insert mode, the lengths of the x and y vectors will both increase by one.

Range

With the range commands the length of the x and y vectors remain the same. The range commands allow you to modify many consecutive data elements at once. All the data points between the current cursor location and the location modified during the previous data editing command are modified so that all these points lie on a straight line connecting the two end locations. For this to work, the previously edited point and the current cursor location must both lie on the same line. If this is not true, then the Range commands behave just like the Modify commands described above. You can recognize whether the range operation or the modify operation is in progress based on the shape of the edit cursor (See cursor shapes table below).

The six commands are also split into three categories which are identified by the arrows next to each command as follows:

Modify↑↓ Range↑↓	These are perhaps the two most commonly used of the data editing menus. As soon as you select the editing mode, the regular data cursor disappears and is replaced by an editing cursor with a different shape. (See data editing cursor shapes below). Then you can grab the edit cursor with the mouse and drag it to the desired location. However you will only be able to move the cursor up and down (i.e. only the y coordinate is allowed to change). This is useful because in many data sets, the independent variable (x) represents a specific chosen set that you want to keep fixed. As soon as you release the mouse button (after the edit cursor has been dragged to its new location) the edit command will take effect, the edit cursor will disappear, and the normal data cursor will reappear. The cursor then reverts to its usual data exploration function, and to edit another data point you must right click yet again on the Ycursor edit box and select the desired data edit operation. This back and forth operation (which I will call the "normal editing mode" is convenient when you just have a few data points to modify, but can become cumbersome when you want to edit many data points in succession. In that situation you can switch to "persistent editing mode". (The persistent editing mode applies only to the three Modify selections and does not apply to any of the Range selections). To enable the persistent editing mode for Modify up/down, bring up the data editing menu as usual, but then instead of left clicking on the Modify up/down selection, click on it with the right mouse button. The label in front of the Ycursor edit box (gray) normally contains the letter "y" (as shown to the left) but this label will switch to the delta symbol (shown to the left) which indicates that you are now in persistent editing mode. Once in this persistent mode, you can continue to modify as many points on the graph as you want (including insert and delete operations) without having to open the data editing menu each time. The only drawback is that you have to forgo the usual data exploration features of the cursor, however you can restore the default mode by double RIGHT clicking on the Ycursor edit box. (at which point the Ycursor label changes from the delta back to the "y").
Modify↔ Range↔	These two menu options behave identically to the two commands described above except for the fact that with the mouse you can only drag the cursor left or right (i.e. only the x coordinate is allowed to change). It is far more common to want to change the y coordinate (using the selections above) or to use the selections below to have the freedom to move the point anywhere (modifying both coordinates), however the left/right option is included for completeness. You can also select this option with the persistent editing mode by right clicking on the Modify left/right option. The gray "y" label of the Ycursor editbox changes to a ">" greater than sign (as shown at the left) to indicate the persistent mode is enabled. Again, you can restore the normal editing mode by double RIGHT clicking on the Ycursor edit box, which will cause the label to revert to "y" indicating the normal editing mode.
Modify Range	When using these last two menu options you can use the mouse to drag the edit cursor anywhere (i.e. you can change both the x and y coordinates of the point. You can select this option with the persistent editing mode by right clicking on the Modify option. The gray "y" label of the Ycursor editbox changes to a solid diamond symbol (as shown at the left) to indicate the persistent mode is enabled. Again, you can restore the normal editing mode by double RIGHT clicking on the Ycursor edit box, which will cause the label to revert to "y" indicating the normal editing mode.

The usual data cursor is a plus sign or a small circle, but once you select one of the six editing modes, the data cursor changes to one of the six edit cursors shown in this table. (Although a single edit cursor shape would suffice, these six cursor shapes makes it clear which editing mode you are using.)

Whenever you see one of these six data cursors, in addition to dragging the cursor with the mouse, you also have the opportunity to type a new new x or y value into the x or y cursor edit boxes. This allows you to enter values more precisely than what is possible with a mouse movement. In all six modes, you may enter a new value in either the x or y edit boxes. (So, for example with the Modify up/down selection, you can still type in a new value into the x edit box, thus bypassing the "y-only" restriction of the mouse movement.) With the ↑↓ and ↔ editing modes, data editing is terminated as soon as you type a value into the x or y edit box. However for the unrestricted modes, data editing isn't terminated until you click on one of the data traces with the mouse. This allows you to enter both x and y values as well as to experiment with different entries before accepting any particular value.

Data Editing programming features

Although programming features and techniques are generally discussed in the "Programming with plt section, the following information is included here because it relates closely with the data editing user interface features shown above.

If you don't like the default size that plt chooses for the six data edit cursors, (shown in the table above) you can change this with a command such as: setappdata(gcf,'CurEdit',14). The new size will be used the next time a cursor edit mode is selected.

If you want to prevent a line from being edited, set the line's tag property to 'NoEdit'. With that line property set, any attempt to edit that line will be ignored.

If plt was called using the MotionEdit parameter, the function specified with that parameter will be called continuously as you drag the edit cursor around. This function may be used to create or modify text, plots or other gui objects on the screen. Both the editz.m and pltquiv.m examples demonstrate the use of the MotionEdit parameter. (Also see Mouse Motion Functions)

If you want to save the altered data (to a file for example) you have to get the data from the 'xdata' and 'ydata' properties of the line handle. (Remember the line handles are returned by the plt call.) When the user modifies any data using these data editing functions, plt executes the user specified move cursor callback. (See the description of the 'set','moveCB' function here.) The callback routine or any other part of your application can use the 'NewData' application property of the current figure window to determine if data has been modified by one of the data edit commands. For example:

index = getappdata(gcf,'NewData'); % returns the index where xdata/ydata was modified
if index % is there any new data?
DataWasModifiedAction(index); % yes, process the new data
setappdata(gcf,'NewData',0); % indicate that the data was already processed
end;

Note that the NewData property only gets set after a data edit operation is complete, unlike the MotionEdit function which gets called as you are dragging a cursored value to its new location. There is one additional figure application data variable called Dedit that may also be useful for an application using the data editing feature. The command getappdata(gcf,'Dedit') will return the following 9 element cell array:

**'Dedit' figure application data (cell array)**
1	The CursorID associated with the edited trace
2	A number from 1 to 6 which identifies which data edit command is being used (in the order that they appear in the popup): 1: Range 2: Range Left/Right 3: Range Up/Down 4: Modify 5: Modify Left/Right 6: Modify Up/Down
3	The handle of the cursor object associated with the modified data.
4,5	For internal use. (This saves the cursor marker shape and size so that the normal cursor can be restored when the data edit operation is complete.)
6	For internal use. (This saves the edited trace x/y data so that it can be restored by the undo function (right clicking on the "Cancel" option)
7,8	For internal use. (This saves the position index and trace number of the previously edited trace - information is needed for the modify range operations.)
9	The position index of the cursor into the edited trace

After performing a data edit operation it is likely that you will want to perform another data edit using the same data edit command. Thus it would be nice if you could initiate another data edit operation without having to again select one of the nine data editing operations. In fact there is a way to do this - simply right-click on the Xcursor edit box. This behaves similarly to what happens when you right-click on the Ycursor edit box except you don't get the menu of data editing choices, since it will use your previous selection. There has to be a default for this operation in case the user right-clicks on the Xcursor edit box before doing any other data edit operation. The default is "Modify" since this is the most commonly used operation. It is rare to want to change this default, although you can do so by changing the second element of the Dedit application variable as described above.

If you create a figure with a plt command that includes the parameter 'MotionEdit','funcname', then while you are modifying a data value by using the data editing feature, the function funcname(a) will be continually called as the mouse is moved (i.e. for as long as the mouse button is held down). The parameter "a" is a nine element cell array containing information related to the edited trace (as described in the table above). Alternatively you can define the MotionEdit function after the call to plt with the following command:

setappdata(gca,'MotionEdit',{@funcHandle param1});

The example demo\editz.m shows how the MotionEdit function can be used to reposition the plotted poles and zeros. Note that allowing the plot to be updated as the data is being edited has an impressive advantage for that application.

The pltquiv.m example also demonstrates the use of the MotionEdit parameter to update the polynomial interpolation of a vector field in real time.

In addition, you may also define functions which get called when a data edit operation begins or terminates. These two functions (respectively) may be defined as follows:

setappdata(gcf,'EditStart',@StartFuncName);
setappdata(gcf,'EditStop', @StopFuncName);

Usually you enter one of the data editing modes by selecting one of the entries in the Yedit popup menu with the mouse, however this can be initiated from a program as well. For example the command plt click Yedit 6; or its functional form plt('click','Yedit',6); puts the cursor into the "modify up/down" mode, since that is the 6th selection in the menu shown above. (Note that the "6" refers to the sixth entry in the Yedit popup menu. The full list of commands similar to this is shown in the table below:

plt xleft EDIT 1;	Enter data editing (using last used editing mode)
plt xleft EDIT 2;	Open up Yedit popup menu
plt xleft EDIT 5;	Exit data editing mode
plt xleft Yedit 4;	Cancel data editing mode
plt xleft Yedit 5;	Enter data edit mode (Range)
plt xleft Yedit 6;	Enter data edit mode (Range left/right)
plt xleft Yedit 7;	Enter data edit mode (Range up/down)
plt xleft Yedit 8;	Enter data edit mode (Modify)
plt xleft Yedit 9;	Enter data edit mode (Modify left/right)
plt xleft Yedit 10;	Enter data edit mode (Modify up/down)
plt xright Yedit 8;	Enter persistent data edit mode (Modify)
plt xright Yedit 9;	Enter persistent data edit mode (Modify left/right)
plt xright Yedit 10;	Enter persistent data edit mode (Modify up/down)

3d data editing

When the data has been plotted using plt('image',...) (i.e. the image pseudo object) you can use the method described below to edit the data in the plotted intensity map. You can practice using these methods with the drawgray.m, pltmap.m, julia.m programs in the demo folder.

Modifying a single pixel at a time

To edit a single pixel, first expand the axis so that each individual pixel near the region you want to modify is easily visible. If you don't know how to do that, review the Zooming and panning section. Next click on the pixel that you want to edit. In this example we have clicked on the pixel at (x,y) coordinates (37,42). The cursor marker (an asterisk symbol) will always appear in the middle of the pixel. It's current Z value (i.e. intensity) will appear below the graph after the "Z:" label. In this example (using the drawgray.m demo) the Z value for this pixel is 223.66. Suppose we want to change this value to 4.4. Right click on the 223.66 number and then press the backspace key until the number is erased and then type "4.4" and press enter.

The figure will now look like this. Notice that the chosen pixel has change to black and the Z value readout shows the new pixel value. Also note the cursor color has also changed. (This is because plt insures that the contrast between the cursor and the pixel color is as high as possible.) Notice that a new symbol has appeared (a left arrow) just to the left of the Z: label. This is the undo symbol. If you now click on the undo symbol, the Z value will revert to 223.66 (the value the pixel held before editing). Since this was the only data edit we have done, the left arrow symbol will disappear indicating that there is nothing left to undo. There is essentially no limit (beyond the amount of memory allocated to Matlab) to how many undo operations are allowed. If you make 100 edits, the left arrow will remain visible until you click on it 100 times as each of the edits are reversed. Modifying the same pixel twice in a row is treated like a single edit. For example if we modified the 4.4 value again (to say 5.5) without changing a different pixel in between) then pressing undo will not change it back to 4.4 but rather back to 223.66 (its original value).

In addition to typing the new Z values as we just described, if you want to change the intensity value more gradually you can left click just to the right or left side of the current Z value to increase or decrease the Z value by 1. You can also hold down the mouse button after clicking and the Z value will continue to increase or decrease until you release the mouse button. The pixel value will slowly change its color as you are holding down the mouse button and the cursor marker will also change as necessary to maintain adequate contrast with the surrounding pixel color.

Modifying a rectangular region

In addition to editing a single point, we can fill a rectangular region with a constant value. We start by placing the cursor on any corner of the region we would like to fill. In this example, I have chosen to cursor the upper right corner of the fill region at the (x,y) coordinates (6.377,8.102). The Z value at this point happens to be 6.3951 as you can see by the Z readout at the bottom of the figure. For this particular color map (jet) this Z value corresponds to the orange pixel you see in the cursored square. (Note: You can replicate this figure by running the pltmap.m demo program and then moving the resolution slider all the way down to its lowest setting of 25 pixels).

Next we enter the desire fill value (zero in this example) by right clicking on the current Z value (6.3951), entering backspaces followed by a zero and then pressing enter. This is the same process described above for editing a single pixel, and indeed only the one pixel chosen has been modified as shown here.

Next we cursor the opposite corner of the desired rectangle. In this example, I have cursored the point (3.188,2.209) which will be the lower left of the fill region. As you can see, the Z value of this point is 6.3627 (which is similar to but not identical to the original Z value of the upper right corner pixel).

To complete the fill operation, right click on the yellow Z: text string which is located at the bottom of the figure between the left arrow symbol and the zero character that indicates the fill value for the region. As soon as you do that, the selected region will be filled and the figure will look like this one. This may feel like two edit operations, but it is recorded as a single edit operation which means that clicking on the left arrow will restore the entire fill region to contain the values that it had before the rectangular fill operation began. If no other pixels were edited, the left arrow symbol will disappear indicating that there is nothing left to undo. The undo buffer may contain a mixture of single point and rectangular fill edit operations and they will be undone one item at a time (in the reverse order that they were entered) until the left arrow disappears and the plot is returned to its original configuration.