Auxiliary .m files

  

 

These .m functions exist as separate files in the main plt folder. They aid in creating special plot types.

 

vbar.m
(vertical bar plots)   		This function is used to plot a series of vertical bars. It doesn't do any plotting itself, but returns an array which is then plotted using plt (or even plot). For example, suppose you want to plot 4 vertical bars at x-axis locations 2,3,7,8. Each bar is to start at y=0 and extend up to y=6,6,5,1 respectively. The following line would meet this objective:

plt(vbar([2 3 7 8],0,[6 6 5 1]);

Normally the 3 vbar arguments are the same size, however in this case since the lower y position of each bar is the same, a constant may be used for the 2nd argument.

Although you don't have to know this to use it, vbar returns a complex array which is interpreted correctly by plt or plot to display the desired sequence of vertical bars. plt and plot displays complex arrays by plotting the real part of the array along the x-axis and the imaginary part of the array along the y-axis. The trick that vbar uses to display a series of lines with a single array stems from the fact that NaN values (not a number) are not plotted and can be used like a "pen up" command. (The ebar and quiv functions described below use this same trick.)

The general form of the vbar function call is:

v = vbar(x,y1,y2)

If the inputs are row or column vectors, this would return a complex column vector which when plotted with plt or plot would produce a series of vertical bars (of the same color) at x-axis locations given by x. y1 and y2 specify the lower and upper limits of the vertical bar. It doesn't matter whether you list the upper or lower limit first. If y1 is a scalar, vbar expands it to a constant vector of the same size as y2.

Suppose you wanted to plot 30 bars of one color (specified by length 30 column vectors xa,ya1,ya2) and 30 bars of a different color (specified by length 30 column vectors xb,yb1,yb2). You could do this with two calls to vbar as in:

plt(vbar(xa,ya1,ya2),vbar(xb,yb1,yb2));

That's probably the first way you would think of, but if xa and xb happen to be the same length (as in this case) you can accomplish the same thing with a single call to vbar:

plt(vbar([xa xb],[ya1 yb1],[ya2 yb2]);

The second form is especially convenient when plotting many bar series (generally each series in a different color). Interestingly, if you use plot instead of plt you must use the second form since the first form will not work.

Note that vbar will expand the second argument in either dimension if needed. So for instance in the example above, if ya1 and yb1 were the same you could just use ya1 as the second argument. Or suppose the base (lower limit) of the first series was always 0 and the base of the second series was always -1. Then you could use [0 -1] as the second argument. If the base of all the bars in all the series was the same value, then the second argument may be a scalar.

To see vbar in action, look at the example program pltvbar.m in the demo folder. This example also shows the use of the ebar function described below.

 
ebar.m
(error bar plots)  

 

 This function is used to plot a series of vertical bars similar to the above vbar function with the addition of a small horizontal "T" section on the top and bottom of each bar. This is commonly used to depict an error bound of a function, or a range of values that may be achieved by a certain function. Another difference with vbar is the way the lower and upper y positions of the bars are specified. With ebar, the first two arguments (x,y) specify a reference position for each vertical bar, which is normally (but not strictly necessary) somewhere in the middle of the bar. The third/fourth arguments (l,u) specify the distance between the reference position and the lower/upper end (respectively) of the vertical bar.

The general form of the ebar function call is:

e = ebar(x,y,l,u,dx)

The position of the top of the error bars is y+u and the bottom is y-l. The last argument (dx) is a scalar that specifies the width of the horizontal Ts as a percentage of the average x spacing. The last two arguments are optional. If dx is not specified it defaults to 30 (%). If u is not specified it defaults to l (the 3rd argument) in which case the reference coordinates become the midpoints of the error bars. e,x,y,l,u are generally vectors or matrices of the same size, the only exception being that if l or u are constant, the may be scalar. Read the description of vbar above for an explanation of how vector and matrix inputs are interpreted.

To see ebar in action, look at the example program pltvbar.m in the demo folder. This example also shows the use of the vbar function described above.

 
quiv.m  
(vector plots)		 This function is used to plot a vector fields represented by a set of arrows with arbitrary head and tail locations. It doesn't do any plotting itself, but returns an array which is then plotted using plt (or even plot). For example, suppose you wanted to plot 3 arrows (all in the same color) with tail locations (4,9) (2,3) and (1,7). Also suppose you wanted each vector to be of length one, pointing up, down, and the the right respectively. Either of the following lines would meet this objective:

plt(quiv([4;2;1],[9;3;7],[0;0;1],[1;-1;0]));

plt(quiv([4+9i;2+3i;1+7i],[1i;-1i;1]));

Note that row vectors could have been used instead of column vectors if desired. Now suppose in addition to those 3 vectors, you wanted to plot 3 more vectors (in a second color) with the same tail locations but pointing in the opposite direction. Either of the following lines would meet this objective:

plt(quiv([4+9i;2+3i;1+7i],[1i;-1i;1]),quiv([4+9i;2+3i;1+7i],[-1i;1i;-1]));

plt(quiv([4+9i;2+3i;1+7i]*[1 1],[1i;-1i;1]*[1 -1]));

Of course the equivalent 4 argument (real input) form of quiv could have been used as well.

There are 8 possible calling sequences for quiv depending on whether the input arguments are real or complex and on whether the optional arrow head size argument is included. Quiv is smart enough to figure out which calling sequence you are using.

Calling sequence Tail coordinates Arrow width/length Arrow head size
q = quiv(A,B) [real(A), imag(A)] [real(B), imag(B)] 0.3
q = quiv(A,B,h) [real(A), imag(A)] [real(B), imag(B)] h
q = quiv(x,y,B) [x,y] [real(B), imag(B)] 0.3
q = quiv(x,y,B,h) [x, y] [real(B), imag(B)] h
q = quiv(A,u,v) [real(A), imag(A)] [u, v] 0.3
q = quiv(A,u,v,h) [real(A), imag(A)] [u, v] h
q = quiv(x,y,u,v) [x, y] [u, v] 0.3
q = quiv(x,y,u,v,h) [x, y] [u, v] h

where:
q,A,B are complex vectors or matrices
x,y,u,v are real vectors or matrices
h is a scalar (Arrow head size - relative to vector length)
 

Read in the vbar description above how complex values and NaNs are used to generate the desired display. To see quiv in action, look at the example program pltquiv.m in the demo folder.