Procedure: plotxyz Purpose: Generates an isotropic spectrographic plot. It takes one 2-d array(Z) and plots it using the values in 2 1-d arrays(X,Y) to scale the data in Z. The X and Y axes can be any kind of data, most specifically the X axis need not be time. By default the plots, are scaled isotropically. Meaning that a unit on the x axis will have the same length on the screen as a unit on the z axis. The plots can be interleaved with plotxy/tplotxy plots in the same panel/window. Calling plotxyz with no arguments will redraw the entire window(including plotxy/tplotxy plots) The most significant restiction to this function is that it will clip any negative(or 0) data(in X,Y or Z) if you select a logarithmic axis. If one scaling axis is set to logarithmic and the other is not, but the plot is set to isotropic, 1 power unit on the logarithmic axis will take up the same space on screen as one normal unit on the normal axis. Despite the capability to perform these mixed x,y log plots, this is not recommended...but feel free to experiment. ************************************ Detailed explanation of Plot windows and panels: /addpanel,/noisotropic and multi= To put multiple panels in a window first call plotxyz with the multi keyword. It will either plot in which ever window is your current one, or create a new one if no window exists or if you request the use of a nonexistent window. During this first call you may want to specify things like wtitle,xsize,ysize,window...in addition to your normal plotting options, setting these windowing options will interfere with the creation of postscript multi specifies the plot window panel layout. So if you set multi='3,2' you will get 6 plots in your window with a layout like: ------- |x x x| |x x x| ------- Each panel will have dimensions x number of pixels = 1/3 * xsize of window and y number of pixels = 1/2 * ysize of window. Your first call should also specify the layout of your first panel. To add to that panel use the /overplot keyword. If you wish to add an overall title and/or margins to your multi panel window your first call should also specify mtitle and/or mmargin. When you use the /add keyword the program will move on to the next panel within the plot window and you should add options to specify the layout of that panel. If you set the xmargin or ymargin keyword the margin will be relative to the overall size of that panel. When using the not using the noisotropic keyword the procedure will make each axis vary over the same range AND make the largest possible square window given the size of the panel and the sizes of the margins you have provided, if possible. In some cases when ranges are set explictly the plot must be rectangular. An entire plot window must be filled in sequence, if you move on to a new window you will not be able to go back to the previous panel without restarting. It is possible use a panel out of sequence by setting mpanel. mpanel also allows you to create non symmetric layouts by creating plots that take up more than one panel. If you call plotxyz with no arguments it will redraw the entire window including all panels and overplots. If you resize the window before calling with new arguments it will redraw the isotropic panels as the largest possible squares. This comes at a cost of storing copies of the commands and data you made in memory. If you need to save memory you can call the function with the /memsave argument, but then redraws will be done using hardware and window resizes can distort isotropic plots. NOTE TO PROGRAMMERS: Information about plotting for plotxyz is stored in the global variable !TPLOTXY, this includes information about the layout of the plot window which panel it is currently working on, and the sequence of commands used to generate current plot window so that it can regenerate the plotwindow when called with no arguments. This variable also stores information used by the plotxy function so line plots can be interleaved with xyz spectrographic plots. Required Inputs: x: 1-d array specifying the scaling/spacing of the x axis This array must have the same number of elements as the 1st dimension of Z. One can think of the x coordinates of the centers of the Z array data y: 1-d array specifying the scaling/spacing of the y axis This array must have the same number of elements as the 2nd dimension of Z. One can think of the y coordinates of the centers of the Z array data z: 2-d array specifying the intensity of each element, or the height of the z-axis. This will be represented by color in the 2-d plot this procedure generates. Optional keywords: interpolate: set this argument if you want the data to be interpolated between z data. This will give the appearance of smooth gradations, although this may not exist in the data. If your Z data has blanks(NaNs), interpolation can give inaccurate results near the blanks. noisotropic: set this argument if you don't want the plot to be isotropic. If this is set the plot will fill the entire space available to it, regardless of data scaling. xistime: Set this argument to use tplot-style time formatting for x-axis labels. xlog,ylog,zlog: set any of these to create logarithmic scaling on the appropriate axis. It is recommended, but not required that if you set xlog on an isotropic plot you also set ylog. multi: as explained above set this to a string indicating the desired number of columns and rows in your window. This string can must contain 2 numbers delimited by any common delimiter character or space. the numbers may optionally be followed by an r to indicate a reversal in the direction that the plots will be added to the window. mmargin(can only be used if multi is also specified): set this keyword to a 4 element array specifying margins to be left around a multipanel plot. Element order is bottom, left, top, right. Margins are specified relative to the overall size of the window: 0.0 is no margin, 1.0 is all margin. e.g. mmargin=[0.1,0.1,0.15.0.1] mtitle(can only be used if multi is also specified): set this keyword to a string to display as a title for a multi panel plot window. This is displayed in addition to any titles specified for individual panels. If the top mmargin = 0, or has not been set then it will be set at 0.05 to allow room for the title. It is not possible to set your own font size for the mtitle. The size is chosen so that as much as possible the title fits in the top margin and is not too long for the window. Setting a larger top mmargin will increase the font size. NB: Size is fixed you are saving your plot to a postscript. ] If you require more control over the title format try leaving space using mmargin and adding your own text with idl procedure XYOUTS. mpanel(can only be used if multi is also specified): set this keyword to a string to specify which panels in a multipanel window to plot to. This allows you to create non symmetric plot layouts in a multi panel window. mpanel must contain two numbers separated by a comma (col, row) or two ranges indicated with a colon, separated by a comma. Panels are numbered starting at 0, from top to bottom and from left to right. e.g. mpanel = '0,1' will plot to panel in the first column, second row; mpanel = '0:1,0' will create a plot that takes up both the first and second columns in the first row. You cannot plot to a panel if that panel has already been used. Panels in a window are normally filled from left to right, top to bottom. You can use mpanel to place a plot out of this standard sequence. addpanel: set this keyword to make the procedure move on to the next plot in window, if you have previously set multi. If this is not set, it will generate a new plot in a clear window, if this is set and there are no more available spaces for plots an error will be generated. memsave: To allow replotting of the data when the procedure is called with no arguments, the copies of the data are stored in memory. If memsave is set these copies will not be saved and you will be unable to replot with a 0 argument call. xmargin,ymargin: Set these keyword to a 2 element array to set extra space around the plot. Margins are measured proportionally(from 0.0 to 1.0) and are separate for each plot(not global to the entire window). The arrays store the [left,right] xmargin or [bottom,top] ymargin. Default xmargin for xyz plots is [.15,.15] and ymargin is [.1,.075]. xrange,yrange,zrange: Set these keywords to a 2 element array to control the range of values to be displayed for each axis. title: set this to a string indicating the title at the top of the plot xtitle,ytitle,ztitle: set this to a string indicating the title of the appropriate axis. charsize: set this to a number to scale the character size of writing on the plot. 1.0 is the default, less than 1.0 decreases charsize, greater increases. WARNING setting window, xsize, ysize or wtitle will interfere with the creation of postscript window: specify the window in which the plots should be made. The default is the current window. If the window number does not exist one will be made xsize,ysize: Specify the number of pixels of the window you are plotting in. This can be done ahead by the user if they like, or just by stretching the window. wtitle: Specify the title for the bar at the top of the window as a string. noticks: set this if you do not want ticks on the plot (mutually exclusive with grid) grid: set this if you want a grid on your plot (mutually exclusive with noticks) Use xticks and yticks to manipulate the spacing of your grid markends: This keyword is deprecated. You can use all the normal options for plot to manipulate the position of the ticks on the axes. xtick_get,ytick_get: These behave exactly as the plot command versions, but they had to be identified explictly to ensure they would be passed through correctly. zticks: this acts like the normal x,y ticks option in idl plots. Set it to some number greater than 1 to set the number of tick marks of the z axis. It is available because draw color scale will sometimes supress all the tick marks on the z axis. ps_resolution: set the resolution, if you are using postscript (default is 150 pts/cm) no_color_scale: Set to not draw the z-axis color scale get_plot_pos=get_plot_pos: Return the normalized position of your plot. Output will be a 4-element array [x1,y1,,x2,y2] Where (x1,y1) is the lower-left corner of your plot and (x2,y2) is the top right corner of your plot. You can also use many normal plot options. NOTES: All NaN's & INFs in the x and y axes will be removed from the data. All NaN's in the z data will be replaced by the minimum value. bin2d is VERY useful for preparing data for use in this routine Be very careful when manually setting the ticks. While some options like [xy]ticks are quite safe, others can inadvertently produce inaccurate labels as idl will sometimes make assumptions about positioning of axes, by rounding off. If you plan on using [xy]tickv, or [xy]style be careful to verify that the axis labeling is working correctly. This can best be done by testing on a data set where the axes are irregularly spaced and where some of the values at the axes are irrational. SEE ALSO: plotxy,tplotxy,thm_crib_tplotxy,thm_crib_plotxy,thm_crib_plotxyz,bin2d, plotxylib,plotxyvec $LastChangedBy: pcruce $ $LastChangedDate: 2008-01-16 16:54:40 -0800 (Wed, 16 Jan 2008) $ $LastChangedRevision: 2283 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/ssl_general/trunk/tplot/tplotxy.pro $