functions in graph.i - p

             palette, filename  
          or palette, source_window_number  
          or palette, red, green, blue, ntsc=1/0  
          or palette, red, green, blue, gray  
          or palette, red, green, blue, query=1  
          or palette, red, green, blue, gray, query=1  
 
     sets (or retrieves with query=1) the palette for the current  
     graphics window.  The FILENAME is the name of a Gist palette file;  
     the standard palettes are "earth.gp", "stern.gp", "rainbow.gp",  
     "heat.gp", "gray.gp", and "yarg.gp".  Use the maxcolors keyword  
     in the pldefault command to put an upper limit on the number of  
     colors which will be read from the palette in FILENAME.  
     In the second form, the palette for the current window is copied  
     from the SOURCE_WINDOW_NUMBER.  If the X colormap for the window is  
     private, there will still be two separate X colormaps for the two  
     windows, but they will have the same color values.  
     In the third form, RED, GREEN, and BLUE are 1-D arrays of the same  
     length specifying the palette you wish to install; the values  
     should vary between 0 and 255, and your palette should have no  
     more than 240 colors.  If ntsc=0, monochrome devices (such as most  
     laser printers) will use the average brightness to translate your  
     colors into gray; otherwise, the NTSC (television) averaging will  
     be used (.30*RED+.59*GREEN+.11*BLUE).  Alternatively, you can specify  
     GRAY explicitly.  
     Ordinarily, the palette is not dumped to a hardcopy file  
     (color hardcopy is still rare and expensive), but you can  
     force the palette to dump using the window or hcp_file commands.  
     See the dump= keyword for the hcp_file and window commands if you  
     are having trouble getting color in your hardcopy files.  
builtin function, documented at i0/graph.i   line 284  

             pause, milliseconds  
          or pause(milliseconds)  
 
     pause for the specified number of milliseconds of wall clock  
     time, or until input arrives from the keyboard.  
     If you call pause as a function, the return value is 1  
     if the specified number of milliseconds elapsed, or 0 if  
     keyboard input caused the pause to abort.  
     This is intended for use in creating animated sequences.  
builtin function, documented at i0/graph.i   line 1365  

             plc, z, y, x, levs=z_values  
          or plc, z, y, x, ireg, levs=z_values  
          or plc, z, levs=z_values  
 
     plots a contours of Z on the mesh Y versus X.  Y, X, and IREG are  
     as for plm.  The Z array must have the same shape as Y and X.  
     The function being contoured takes the value Z at each point  
     (X,Y) -- that is, the Z array is presumed to be point-centered.  
     The Y, X, and IREG arguments may all be omitted to default to the  
     mesh set by the most recent plmesh call.  
     The LEVS keyword is a list of the values of Z at which you want  
     contour curves.  The default is eight contours spanning the  
     range of Z.  
     See plfc if you want to color the regions between contours.  
     The following keywords are legal (each has a separate help entry):  
   KEYWORDS: legend, hide  
             type, width, color, smooth  
             marks, marker, mspace, mphase  
             smooth, triangle, region  
builtin function, documented at i0/graph.i   line 426  

             pldefault, key1=value1, key2=value2, ...  
 
     sets default values for the various properties of graphical elements.  
     The keywords can be most of the keywords that can be passed to the  
     plotting commands:  
       plg:  color, type, width,  
             marks, mcolor, msize, mspace, mphase,  
             rays, rspace, rphase, arrowl, arroww  
       pldj: color, type, width  
       plt:  color, font, height, path, justify, opaque  
       plm:  color, type, width  
       plv:  color, hollow, width, aspect  
       plc:  color, type, width,  
             marks, mcolor, marker, msize, mspace, mphase  
       plf:  edges, ecolor, ewidth  
     The initial default values are:  
       color="fg", type="solid", width=1.0 (1/2 point),  
       marks=1, mcolor="fg", msize=1.0 (10 points),  
          mspace=0.16, mphase=0.14,  
       rays=0, arrowl=1.0 (10 points), arroww=1.0 (4 points),  
          rspace=0.13, rphase=0.11375,  
       font="helvetica", height=12.0, justify="NN", opaque=0,  
       hollow= 0, aspect=0.125,  
       edges=0, ecolor="fg", ewidth=1.0 (1/2 point)  
     Additional default keywords are:  
       dpi, style, legends  (see window command)  
       palette              (to set default filename as in palette command)  
       maxcolors            (default 200)  
builtin function, documented at i0/graph.i   line 1238  

             pldj, x0, y0, x1, y1  
 
     plots disjoint lines from (X0,Y0) to (X1,Y1).  X0, Y0, X1, and Y1  
     may have any dimensionality, but all must have the same number of  
     elements.  
     The following keywords are legal (each has a separate help entry):  
   KEYWORDS: legend, hide  
             type, width, color  
builtin function, documented at i0/graph.i   line 603  

             pleb, y, x, dx=dx, dy=dy  
 
     plots Y vs. X with error bars.  
     Uncertainty on X and/or Y are specified with the dx= and dy= keywords.  
     X and Y must have same dimensions, dx= and dy= must be conformable  
     with X (or Y).  Either dx or dy may be nil for no error bar in that  
     direction.  Scalar dx or dy gives equal error bars at all points,  
     dimsof(dx)==dimsof(X), etc., gives different error bar at each point.  
     dx= and dy= may also have a trailing dimension of length 2 in order  
     to get asymmetric error bars; dx(..,1) is the lower error bar length,  
     and dx(..,2) is the upper error bar length in that case, etc.  
     If marker=, msize=, or width= is specified, markers are positioned  
     at X, Y using plmk.  Use the mfill=1 keyword to get filled markers  
     (width>=10. in plmk; width= refers to error bar width in pleb).  
   EXAMPLE:  
      x = [0, 1, 2, 3];  
      y = [0, 2, 4, 7];  
      pleb, y, x, dx=0.2, dy=[0.3, 0.4, 0.5, 0.3], mfill=1;  
         Uncertainties on dx are the same for all X, and those  
         on Y are different for each value of Y.  Filled markers  
         will be displayed at (X, Y).  
   KEYWORDS: color, width, marker, msize  
      dx     uncertainty on X  
      dy     uncertainty on Y  
interpreted function, defined at i0/graph.i   line 1790  

             pledit, key1=value1, key2=value2, ...  
          or pledit, n_element, key1=value1, key2=value2, ...  
          or pledit, n_element, n_contour, key1=value1, key2=value2, ...  
 
     changes some property of element number N_ELEMENT (and contour  
     number N_CONTOUR of that element).  If N_ELEMENT and N_CONTOUR are  
     omitted, the default is the most recently added element, or the  
     element specified in the most recent plq query command.  
     The keywords can be any of the keywords that apply to the current  
     element.  These are:  
       plg:  color, type, width,  
             marks, mcolor, marker, msize, mspace, mphase,  
             rays, rspace, rphase, arrowl, arroww,  
             closed, smooth  
       pldj: color, type, width  
       plt:  color, font, height, path, justify, opaque  
       plm:  region, boundary, inhibit, color, type, width  
       plf:  region  
       plv:  region, color, hollow, width, aspect, scale  
       plc:  region, color, type, width,  
             marks, mcolor, marker, msize, mspace, mphase  
             smooth, levs  
     (For contours, if you aren't talking about a particular N_CONTOUR,  
      any changes will affect ALL the contours.)  
     A plv (vector field) element can also take the scalem  
     keyword to multiply all vector lengths by a specified factor.  
     A plt (text) element can also take the dx and/or dy  
     keywords to adjust the text position by (dx,dy).  
builtin function, documented at i0/graph.i   line 1203  

             plf, z, y, x  
          or plf, z, y, x, ireg  
          or plf, z  
 
     plots a filled mesh Y versus X.  Y, X, and IREG are as for plm.  
     The Z array must have the same shape as Y and X, or one smaller  
     in both dimensions.  If Z is of type char, it is used "as is",  
     otherwise it is linearly scaled to fill the current palette, as  
     with the bytscl function.  
     (See the bytscl function for explanation of top, cmin, cmax.)  
     The mesh is drawn with each zone in the color derived from the Z  
     function and the current palette; thus Z is interpreted as a  
     zone-centered array.  
     As for pli and plfp, Z may also be a 3x(NX-1)x(NY-1) array  
     of char giving the [r,g,b] components of each color.  See the  
     color keyword for cautions about using this if you do not have  
     a true color display.  
     The Y, X, and IREG arguments may all be omitted to default to the  
     mesh set by the most recent plmesh call.  
     A solid edge can optionally be drawn around each zone by setting  
     the EDGES keyword non-zero.  ECOLOR and EWIDTH determine the edge  
     color and width.  The mesh is drawn zone by zone in order from  
     IREG(2+imax) to IREG(jmax*imax) (the latter is IREG(imax,jmax)),  
     so you can achieve 3D effects by arranging for this order to  
     coincide with back-to-front order.  If Z is nil, the mesh zones  
     are filled with the background color, which you can use to  
     produce 3D wire frames.  
     The following keywords are legal (each has a separate help entry):  
   KEYWORDS: legend, hide  
             region, top, cmin, cmax, edges, ecolor, ewidth  
builtin function, documented at i0/graph.i   line 510  

             plfc, z, y, x, levs=z_values  
          or plfc, z, y, x, ireg, levs=z_values  
 
     fills contours of Z on the mesh Y versus X.  Y, X, and IREG are  
     as for plm.  The Z array must have the same shape as Y and X.  
     The function being contoured takes the value Z at each point  
     (X,Y) -- that is, the Z array is presumed to be point-centered.  
     The LEVS keyword is a list of the values of Z at which you want  
     contour curves.  These curves divide the mesh into numberof(LEVS)+1  
     regions, each of which is filled with a solid color.  If LEVS is  
     nil, up to 19 "nice" equally spaced level values spanning the  
     range of Z are selected.  The level values actually used are  
     always output to the external variable plfc_levs.  
     If you specify levs=, you may also specify colors= a list of  
     colors of length numberof(LEVS)+1.  The colors should be indices  
     into the current palette.  If you do not specify them, equally  
     spaced colors are chosen.  
     The following keywords are legal (each has a separate help entry):  
   KEYWORDS: triangle, region  
interpreted function, defined at i0/graph.i   line 1582  

             plfp, z, y, x, n  
 
     plots a list of filled polygons Y versus X, with colors Z.  
     The N array is a 1D list of lengths (number of corners) of the  
     polygons; the 1D colors array Z has the same length as N.  The  
     X and Y arrays have length sum(N).  
     If Z is of type char, it is used "as is", otherwise it is linearly  
     scaled to fill the current palette, as with the bytscl function.  
     If Z is nil, the background color is used for every polygon.  
     (See the bytscl function for explanation of top, cmin, cmax.)  
     As for plf and pli, Z may also be a 3-by-numberof(N) array of  
     char giving the [r,g,b] components of each color.  See the  
     color keyword for cautions about using this if you do not have  
     a true color display.  
     As a special case, if n(2:)==1, the first polygon is assumed  
     to have NDC coordinates, while the remaining individual X and Y  
     values are in world coordinates.  The first polygon is drawn  
     numberof(n)-1 times, with its (0,0) placed at each of the  
     individual (X,Y) values in succession.  This is a hack to enable  
     plotting of more elaborate data markers than plg,type=0 -- see  
     the plmk function for details.  
     The following keywords are legal (each has a separate help entry):  
   KEYWORDS: legend, hide, top, cmin, cmax, edges, ecolor, ewidth  
builtin function, documented at i0/graph.i   line 546  

             plg, y, x  
          or plg, y  
 
     plots a graph of Y versus X.  Y and X must be 1-D arrays of equal  
     length; if X is omitted, it defaults to [1, 2, ..., numberof(Y)].  
     A keyword n=[n1,n2,n3,...nN] can be used to add N curves.  In this  
     case, sum(n) must be numberof(y).  
     The following keywords are legal (each has a separate help entry):  
   KEYWORDS: legend, hide  
             type, width, color, closed, smooth  
             marks, marker, mspace, mphase  
             rays, arrowl, arroww, rspace, rphase  
builtin function, documented at i0/graph.i   line 362  

             pli, z  
          or pli, z, x1, y1  
          or pli, z, x0, y0, x1, y1  
 
     plots the image Z as a cell array -- an array of equal rectangular  
     cells colored according to the 2-D array Z.  The first dimension  
     of Z is plotted along x, the second dimension is along y.  
     If Z is of type char, it is used "as is", otherwise it is linearly  
     scaled to fill the current palette, as with the bytscl function.  
     (See the bytscl function for explanation of top, cmin, cmax.)  
     As for plf and plfp, Z may also be a 3D array with 1st dimension 3  
     of char giving the [r,g,b] components of each color.  See the  
     color keyword for cautions about using this if you do not have  
     a true color display.  
     If X1 and Y1 are given, they represent the coordinates of the  
     upper right corner of the image.  If X0, and Y0 are given, they  
     represent the coordinates of the lower left corner, which is at  
     (0,0) by default.  If only the Z array is given, each cell will be  
     a 1x1 unit square, with the lower left corner of the image at (0,0).  
     The following keywords are legal (each has a separate help entry):  
   KEYWORDS: legend, hide, top, cmin, cmax  
builtin function, documented at i0/graph.i   line 576  

             plm, y, x, boundary=0/1, inhibit=0/1/2  
          or plm, y, x, ireg, boundary=0/1, inhibit=0/1/2  
          or plm, boundary=0/1, inhibit=0/1/2  
 
     plots a mesh of Y versus X.  Y and X must be 2-D arrays with equal  
     dimensions.  If present, IREG must be a 2-D region number array  
     for the mesh, with the same dimensions as X and Y.  The values of  
     IREG should be positive region numbers, and zero for zones which do  
     not exist.  The first row and column of IREG never correspond to any  
     zone, and should always be zero.  The default IREG is 1 everywhere  
     else.  If present, the BOUNDARY keyword determines whether the  
     entire mesh is to be plotted (boundary=0, the default), or just the  
     boundary of the selected region (boundary=1).  If present, the  
     INHIBIT keyword causes the (X(,j),Y(,j)) lines to not be plotted  
     (inhibit=1), or the (X(i,),Y(i,)) lines to not be plotted (inhibit=2).  
     By default (inhibit=0), mesh lines in both logical directions are  
     plotted.  
     The Y, X, and IREG arguments may all be omitted to default to the  
     mesh set by the most recent plmesh call.  
     The following keywords are legal (each has a separate help entry):  
   KEYWORDS: legend, hide  
             type, width, color  
             region  
builtin function, documented at i0/graph.i   line 378  

             plmesh, y, x, ireg, triangle=tri_array  
          or plmesh  
 
     sets the default mesh for subsequent plm, plc, plv, and plf calls.  
     In the second form, deletes the default mesh (until you do this,  
     or switch to a new default mesh, the default mesh arrays persist and  
     take up space in memory).  The Y, X, and IREG arrays should all be  
     the same shape; Y and X will be converted to double, and IREG will  
     be converted to int.  If IREG is omitted, it defaults to IREG(1,)=  
     IREG(,1)= 0, IREG(2:,2:)=1; that is, region number 1 is the whole  
     mesh.  The triangulation array TRI_ARRAY is used by plc; the  
     correspondence between TRI_ARRAY indices and zone indices is the  
     same as for IREG, and its default value is all zero.  
     The IREG or TRI_ARRAY arguments may be supplied without Y and X  
     to change the region numbering or triangulation for a given set of  
     mesh coordinates.  However, a default Y and X must already have been  
     defined if you do this.  
     If Y is supplied, X must be supplied, and vice-versa.  
builtin function, documented at i0/graph.i   line 405  

             plmk, y,x  
 
     Make a scatter plot of the points Y versus X.  If X is nil,  
     it defaults to indgen(numberof(Y)).  By default, the marker  
     cycles through 7 predefined marker shapes.  You may specify a shape  
     using the marker= keyword, line width using the width= keyword (you  
     get solid fills for width>=10), color using the color= keyword.  
     You can also use the msize= keyword to scale the marker (default  
     msize=1.0).  You can change the default width, color, or msize  
     using the plmk_default function.  
     The predefined marker= values are:  
     marker=  
       1        square  
       2        cross  
       3        triangle  
       4        circle  
       5        diamond  
       6        cross (rotated 45 degrees)  
       7        triangle (upside down)  
     You may also put marker=[xm,ym] where xm and ym are vectors  
     of NDC coordinates to design your own custom marker shapes.  
interpreted function, defined at i0/graph.i   line 1477  

             plmk_default, color=color, msize=msize, width=width  
 
     sets default color, msize, and width values for plmk.  Use  
     width=10 to get solid fills.  With no parameters, plmk_default  
     restores the initial default values.  
interpreted function, defined at i0/graph.i   line 1546  

             plq  
          or plq, n_element  
          or plq, n_element, n_contour  
          or legend_list= plq()  
          or properties= plq(n_element, n_contour)  
 
     Called as a subroutine, prints the list of legends for the current  
     coordinate system (with an "(H)" to mark hidden elements), or prints  
     a list of current properties of element N_ELEMENT (such as line type,  
     width, font, etc.), or of contour number N_CONTOUR of element number  
     N_ELEMENT (which must be contours generated using the plc command).  
     Called as a function, returns either the list of legend strings, or a  
     list of pointers to the values of the various element properties.  
     Elements and contours are both numbered starting with one; hidden  
     elements or contours are included in this numbering.  
     The PROPERTIES list returned by plq is a list of pointers to the  
     relevent properties for the specified graphical element.  Each  
     possible property has a particular index in the returned PROPERTIES  
     list as follows:  
     *PROPERTIES(1)   int([element type (0 for none, 1 for plg, 2 for pldj,  
                                         3 for plt, 4 for plm, 5 for plf,  
                                         6 for plv, 7 for plc, 8 for pli,  
                                         9 for plfp),  
                           hide flag])  
     *PROPERTIES(2)   string(legend)  
     *PROPERTIES(3)   int array, depends on type (names match keywords):  
       1 plg:  [color, type, marks, mcolor, marker, rays, closed, smooth]  
       2 pldj: [color, type]  
       3 plt:  [color, font, path, justify, opaque]  
       4 plm:  [color, type, region, boundary, inhibit]  
       5 plf:  [region, edges, ecolor, rgb_flag]  
       6 plv:  [region, color, hollow]  
       7 plc:  [region, color, type, marks, mcolor, marker, smooth]  
       8 pli:  nil  
       9 plfp: [edges, ecolor, rgb_flag]  
     *PROPERTIES(4)   double array, depends on type (names match keywords):  
       1 plg:  [width, msize, mspace, mphase, rspace, rphase, arrowl, arroww]  
       2 pldj: [width]  
       3 plt:  [height, x, y]  
       4 plm:  [width]  
       5 plf:  [ewidth]  
       6 plv:  [width, aspect, scale]  
       7 plc:  [width, msize, mspace, mphase]  
       8 pli:  [x0, x1, y0, y1]  
     *PROPERTIES(5)   long array, depends on type (names match arguments):  
       1 plg:  [npoints, &x, &y]  
       2 pldj: [npoints, &x0, &y0, &x1, &y1]  
       3 plt:  [nchars, &text]  
       4 plm:  [imax, jmax, &x, &y, &ireg]  
       5 plf:  [imax, jmax, &x, &y, &ireg, &colors]  
       6 plv:  [imax, jmax, &x, &y, &ireg, &vx, &vy]  
       7 plc:  [imax, jmax, &x, &y, &ireg, &z, &triangle, nlevs, &levs]  
       8 pli:  [imax, jmax, &colors]  
       9 plfp: [n, &x, &y, &colors, &pn]  
     You can use the reshape function to peek at the data at the addresses  
     returned in PROPERTIES(5) as longs.  The appropriate data types are:  
     char for text, int for ireg, short for triangle, char for colors, and  
     double for everything else.  In a plf, colors is (imax-1)-by-(jmax-1).  
     Although PROPERTIES(5) returns pointers to the data plotted, attempting  
     to poke new values into this data will not produce immediate changes  
     to your plot, since the graphics package does not realize that anything  
     has changed.  Use pledit to make changes to plotted elements.  
     The plq function always operates on the current coordinate system  
     in the current graphics window; use window and plsys to change these.  
builtin function, documented at i0/graph.i   line 1134  

             plsys, n  
          or plsys(n)   or   plsys()  
 
     sets the current coordinate system to number N in the current  
     graphics window.  If N equals 0, subsequent elements will be  
     plotted in absolute NDC coordinates outside of any coordinate  
     system.  The default style sheet "work.gs" defines only a single  
     coordinate system, so the only other choice is N equal 1.  You  
     can make up your own style sheet (using a text editor) which  
     defines mulitple coordinate systems.  You need to do this if  
     you want to display four plots side by side on a single page,  
     for example.  The standard style sheets "work2.gs" and "boxed2.gs"  
     define two overlayed coordinate systems with the first labeled  
     to the right of the plot and the second labeled to the left of  
     the plot.  When using overlayed coordinate systems, it is your  
     responsibility to ensure that the x-axis limits in the two  
     systems are identical.  
     Return value is coordinate system setting before this call;  
     input n may be nil to retrieve this without changing it.  Return  
     value can be <0 if the information is unavailable for some reason.  
builtin function, documented at i0/graph.i   line 336  

             plt, text, x, y, tosys=0/1  
 
     plots TEXT (a string) at the point (X,Y).  The exact relationship  
     between the point (X,Y) and the TEXT is determined by the  
     justify keyword.  TEXT may contain newline ("\n") characters  
     to output multiple lines of text with a single call.  The  
     coordinates (X,Y) are NDC coordinates (outside of any coordinate  
     system) unless the tosys keyword is present and non-zero, in  
     which case the TEXT will be placed in the current coordinate  
     system.  However, the character height is NEVER affected by the  
     scale of the coordinate system to which the text belongs.  
     Note that the pledit command takes dx and/or dy keywords to  
     adjust the position of existing text elements.  
     The characters ^, _, and ! are treated specially in TEXT.  
     ^ begins a superscript, _ begins a subscript, and ! causes the  
     following character to be rendered using the symbol font.  As  
     special cases, !^, !_, and !! render the ^, _, and ! characters  
     themselves.  However, if ! is the final character of TEXT  
     (or immediately before a newline in multiline text), it  
     loses its special meaning.  TEXT has just three modes: ordinary,  
     superscript, and subscript.  A ^ character enters superscript  
     mode from ordinary or subscript mode, and returns to ordinary  
     mode from superscript mode.  A _ enters subscript mode, except  
     from subscript mode it returns to ordinary mode.  For example,  
     Euclid said, "!pr^2", and Einstein said, "G_!s!n_=8!pT_!s!n".  
     One final special escape: !] produces the ^ character in the  
     symbol font (it is a perpendicular sign, whereas ] is just ]).  
     The following keywords are legal (each has a separate help entry):  
   KEYWORDS: legend, hide  
             color, font, height, opaque, orient, justify  
builtin function, documented at i0/graph.i   line 615  

             plt1, text, x, y  
 
     same as plt, but TEXT, X, and Y may be arrays to plot multiple  
     strings.  The tosys= keyword works as for plt.  
   KEYWORDS: color, font, height, opaque, orient, justify  
interpreted function, defined at i0/graph.i   line 651  

             pltitle, title  
 
     Plot TITLE centered above the coordinate system for any of the  
     standard Gist styles.  You may want to customize this for other  
     plot styles.  
interpreted function, defined at i0/graph.i   line 669  

             plv, vy, vx, y, x, scale=dt  
          or plv, vy, vx, y, x, ireg, scale=dt  
          or plv, vy, vx, scale=dt  
 
     plots a vector field (VX,VY) on the mesh (X,Y).  Y, X, and IREG are  
     as for plm.  The VY and VX arrays must have the same shape as Y and X.  
     The Y, X, and IREG arguments may all be omitted to default to the  
     mesh set by the most recent plmesh call.  
     The SCALE keyword is the conversion factor from the units of  
     (VX,VY) to the units of (X,Y) -- a time interval if (VX,VY) is a velocity  
     and (X,Y) is a position -- which determines the length of the  
     vector "darts" plotted at the (X,Y) points.  If omitted, SCALE is  
     chosen so that the longest ray arrows have a length comparable  
     to a "typical" zone size.  
     You can use the scalem keyword in pledit to make adjustments to the  
     SCALE factor computed by default.  
     The following keywords are legal (each has a separate help entry):  
   KEYWORDS: legend, hide  
             type, width, color, smooth  
             marks, marker, mspace, mphase  
             triangle, region  
builtin function, documented at i0/graph.i   line 485