# Trace properties

### Right
| You specify which traces should appear on the right-hand axis with the 'Right' parameter. For example, if you included 'Right',[1 4:2:10 17] in the parameter list, then plt would put trace numbers 1,4,6,8,10, and 17 on the right axis and all other traces on the left axis. A slight shading is used behind the Trace IDs associated with the right-hand axis so you can tell at a glance which traces belong to which axis. (You can disable this shading if you prefer. To see how read the description of the TraceID parameter below). You can also tell which axis a trace is on by the shape of its cursor ('+' for left axis and 'o' for the right axis). You can optionally specify a label for the right hand axis (see LabelY) as well as the axis limits (see YlimR). Specifying an empty list, as in 'Right',[] tells plt to use the left axis for all the traces (the same as if you omitted the Right parameter altogether.)
### Markers
| The Markers parameter is a shorthand way of setting a different marker property for each line. For example: plt(x,y,'Markers',s) is equivalent to: a = plt(x,y); for k=1:length(a) set(a(k),'Marker',s(k,:)); end; The argument may be an array of characters or a cell array of strings. The latter method is easier when the elements are different sizes because you don't have to pad with blanks as with the character array. (Wherever a character array is allowed in a plt argument list, a cell array of strings is also allowed and visa versa.) For example, these two lines have give the same result: plt(...,'Markers',['square';'+ ';'none ']); plt(...,'Markers',{'square','+','none'}); This sets the marker for the first two lines to a square and a plus sign respectively while the third line will be rendered without any markers. The following example shows two ways to set the markers of the six traces to x,+,square,o,asterisk,x (respectively). The shorter method used in the 2nd line is possible because every marker may be represented with a single character: plt(...,'Markers',['x';'+';'s';'o','*','x']); plt(...,'Markers','x+so*x');
### Styles
| The Styles parameter is a shorthand way of setting the LineStyle property in a similar way that the Markers parameter is used to set the Marker property. For example, to set the first trace to normal, the 2nd and 3rd traces to dotted and dashed respectively, and the 4th trace to none (useful when you want the markers with no lines connecting them) you would use the following command: plt(...,'Styles',{'-',':','--','none'}); The shorthand for single-character styles mentioned above also works. For instance, to alternate between normal and dotted among eight traces one could use: plt(...,'Styles','-:-:-:-:'); One additional trick applies to the Styles parameter. If a single character is given which is not a valid line style, then the linestyle property is set to none and the given character is applied to the marker property. As an example, the following command defines eight traces of which the first four are rendered as continuous lines (i.e. without markers) and the last four are rendered with plus sign markers placed at each x,y location specified by the data arrays but with no lines connecting the markers: plt(...,'Styles','----++++'); Since there are no marker property values that can also be linestyle property values, there is never any ambiguity as to which property should be set.
### GridStyle
| This parameter allows you to select the grid line style. For example: plt(...,'GridStyle',':'); will select a dotted or dashed line (depending on the graphics renderer). If this parameter is not included the default is usually a solid line ('-') although there is one somewhat complicated exception to this which is described in the default section of the GRIDc parameter which you can find here.
### TraceID
| This parameter allows you to assign a name to each trace. This name will appear in the trace selection box (also sometimes called the TraceID box). The number of characters that will fit in the trace selection box depends on the size you choose for the plt window. For the default figure size there is room for about 5 uppercase or 6 lowercase characters. In the example below, both forms are equivalent: plt(...,'TraceID',['Rtemp';'Ltemp';'RV1 ']); plt(...,'TraceID',{'Rtemp';'Ltemp';'RV1'}); Default: ['Line 1';'Line 2'; ... 'Line n']; If you want the plot to be created without a TraceID box, call plt with a TraceID parameter of zero or the empty set ([] or ''). Since plt can't create a TraceID box containing more than 99 IDs, if you want to plot more than 99 traces, you must include 'TraceID',0 (or with the equivalent empty set value) in the parameter list. When specifying trace IDs, you must have one trace ID for every trace on the main and right-hand axes. However, if you don't want a trace ID for a specific trace to appear, just use the null string ('') for the trace name. If you do that, the trace ID box will be made smaller to account for the fewer trace IDs displayed. Normally trace IDs associated with the right-hand axis will appear in the TraceID box with a slight shading so you can identify those traces at a glance. If you want to disable this shading, insert the special character ']' at the beginning of the first TraceID name. The right bracket will be removed from the trace name before it is used. The third plot of the pub0.m demo program demonstrates the use of this special character as does the main figure of the erip.m program (located in the sig folder). You may specify a callback function (fcn) to execute when the user clicks on any of the TraceID tags by including the parameter 'TIDcback',fcn in the argument list. If the string '@TID' occurs anywhere inside the function string then it's replaced with the handle of the trace ID string. Likewise if the string '@LINE' occurs anywhere inside fcn, it is replaced with the handle of the trace itself, and occurrences of '@IDX' are replaced with the index of the selected trace. (i.e. 2 for the second trace listed in the TraceID box). See the demo program vBAR.m for an example using the TIDcback parameter. In that example, the name and color of a trace is displayed in the command window when you click on a Trace ID tag. (Not particularly useful, but this example was contrived to demonstrate all the possible substitutions.) To define a quote within a quote in Matlab, one uses two single quote characters in a row. Since this can get confusing at times, recent versions of Matlab allow the use of a double quote character instead of two successive single quotes. Callbacks defined within plt may use this double quote shorthand even with older versions of Matlab that don't usually support it. In addition to a string, fcn may also be a function handle of the form @func or {@func,arg1,arg2,...,argn}. Note that the string substitutions can't be used with the function handle form of this parameter. You also may change the trace IDs after the plot has been created. For example, if the current figure contains a plot with four traces, these traces can be renamed with a command such as: plt('rename',{'First' 'Second' '3rd' '4th'}); The rename operation accepts an additional argument (which defaults to 1 if not included) specifying the first trace to rename. For example to rename just traces 2 and 3 you could use the command: plt('rename',{'Second' '3rd'},2); You don't need a cell array when renaming just a single trace. For example, this command would rename just the 3rd trace: plt('rename','NewName',3); It's possible for a figure to contain more than one TraceID box. In that case, the rename function assumes that the trace names are concatenated in the order the TraceID boxes were defined. (The demo program editz.m is an example of this.) So for example if the first plot had 5 traces and the 2nd plot had 4 traces, then this command would rename the last trace in the first plot and the first two traces of the second plot: plt('rename',{'NameA5' 'NameB1' 'NameB2'},5); If there are other changes you want to make to the TraceID box from your program (as in the curves.m example), you can get the handle of the axis that contains all the TraceID objects with the following command: tbox = findobj(gcf,'user','TraceID'); An alternate method of getting the handle of the TraceID axis is with the following commands: h = cur(cid,'obj'); tbox = h(14) (where cid is the cursor ID associated with the plot axis) The first method is simpler if there is only one TraceID box in the figure window. However, if there is more than one, tbox would contain a vector of handles to all the TraceID boxes, so in that case the second method is easier. Then, for example, the following command would make the TraceID box invisible: set([tbox; get(tbox,'child')],'vis','off') An easier way to make the TraceID box invisible would be to simply move it outside the figure area: set(tbox,'pos',[-2 0 1 1]). Or in the unlikely event you wanted to reverse the order of the TraceIDs (i.e. bottom to top ordering in the TraceID box), use the command: set(tbox,'view',[0 270]).
### TraceMK
| This parameter allows you to show the line types in the trace selection box to help identify the traces. This can be visually pleasing and is especially helpful if you are color blind. If the argument is a vector, it specifies the marker positions within the trace selection box. For example 'TraceMK',[.6 .7 .8 .9] would tell plt to place a horizontal line next to each TraceID label beginning and ending at x = .6 and .9 with markers at the four locations specified (assuming the line type in the plot included markers). The area between x = 0 and .6 (i.e. the first 60%) would be used for the text label. If the first element of the vector is less than .25 then plt will not display the text labels since there probably would not be room for them anyway. (Clicking on the lines in the TraceID box have the same effect as clicking on the labels, so the labels can be removed without loss of functionality). If the argument is a scalar, plt will use that value as the first element of a length 3 vector whose last element is .9. Thus 'TraceMK',.6 is shorthand for 'TraceMK',[.6 .75 .9]. A special case is when the scalar argument is zero, in which case no lines are inserted into the trace selection box (as if the TraceMK parameter was not used at all). For examples of using the TraceMK parameter, see the demo programs trigplt.m, subplt.m and pub0.m.
### TIDcolumn
| All TraceIDs will appear in the trace selection box (aka TraceID box) in a single column except when the TIDcolumn parameter is included. This is useful when you are using so many traces that the TraceID box becomes too crowded to fit all the trace names in a single column. The simplest way to use the TIDcolumn parameter is to supply an empty argument to the parameter (i.e. '' or []). When this is done plt will use just a single column for the TraceID box when the number of traces is 24 or less. Two columns will be used when the number of traces is between 25 and 48, and three columns will be used when there are more than 48 traces. (The TraceID box will not appear when more than 99 traces have been defined). This default will probably work in nearly all situations but if you want exact control over how many columns are used and how many trace IDs appear in each column, you can do that by specifying a non-empty argument to the TIDcolumn parameter as follows: If TIDcolumn is a scalar, it specifies the number of TraceIDs to put in the second column. If it is a vector, it specifies the number of TraceIDs to put in columns 2,3, etc, with the remaining going into column 1. For example, if 30 traces are displayed, and you use 'TIDcolumn',8 then the first 22 TraceIDs appear in the first column and the last 8 appear in the second column. 'TIDcolumn',[5 5 5] would tell plt to arrange the 30 IDs in four columns as follows: (1-15, 16-20, 21-25, 26-30).
### DIStrace
| By default, all the traces defined by plt are visible until you change that from the trace selection box. You can change the default by disabling some traces from the plt call. For example: plt(...,'DIStrace',[1 1 0 0 0]); This tells plt to start the display with the first two traces disabled and the remaining 3 traces enabled. Of course, you can later enable the first two traces via the trace selection box. If the parameter has fewer elements than the number of traces, it is extended by adding zeros. This means that we could have used [1 1] above to the same effect. After the call to plt has been made, if you want to change which traces are enabled/disabled you can click on the TraceIDs as described in Selecting traces. However, if you want to do that from a program you can use the plt('show',...) command which is described at the very bottom of the Calling sequence and line styles section.
### ENAcur
| By default you will be allowed to cursor every visible trace in the plot area. You can change this default using this parameter. For example, if we had five traces, but wanted to use cursors only on traces 1,4, and 5 you would use: plt(...,'ENAcur',[1 0 0 1 1]); If the parameter has fewer elements than the number of traces, it is extended by adding ones. This means that we could have used 'ENAcur',[1 0 0] above to the same effect.
## +
| This parameter allows you to reserve space for additional traces to be added to the figure after the plt window has been started. For example plt(x1,y1,x2,y2,'+',5); opens the plt window with two traces, the first one defined by x1,y1 and the second one by x2,y2. Then, room is reserved in the TraceID box for up to 5 more traces that can be added using the pltt.m function. This parameter is normally only used inside script or function files because when you type the plt command in the Matlab command window an automatic '+',8 is assumed. You could still include the + parameter from the command window in the unlikely event you were planning on adding more than 8 traces. When plt is called from a script or function, you can't add traces after the plt window has opened unless you had included the + parameter in the argument list. It is unusual to want to add dozens of traces with the pltt function, but it is possible. For example with the command plt(x,y,'+',39,'TIDcolumn',''); plt will reserve space in the TraceID box for 40 traces. The first is specified in the plt command and the remaining 39 can be added using the pltt function. The TIDcolumn parameter was needed in this case because, without it, plt would attempt to cram all 40 TraceIDs into one column which would probably be unreadable. You may include the TraceID parameter in the argument list as well if you like, and you should be aware that there are two ways of doing this. The first (and by far the most common) way of doing this is to put the 'TraceID' parameter before the '+' in the argument list. When done in that order, that TraceID argument specifies the trace names only for the traces defined in the argument list. Then when the '+' parameter is encountered, plt expands the TraceID list using default names that will usually be overwritten by the trace names included in the calls to pltt. When done in the opposite order, the TraceID argument should include the trace names you want for the traces that will be added later (even though the trace names will be invisible until those traces are added). And if the TraceID argument does not include enough trace names for this, when a trace is added after the list has been exhausted, the new trace will be added without any corresponding entry in the TraceID box (which occasionally might even be what you wanted). Typically the + parameter is placed after all the traces defined inside the plt argument list, however, this is not strictly necessary. In fact, multiple + parameters may be included and they may be interspersed with the trace definitions in the parameter list. When you do that, the space reserved in the TraceID box for the traces to be added later will be interspersed with the defined traces in the order in which they appeared. This flexibility is rarely needed, but nevertheless, it is available if you want it. Note that when traces are added with the pltt function, the reserved slots are used in order (top to bottom, as well as left to right if multiple columns were enabled). When calling plt from the command line, you can use '+',0 to indicate that you don't want to reserve any slots for adding traces later with pltt although there is no particular advantage in doing that. You can also include '+',0 in the argument list when calling plt from a script or function to allow the use of pltt to delete one or more of the defined traces. (You can't use pltt unless the '+' parameter was included explicitly or implicitly (by invoking plt from the command window).
### properties
| If a property name appears in the argument list, then the property value will be assigned to all the lines that have been defined so far in the argument list. For example: plt(x,[y1;y2;y3],'LineWidth',5); will define 3 traces, each with a linewidth property set to 5. The property value may also be a cell array of the same length as the number of traces that have been defined so far. In that case, each cell array element is applied to its respective line. For example: plt(x,[y1;y2;y3],'userdata',{27 16 3}); will create three traces. The trace associated with y1/y2/y3 will contain userdata values of 27/16/3 respectively.