View source for plot/examples

==Example Using xaxis==
xaxis operates much as it did in xplot().<br>
If you specify the global keyword Xaxis value anywhere in the argument list it will be applied as the override xaxis for every object.<br>
If you declare an Xaxis and then you feed plot() an object whose dimensions do not match the Xaxis, you will receive the error, "<i>Length of x-axis vector is different than object vector.</i>"<br>
You may <i>not</i> override this by specifying an object specific xaxis, so beware using global keywords.<br>

 dv> m
 1x1x143 array of float, bsq format [572 bytes]
 
 dv> mx
 1x1x143 array of float, bsq format [572 bytes]
 
 dv> n
 1x1x10 array of float, bsq format [40 bytes]
 
 dv> plot(m, Xaxis&#61;mx, n)
 Length of x-axis vector is different than object vector
 
 dv> nx
 1x1x10 array of float, bsq format [40 bytes]
 
 dv> plot(m, xaxis&#61;mx, n, xaxis&#61;nx)

[[Image:ex1.png]]<br>
[[plot|Back to plot()]]

==Example Using axis==
The keyword axis tells plot() along which dimension of your object you wish your vectors to run.<br>
It only accepts the values: x, y or z, and is called like this:  axis &#61; y    or   axis &#61; 'y' <br><br>
axis operates much as it did in xplot().<br>
If you specify the global keyword Axis value anywhere in the argument list, Axis will be applied as the override axis for every object.<br>
You can <i>not</i> override this by specifying an object specific axis, so beware using global keywords<br><br>
<b>Possible Errors</b><br>
If you declare an axis and an xaxis or Xaxis and then you feed plot() an object whose dimensions do not match the Axis, you will receive the error, "<i>Length of x-axis vector is different than object vector.</i>"<br>
If you declare an axis and then feed plot() an object whose dimensions do not match the axis and you <i>do not</i> specify an Xaxis, it <i>will</i> plot the object, most probably on the x=0 Y-axis of the graph. See the graph below.<br>

 dv> a
 1x101x1 array of float, bsq format [404 bytes]
 
 dv> b
 1x1x17 array of float, bsq format [68 bytes]
 
 dv> plot(a, axis&#61;y, b)

[[Image:ex2.png]]<br><br>
You can also plot b along it's own axis by specifying it:<br>

 dv> plot(a, axis&#61;y, b, axis&#61;z)

[[Image:ex2a.png]]<br>
[[vplot|Back to plot()]]

==Example Using labels==
Labels of the plotted objects are placed in the key.<br>
plot() allows two ways to specify the label you want to use.<br>
You can use the keyword 'label' any place in the argument stream after the object you want it applied to and <i>before</i> the next object.<br>
An example would be:<br>

 dv> a
 1x101x1 array of float, bsq format [404 bytes]
 
 dv> b
 1x101x1 array of float, bsq format [404 bytes]
 
 dv> plot(a,label&#61;"Silly sine wave",b)
[[Image:ex3.png]]<br>

plot() does not require you to actually type 'label =' to specify the name of the object.<br>
Any string placed in quotes after a plot object is declared will be used as the label.<br>
Like so:
 plot(a,"Silly sine wave",b)
results in the same graph above.<br>
[[plot|Return to plot()]]

==Example Using ignore values==
plot() allows for three types of ignore values that may be used in any combination.<br>
The keyword 'ignore' is called when you wish to plot an object but you do not want a certain y-value included.<br>
ignore values are only applied to the plot object after which they are stated.<br>
Here's an example where there is a data dropout to a null-data value of -0.01:
 dv> data
 6220x1x1 array of double, bsq format [49,760 bytes]
 
 dv> data_x
 6220x1x1 array of float, bsq format [24,880 bytes]
 
 dv> plot(data,xaxis&#61;data_x)
 
 dv> plot(data,xaxis&#61;data_x,ignore&#61;-0.01)
[[Image:ex4.png]]<br>
[[Image:ex4a.png]]<br><br>
There are four other keywords, which may be used in conjunction with ignore.<br>
These keywords are not part of standard Gnuplot capabilities, but are useful for segregating regimes in davinci plots.<br><br>
===Example using y ignore values===
When you wish to ignore values in y, <b>iabove</b> will <i>ignore above</i> a specific y value, and <b>ibelow</b> will <i>ignore below</i> the specified y value.<br>
Here is an example using <b>ibelow</b> using the previous data.  Let's say we don't believe any value below -0.0003:

 dv> plot(datas,x&#61;data_x,ignore&#61;-0.01,ibelow&#61;-0.0003)
[[Image:ex4b.png]]<br><br>
===Example using x ignore values===
Finally, plot() allows for ignore values on the x-axis.<br>
The usage is two fold:<br>
You may use <b>ixabove</b> to ignore all data values whose x-axis value is above your designation, and similarly for <b>ixbelow</b><br><br>
The other usage allows the user to <i>cut out a single section</i> of the data.<br>
To eliminate a section of the data in the middle of the plot, designate a <b>ixabove</b> that is <i>below</i> <b>ixbelow</b>.<br>
Here is an example:<br>
 dv> data
 2000x1x1 array of float, bsq format [8,000 bytes]
 
 dv> plot(data, xaxis&#61;data_x)
[[Image:ex4e.png]]
 dv> plot(data, xaxis&#61;data_x, ixabove&#61;0.198, ixbelow&#61;0.204)
[[Image:ex4f.png]]
[[plot|Back to plot()]]

==Example Using errorbars==
Errorbars may be applied to any plot object, but they must adhere to a specified format both in Gnuplot and davinci.<br>
You may designate errorbars using the surprising keyword 'errorbars'.<br>
Your errorbars object must have the same number of elements in the axis dimension as your object and your xaxis.<br>
Let's say you've got a object with dimensions 1x1x1080 and the same for the xaxis; your errorbars must have a z-dimension of 1080 too.<br><br>
Now, so far so good, but the other dimensions depend on which type of errorbars you want to use.<br>
After calling the keyword 'errorbars' to provide the values you wish to use, you must set the keyword 'style' to one of the six following types of errorbars:<br>
<b>xerrorbars, yerrorbars, xyerrorbars xerrorlines, yerrorlines and xyerrorlines.</b><br>
Each of these comes in two flavors: delta values or low and high values, making the total number of variations errorbars accepts 12.<br>
It's easiest to just give examples.<br>
 #here's an altered sine wave
 dv> a
 1x101x1 array of float, bsq format [404 bytes]
 
 dv> plot(a)
[[Image:ex5.png]]<br>
===Delta Errorbars===
You only need one column of numbers if you're going to give the errorbars as a 'delta' value, where your error is the same in the positive and negative directions.<br>
So let's add a y-delta error of 0.11:<br>
 dv> my_y_delta_error&#61;clone(0.11,1,101,1)
 1x101x1 array of float, bsq format [404 bytes]
 
 dv> plot(a, errorbars&#61;my_y_delta_error, style&#61;yerrorbars)
[[Image:ex5a.png]]<br>
===High and Low Errorbars===
If you wish to provide a different value for '+' and '-' errors, then you need two columns telling the low and high <i>values</i>, not <i>offsets</i>.<br>
 dv> y_errorbar_high &#61; a+0.11
 1x101x1 array of float, bsq format [404 bytes]
 
 dv> y_errorbar_low &#61; a-0.32
 1x101x1 array of float, bsq format [404 bytes]
 
 dv> y_err_low_high &#61; cat(y_errorbar_low, y_errorbar_high, axis&#61;x)
 2x101x1 array of float, bsq format [808 bytes]
 
 dv> plot(a, errorbars&#61;y_err_low_high, style&#61;yerrorbars)
[[Image:ex5b.png]]<br>
The previous examples work just as well for x-errorbars as for y, you just set the keyword 'style' to 'xerrorbars'.<br><br>

===Errorbars in both X and Y===
If you wish to use delta values, then you need 2 columns, the first for X-delta and the next for Y-delta.<br>
If you wish to set high and low values, the columns need to follows the order: X-low, X-high, Y-low, Y-high.<br>
I'll use the same data, but I'm going to zoom in to show the errorbars.<br>
 dv> my_xlo_xhi_ylo_yhi
 4x101x1 array of float, bsq format [1,616 bytes]
 
 dv> plot(a, errorbars&#61;my_xlo_xhi_ylo_yhi, style&#61;xyerrorbars)
[[Image:ex5c.png]]<br><br>
<b>Errors</b><br>
There is one kind-of-crappy limitation on errorbars usage.<br>
You see in the example above that the errorbars has dimensions 4x101x1.<br>
If you use errorbars, the dimension of your object must be 1 in the dimension of errorbars that defines the inputs.<br>
In this case your object may only have an x dimension of 1, but can have any dimension in z.<br>

[[plot|Back to plot()]]

==Example Using style, width and color==
style, width and color are equivalent to the Gnuplot flags ls (line style), lw (line width) and lt (linetype), and are applied to the plot object they immediately follow or are in a [[plot/examples#Example_Using_structures|standard structure]].<br>
For multiple objects you can use as many different styles, widths and colors as you wish.<br>
 dv> a
 1x44x1 array of float, bsq format [176 bytes]
 
 dv> b
 1x131x1 array of float, bsq format [524 bytes]
 
 dv> bx
 1x131x1 array of float, bsq format [524 bytes]
 
 dv> plot(a, style&#61;points, b, xaxis&#61;bx, style&#61;lines, color&#61;3, a*0.2, style&#61;impulses, color&#61;5)
[[Image:ex6.png]]<br>

[[plot|Back to plot()]]

==Example Using dir and gcommand==
For every graph drawn to the screen plot() creates 1 or more text files to contain the data.<br>
These files are used by Gnuplot to draw the graph.<br>
In general, plot() is used to display data to users, not to make publication-grade graphs.<br>
However, you can save the text files in the directory of your choice using the keyword 'dir'.<br>
You can also obtain the Gnuplot command (which is often very long) used to make the graph using the keyword 'gcommand'.<br>
With the files you can go into Gnuplot, alter the command and make graphs as pretty as you please.<br>
This is how you do it:<br>

 dv> a&#61;random(3,441,1)
 3x441x1 array of float, bsq format [5,292 bytes]
 
 dv> plot(a, dir&#61;"/home/me/Desktop", gcommand&#61;1)
 
 plot '/home/me/Desktop/7OVX3o' title 'Obj 1'
 
The temporary text file is '70VX3o', not a very intuitive name, I'll grant you, but it is in the directory I specified and it has data readable by Gnuplot.<br>
The Gnuplot command is printed to the screen and can be cut and paste into Gnuplot and then added to. From that point you're on your own dealing with Gnuplot.<br><br>
Here is the Gnuplot Homepage: http://www.gnuplot.info/<br><br>
[[plot|Back to plot()]]

==Example Using structures==
plot() allows you to provide it with a structure containing any of these standard elements:<br>
.data (which it <i>must</i> contain)<br>
.xaxis<br>
.axis<br>
.label<br>
.errorbars<br>
.ignore<br>
.iabove<br>
.ibelow<br>
.width<br>
.color<br>
.style<br>
.separate<br><br>
Example:<br>
 dv> zz
 struct, 6 elements
     data: 1x101x1 array of float, bsq format [404 bytes]
     xaxis: 1x101x1 array of float, bsq format [404 bytes]
     iabove: 1.50000
     label: "Ebeneezer"
     color: 3
     width: 2
 dv> plot(zz)
[[Image:ex7.png]]<br>
You may combine standard structures with VAL inputs willy nilly.<br>
 dv> a
 17x1x1 array of float, bsq format [68 bytes]
 0.200000        0.280000        0.360000        0.440000        0.520000       
 0.600000        0.680000        0.760000        0.840000        0.920000        
 1.00000         1.08000         1.16000         1.24000         1.32000         
 1.40000         1.48000
 
 dv> b
 17x1x1 array of float, bsq format [68 bytes]
 0.780000        0.792000        0.804000        0.816000        0.828000       
 0.840000        0.852000        0.864000        0.876000        0.888000        
 0.900000        0.912000        0.924000        0.936000        0.948000        
 0.960000        0.972000
 
 dv> plot(zz, a, xaxis&#61;b)
[[Image:ex7a.png]]<br>
[[plot|Back to plot()]]

==Example Using smooth==
Gnuplot has built in functions to fit smoothing functions to data.<br>
There are currently two options for the keyword smooth: bezier and csplines.<br>
 dv> a
 6220x1x1 array of float, bsq format [24,880 bytes]
 
 dv> ax
 6220x1x1 array of float, bsq format [24,880 bytes]
 
 dv> plot(a, xaxis&#61;ax)

[[Image:ex8.png]]

 dv> plot(a, xaxis&#61;ax, smooth&#61;bezier)

[[Image:ex8a.png]]

[[plot|Back to plot()]]

==Example Using offset and separate==
It frequently happens that when viewing data the plots are all very similar and lay on top of each other.<br>
'offset' allows you to specify a y-value applied cumulatively to each successive plot.<br>
por ejemplo:<br>
 dv> a
 2000x5x1 array of float, bsq format [40,000 bytes]
 
 dv> plot(a)

[[Image:ex9.png]]

 dv> plot(a, offset&#61;0.1)

[[Image:ex9a.png]]

offset works well with the 'separate' keyword which draws successive plots in different colors.<br>

 dv> plot(a, offset&#61;0.1, separate&#61;1)

[[Image:ex9b.png]]

[[plot|Back to plot()]]

==Example Using shortened syntax==
Although plot() asks for the keywords 'data', 'xaxis', 'axis' and the like, it actually accepts shortened versions of these keywords.<br>
Below is a list of the keyword and it's shortened syntax.<br>
Xaxis -> X<br>
Axis -> A<br>
xaxis -> x<br>
axis -> a<br>
ignore -> ig<br>
iabove -> ia<br>
ibelow -> ib<br>
separate -> se<br>
style -> st<br>
width -> w<br>
color -> c<br>
errorbars -> e<br>
directory -> d<br>
gcommand -> g<br>
label -> l or simply a STRING unassigned to any keyword will be considered a label.<br>
data need not be called at all, simply designate a VAL or STRUCT and it will be assumed to be data.<br><br>
so...
 dv> plot(data&#61;m, xaxis&#61;mx, label&#61;"Frankfurter", axis&#61;x, ignore&#61;-1, iabove&#61;0.0005, separate&#61;1, style&#61;points, width&#61;3, color&#61;2)
is equivalent to:
 dv> plot(m, x&#61;mx, "Frankfurter", a&#61;x, ig&#61;-1, ia&#61;0.0005, se&#61;1, st&#61;points, w&#61;3, c&#61;2)
Do not apply these shortened keywords to structure elements, you must use the entire keyword name for structure elements.<br>
[[plot|Back to plot()]]