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 which 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 traceIDs, 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 number of IDs displayed.

Normally traceIDs 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 pub.m demo program demonstrates the use of this special character.

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 pltquiv.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, callbacks defined within plt may use a double quote character instead of two successive single quotes. The pltquiv.m example uses this alternative form. 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 traceIDs 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'});

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');

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). See the demo programs trigplt.m and subplt.m  for examples of using the TraceMK parameter.

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 traceIDs 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).

You might expect that when all the free slots in the TraceID box have been used up, you can no longer add a new trace with the pltt function ... but in fact you can. What happens is that in this situation, pltt will overwrite the data and the trace name of the last trace that was added, so effectively you can never run out of free slots (unless you never allocated any in the first place).