;+
; 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.
;         
;         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 window without restarting.
; 
;         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'
;                     .....
;         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.
;
;         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: 2008-07-28 11:52:58 -0700 (Mon, 28 Jul 2008) $
; $LastChangedRevision: 3310 $
; $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/ssl_general/trunk/tplot/tplotxy.pro $
;-

;main function
pro tplotxy, vectors, title=title,overplot=overplot,addpanel=addpanel,multi=multi, usetrange=usetrange,$
             notrange=notrange,sort=sort,colors=colors,units=units,reverse_time=reverse_time,xtick_get=xtick_get,$
             ytick_get=ytick_get,_extra = _extra

compile_opt idl2

@tplot_com.pro

;handle replot case
if ~keyword_set(vectors) then begin
   plotxy
   return
endif

;if(size(vectors, /type) ne 7) then message,'must be passed a valid tplot variable'

if not keyword_set(overplot) then overplot = 0

names = tnames(vectors)

if n_elements(names) eq 1 && names eq '' then message, 'tplot variable specified does not exist'

if n_elements(names) gt 1 then begin
   
   ;handle multiple variables stored as one tvar
   for i = 0,n_elements(names)-1 do begin

      if (i eq 0) && ~keyword_set(overplot) then begin 
         op = 0 
      endif else begin
         op = 1
      endelse

      if (i gt 0) && keyword_set(addpanel) then begin
         add = 0
      endif else if keyword_set(addpanel) then begin
         add = 1
      endif

      if (i gt 0) && keyword_set(multi) then begin
         
         if keyword_set(mlt) then temp = temporary(mlt) ;unset mlt
         
      endif else if keyword_set(multi) then begin
         mlt=multi
      endif

      
      if keyword_set(colors) then begin
         if n_elements(colors) ne 1 then begin
            cols = colors[i]
         endif else begin
            cols = colors
         endelse
      endif


       tplotxy, names[i], title=title,overplot=op,addpanel=add,multi=mlt,usetrange=usetrange,$
                notrange=notrange,sort=sort,colors=cols,units=units,reverse_time=reverse_time,$
                xtick_get=xtick_get,ytick_get=ytick_get,_extra = _extra

    endfor

    return

 endif

 get_data, vectors, data = d, limit=l,dlimit = dl

 if(size(d,/type) eq 7) then begin
    if n_elements(d) eq 1 then d = strsplit(d,' ',/extract)
          
     ;handle multiple variables stored as one tvar
    for i = 0,n_elements(d)-1 do begin

       if (i eq 0) && ~keyword_set(overplot) then begin 
          op = 0 
       endif else begin
          op = 1
       endelse
       
       if (i gt 0) && keyword_set(addpanel) then begin
          add = 0
       endif else if keyword_set(addpanel) then begin
          add = 1
       endif
       
       if (i gt 0) && keyword_set(multi) then begin
          
          if keyword_set(mlt) then temp = temporary(mlt) ;unset mlt
          
       endif else if keyword_set(multi) then begin
          mlt=multi
       endif

       
       if keyword_set(colors) then begin
          if n_elements(colors) ne 1 then begin
             cols = colors[i]
          endif else begin
             cols = colors
          endelse
       endif

       tplotxy, d[i], title=title,overplot=op,addpanel=add,multi=mlt, usetrange=usetrange,$
                notrange=notrange,sort=sort,colors=cols,reverse_time=reverse_time,xtick_get=xtick_get,$
                ytick_get=ytick_get,_extra = _extra
        
   endfor
   
   return

endif

if ((keyword_set(tplot_vars) && keyword_set(tplot_vars.options) && keyword_set(tplot_vars.options.trange)) $
    || keyword_set(usetrange)) && not keyword_set(notrange) then begin
   
   tr =  timerange(/current)

   id = where(d.x ge tr[0] and d.x le tr[1])
   
   if(id[0] eq -1) then begin
     dprint, 'no data available in current timerange'
     return
   endif
   
   n =  size(d.y, /dimensions)

   tm = d.x[id]
   
   if(n_elements(n) eq 2) then vecs = d.y[id, *]
   
   if(n_elements(n) eq 3) then vecs = d.y[id,*, *]
   
endif else begin 
   vecs = d.y
   tm = d.x
endelse

if keyword_set(reverse_time) then begin
   sort = 1
endif

if keyword_set(sort) then begin

   s = size(vecs,/dimensions)
   
   if n_elements(tm) ne s[0] then message,'number of elements in tvar times does not match number of elements in tvar values'

   idx = sort(tm)
   
   tm = tm[idx]

   vecs = vecs[idx,*]
   
endif

if keyword_set(reverse_time) then begin

   vecs = reverse(vecs)

endif
   

if(keyword_set(colors)) then begin
   cols = colors 
endif else begin 

   if keyword_set(dl) then begin

      str_element,dl,'colorsxy',SUCCESS=s

      if s then cols = dl.colorsxy

   endif
   
   if keyword_set(l)  then begin 
   
      str_element,l,'colorsxy',SUCCESS=s

      if s then cols = l.colorsxy

   endif

endelse

;the tplot ytitle is typically more 
;appropriate as the tplotxy title
if(keyword_set(title)) then begin
   titl = title 
endif else begin 

   if keyword_set(dl) then begin

      str_element,dl,'ytitle',SUCCESS=s

      if s then titl = dl.ytitle

   endif
   
   if keyword_set(l)  then begin 
   
      str_element,l,'ytitle',SUCCESS=s

      if s then titl = l.ytitle

   endif

endelse


;the tplot ytitle is typically more 
;appropriate as the tplotxy title
if(keyword_set(units)) then begin
   uni = units 
endif else begin 

   if keyword_set(dl) then begin

      str_element,dl,'ysubtitle',SUCCESS=s

      if s then uni = dl.ysubtitle

   endif
   
   if keyword_set(l)  then begin 
   
      str_element,l,'ysubtitle',SUCCESS=s

      if s then uni = l.ysubtitle

   endif

endelse


if keyword_set(dl) then begin

   str_element,dl,'labels',SUCCESS=s

   if s then labels = dl.labels

endif
   
if keyword_set(l)  then begin 
   
   str_element,l,'labels',SUCCESS=s

   if s then labels = l.labels
   
endif

plotxy,vecs,overplot=overplot,addpanel=addpanel,multi=multi,title=titl,colors=cols,units=uni,labels=labels,$
  xtick_get=xtick_get,ytick_get=ytick_get,_extra=_extra

end
