Procedure: tplotxy Purpose: Takes a tplot variable containing an array of 3-d(Nx3) vectors or and plots them using 2-d plots to help visualize them. It can also take a tplot variable storing an MxNx3 array. This represents N times and M different sets of 3-d vectors. (For example M different magnetic field lines during some interval) This routine will check the current timespan and only display values within the specified range(this entails clipping on the N dimension). If no range is specified by argument or timespan it will use the entire interval. If the noisotropic keyword is not used the plot will be made so that one unit of x is the same length on the screen as one unit of y Can also accept an Nx2 or an MxNx2 element array(in a tvar)...if this is done the versus argument should not use a custom designation or the z-axis, as it assumes 2-d vectors are in the x-y plane, and thus will distort the vectors upon projection. plotxy/tplotxy plots can be interleaved on the same window with plotxyz plots Calling tplotxy with no arguments to redraw the entire window(including plotxyz plots) *************************************************** Using custom axes: If you use two vectors to define custom axes, the procedure will generate a plot of the data vectors projected into a plane defined by the span of the two custom vectors. The x-axis will be the first vector, the y axis will be the second vector. This means that if the custom vectors are not orthogonal the plot will show a distortion. You can think of this as plotting along a plane that slices though the 3-d space. ******************************** Plot windows and panels: using, /overplot,/addpanel,/noisotropic and multi= To put multiple panels in a window first call plotxy 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. 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. 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 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. This program will also set some options using the dlimits and limits of the tplot variable, if they have not already been explicitly set by the user. If the tag 'colorsxy' is set to a color index in either the limits or dlimits of a tplot variable, it will be read to set a default line color. The 'ytitle' tag from a dlimits or limits structure will be used as the plot title If the 'ysubtitle' tag is set, it will be used as the units for the xtitle and ytitle of the tplotxy panel If the 'labels' tag is set, then the appropriate dimension lable will be used. For example 'Bx','By','Bz' labels for FGM will be used if plotted NOTE TO PROGRAMMERS: Information about plotting for plotxy 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 plotxyz function so spectrographic xyz plots can be interleaved with xy line plots. Example: tplotxy,'thb_state_pos' tplotxy,'thb_state_pos',versus='yzr' tplotxy,'thb_state_pos',versus='cc',custom=transpose([[1,1,0],[0,0,1]]) tplotxy,'thb_state_pos',versus='xryz',xrange=[0,10],yrange=[0,10] NOTE: This procedure can accept arguments that are documented only in plotxy. It will pass them through when it calls that routine using keyword inheritance. So if you can't find a useful option here, I would recommend looking there. Inputs: vectors: The name of a tplot variable that stores the list of vectors versus(optional): specify the projection to be used, can be 'xx','xy','xz','yx','yy','yz','zx','zy','zz','cc' you can also follow a letter with an 'r' to reverse the axis(goes from positive to negative instead of from negative to positive) if you specify 'cc','crc'...that indicate you want to use a custom projection example: 'xry' will be an xy plot with the maximum x value listed on the left and the minimum on the right (default:'xy') custom(optional): set this variable to a 2x3 matrix whose columns define a plane in 3-d space, to define a custom projection. In other words the 2-d plot will be a plot of the vectors passed into tplotxy when they are projected into a plane defined by span(custom[0,*],custom[1,*]). (span is defined as the set of all the linear combinations of two vectors, or span(x,y) = {mx+ny:m = element of the reals, n = element of the reals} The vectors used to define this plane will be relative to whatever 3-d coordinate system the input vector data is in. So if the call: tplotxy,'somedata',versus='cc',custom=transpose([[1,1,0],[0,0,1]) is made, the plot generated will be of the vectors closest to the data vectors that are inside a vertical plane whose intersection with the x-y plane forms a line y=x. tplotxy,'somedata',versus='cc',custom=transpose([[1,0,0],[0,1,0]) is effectively the same as: tplotxy,'somedata',versus='xy' overplot(optional): set this keyword if you want to plot on the last plot and panel that you plotted on addpanel(optional): set this keyword if you want to plot on a new panel within the same plot window as where you last plotted. This will go to the next column first and if it is at the end of a row, to the next row. multi(optional): set this keyword to a string that specifies the layout of panels within a plotwindow. Set this keyword only the first time you call tplotxy for a given plotwindow. Each time you set it, the previous contents of the window will be erased. You can separate the two elements with a variety of different delimiters The first element is cols left to right, the second rows top to bottom. Append an 'r' to the elements to have it reverse the direction of panel application Examples: multi= '2 3' multi= '5r,7' multi=' 1:6r' ..... mmargin(optional, 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(optional, 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(optional, 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. noisotropic(optional): set this keyword if you don't want the scaling of both axes to be the same and the space to be perspective corrected so that a cm of y unit takes up the same space on the screen as a cm of x unit memsave(optional): set this keyword to request command copies not be saved and redraws be done without maintaining square isotropic plots. Setting this option can potentially save quite a lot of memory. linestyle(optional):set this to change the linestyle used 0 = default,1=dotted=,2=dashed,3=dash dot,4=dash dot dot,5=long dashes xrange(optional): set this to a 2 element array to specify the min and max for the first axis(x) of the 2-d plot yrange(optional): set this to a 2 element array to specify the min and max for the second axis(y) of the 2-d plot xmargin(optional):set this to a 2 element array to specify the left and right margin for the plot unlike tplot & plot this is specified in terms of the proportion of available space given the plot layout not number of characters. This also specified for each plot in a panel individually, no for the whole panel to allow the user more control over layout. ymargin(optional):set this to a 2 element array to specify the bottom and top margin for the plot unlike tplot & plot this is specified in terms of the proportion of available space given the plot layout not number of characters. This also specified for each plot in a panel individually, no for the whole panel to allow the user more control over layout. pstart(optional): set this keyword to a number representing the symbol you would like to start lines with. (This works like the idl psym keyword, but only for the first symbol in a line being plotted) pstop(optional): set this keyword to a number representing the symbol you would like to end lines with. (This works like the idl psym keyword, but only for the last symbol in a line being plotted) psym(optional): use this to plot using a symbol rather than a line. symsize(optional): specify the size of the start and end symbol, or psym (default:1.0) WARNING!!! Using any of the 4 windowing options below will interfere with the creation of postscript graphics window(optional):specify the window for output. (default:current) xsize(optional):specify the xsize of the window in pixels(default: current) ysize(optional):specify the ysize of the window in pixels (default: current) wtitle(optional):the title you would like the window to have usetrange(optional):set this keyword(ie /usetrange) if you want it to prompt for a timerange if one is not provided by timespan notrange(optional):set this keyword(ie /notrange) if you want it to ignore the time range and use the entire sequence of values regardless. sort(optional): set this keyword(ie /sort) if you want it to sort points on time colors(optional): set this keyword to override the color information stored in the limits or dlimits of the tplot variable, if the tplot variable contains an Nx3 array it should contain a single element, if it contains an MxNx3 array it should contain one or M colors. If the tplot variable contains wildcards or is composite it will be ignored. xlog(optional): set the x scale to be logarithmic ylog(optional): set the y scale to be logarithmic xtitle(optional): set the xtitle for the plot ytitle(optional): set the ytitle for the plot grid(optional): set this to 1 to have the procedure generate a grid rather than normal tickmarks markends(optional): set this if you want to mark the very edges of your plot axis with data labels. This means the numerical values of the maximum x tick,minimum x tick, maximum y tick, and minimum y tick will be marked.Note that an extra blank page may be created in any postscripts you generate when using this option. reverse_time(optional): set to have the function reverse the data according to the time axis,this will only really change which end is marked as stop and which as start units(optional): set this if you want this unit label appended to both axis titles.(This will be ignored if you set the xtitle or ytitle explictly) 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. 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. This procedure also takes normal idl keywords that effect plotting style SEE ALSO: plotxyz,plotxy,thm_crib_tplotxy,thm_crib_plotxy,thm_crib_plotxyz, plotxylib,plotxyvec $LastChangedBy: pcruce $ $LastChangedDate: 2013-08-23 17:25:01 -0700 (Fri, 23 Aug 2013) $ $LastChangedRevision: 12887 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/tplot/tplotxy.pro $