;+
; NAME:
;   lc_array [formerly acton.pro]
;
; WARNING - THIS PROGRAM STILL HAS SOME PARAMETERS AND CAPABILITIES LEFT
;   OVER FROM ITS PARENT PROGRAM THAT MAY NOT WORK IN THE REINCARNATION!
;
; PURPOSE:
;   This procedure creates a multiwindow plot showing the
;   light curve at each pixel in a 2-D region.  The input parameter is a
;   3-D array, with time being the abcissa.  By default, each plot
;   is expanded to touch its neighbors, and only the bottom row of
;   abscissas and the left column of ordinates are labeled.  Pixel
;   coordinates are written along the left and bottom axes (see optional
;   keyword XYOFF).
;   Experience has shown that a 20x20 region is about the limit of comfortable
;   readability when the actongram is plotted on a sheet of letter-size paper
;   using the PS and LS keywords.
;   Optionally, preflare profile, difference profiles, and/or line bisectors
;      may be overplotted.
;   The user may modify IDL system variables such as !X.TICKS and !X.TICKV to
;   create a satisfactory plot.
; CALLING SEQUENCE:
;   lc_array, data, index, [out, ind, wave], 
;     ry=ry, xyoff=xyoff, adjust=adjust, noerase=noerase, color=color
;     maintit=maintit, titles=titles, xyout=xyout, /keepmargin, /all_axes,
;     /ps, /ls, /print, help=help, norm=norm, scale=scale, sub=sub, bin=bin
; INPUTS:
;   data = 3-D data array.
;   index = index array
;   wave = *optional* wavelength vector or velocity vector.  If not
;      specified, data points are labeled with consecutive integers.
; OPTIONAL INPUT PARAMETERS:
;   adjust = nonzero to compensate for continuum variations when plotting
;      difference profiles.  The difference profile is moved up or down such
;      that its minimum value is plotted at 0 on the ordinate.
;   ry = ordinate range (default is from 0 [or min(data) if < 0] to max(data)).
;   xyoff = 2-element vector specifying coordinate of lower-left pixel.
;      X and Y coordinates increase to the right and upwards, respectively.
;   maintit = overall plot title (e.g., time) to be written above plots.
;   titles = individual plot titles (written inside plot region).
;   xyout = 2-element vector specifying location of individual TITLES (default
;      is to put text at upper left of plot region).
; OPTIONAL OUTPUT PARAMETERS:
;   out = selected data array
;   ind = selected index array
; KEYWORD PARAMETERS:
;   norm = switch to exposure normalize the data, index not required if
;      this is not used.
;   scale = set this keyword if you want the plots scaled globally
;   sub = set this to display and select sub array of data
;   bin = rebin factor for selection of sub array for easy viewing
;   noerase = do not erase the screen before plotting, default is to erase.
;   color = sets color of plots, default is color=255
;   keepmargin = set to *not* expand plot to maximum area.
;   all_axes = set to label all axes, not just the abscissas of the bottom row
;      and the ordinates of the left-hand column.
;   ps = set for PostScript output
;   ls = set for PostScript output with landscape orientation
;   print = set to automatically print PostScript file (if /PS or /LS selected).
;      The file (idl.ps) is *not* automatically deleted.
;   help = set to display calling sequence summary (procedure is not executed)
; MODIFICATION HISTORY:
;   Original routine (BISEC.PRO) written by J-P Wuelser. [version 1.0]
;   1991 Sep 04: XBISEC, YBISEC and TITLES keywords added by J-F de La
;                Beaujardiere. [1.1]
;   1991 Sep 09: Documentation block (";+" to ";-") added; HELP and XYOUT
;                keywords added; T keyword replaced by MAINTIT. (JdLB) [1.2]
;   1991 Sep 10: OUTSIDE_AXES keyword added and default axis labeling scheme
;                established. (JdLB) [1.3]
;   1991 Sep 12: Function of BI keyword modified to specify linestyle. (JdLB)
;                [1.3.1]
;   1991 Sep 18: COL keyword added. (JdLB) [1.4]
;   1991 Nov 21: PRINT keyword added. (JdLB) [1.5]
;   1991 Dec 10: Plotting order corrected to yield proper orientation.
;                Labeling of pixel coordinates, and XYOFF keyword, added.
;                COL keyword removed.  KEEPMARGIN keyword added.  WAVE
;                argument made optional. (JdLB) [1.6]
;   1992 Jan 10: PFDATA, PREFLARE and DIFF keywords added. (JdLB) [1.7]
;   1992 Jan 30: Handling of axis tick names improved. (JdLB) [1.7.1]
;   1992 Apr 20: ADJUST keyword added. (JdLB) [1.8]
;   1992 Sep 22: Function of DIFF and PREFLARE keywords modified to specify
;                linestyle.  LS keyword modified to not require PS keyword.
;                (JdLB) [1.8.1]
;   1992 Oct 05: ADJUST keyword modified to merely move the difference profile
;                such that its minimum falls at 0. (JdLB) [1.8.2]
;   1992 Oct 28: Adapted to plot an array of single pixel light curves
;                (LWA)
;-


PRO lc_array, data, index, out, ind, wave, $
    ry=ry, xyoff=xyoff, adjust=adjust, noerase=noerase, color=color, $
    maintit=maintit, titles=titles, xyout=xyout, keepmargin=keepmargin, $
    all_axes=all_axes, ps=ps, ls=ls, print=print, help=help, norm=norm, $
    scale=scale, sub=sub, bin=bin

on_error, 2  ;return to caller if error occurs

; Display calling sequence summary if requested
if (keyword_set(help)) then begin
   print, 'This procedure creates an actongram of a 3-D array.'
   print, 'CALLING SEQUENCE:'
   print, '   acton, data, [wave], pfdata=pfdata, preflare=preflare, diff=diff,'
   print, '      bi=bi, xbisec=xbisec, ybisec=ybisec, ry=ry, xyoff=xyoff,'
   print, '      adjust=adjust, maintit=maintit, titles=titles, xyout=xyout,'
   print, '      /keepmargin, /all_axes, /ps, /ls, /print, help=help'
   return
endif

ddata = data
out = ddata

if (NOT keyword_set(bin)) then bin=1 else bin=bin
;select subimg
if keyword_set(sub) then begin
  subimg, data, index, ddata, dindex, bin=bin
  out = ddata
  ind = dindex
endif

; Check structure of DATA argument
si = size(ddata)
if (si(0) NE 3) then begin
   print, '>>DATA array must be 3-D'
   return
endif

nwave=si(3)
lastwave = nwave - 1

; Exposure normalize data array
if keyword_set(norm) then begin
  ddata = exp_norm(ddata,index)
endif

; set color of plots
if (NOT keyword_set(color)) then color=255 else color=color

; Check optional WAVE argument
if n_elements(wave) EQ 0 then begin
   wave = indgen(nwave)  ;label wavelength axis with integers
endif

; Check preflare arguments
if ((n_elements(preflare) GT 0) OR (n_elements(diff) GT 0)) then begin
   if (n_elements(pfdata) EQ 0) then begin
      message, 'PFDATA must be provided if /PREFLARE or /DIFF are specified.'
      return
   endif
   if (total(size(pfdata)-si) NE 0) then begin
      message, 'PFDATA must be same size as DATA.'
      return
   endif
endif

; Define default parameters
if (n_elements(ry) ne 2) then ry=[min([0,min(ddata)]),max(ddata)]
if (n_elements(xyoff) EQ 0) then xyoff=[0,0]
if (n_elements(xyoff) EQ 1) then begin
   message, /info, 'XYOFF must be 2-dimensional--using (0,0) default instead.'
   xyoff=[0,0]
endif
if (n_elements(titles) eq 0) then titles=strarr(si(2),si(3))

; Save system variables
xsave = !x
ysave = !y
psave = !p

; Set up PostScript output
if (keyword_set(ps)) then begin
   old_device = !d.name  ;save current device
   set_plot, 'ps'
   device,/portrait,/inch,xs=6.5,xo=1.0,ys=9.0,yo=1.0
endif
if (keyword_set(ls)) then begin
   old_device = !d.name  ;save current device
   set_plot, 'ps'
   device,/landscape,/inch,xs=9.0,xo=1.0,ys=6.5,yo=10.0
endif

; Set up default ordinate labeling
;;;if min(wave) le -5.0 and max(wave) ge 5.0 then begin
;;;   xticks = 2
;;;   xtickv = [-5.0,0.0,5.0]
;;;endif else begin
;;;   xticks = 1
;;;   xtickv = [wave(0),wave(nwave-1)]
;;;endelse

; Expand plots so that they touch each other
if (NOT keyword_set(keepmargin)) then begin
   !x.margin = [0,0]
   !y.margin = [0,0]
endif

!x.style = 1
;;;!x.ticks = xticks
!x.range = [min([wave(0),wave(nwave-1)]),max([wave(0),wave(nwave-1)])]
!x.minor = -1
;;;!x.tickv = xtickv
;;;!x.tickname = [' ',' ',' ']

!y.style = 1
;;;!y.ticks = 1

; Globally scale or do not scale individual pixel plots.
if keyword_set(scale) then begin
  !y.range = ry
endif

!y.minor = -1
;;;!y.tickv = [0,ry(1)]
;;;!y.tickname = [' ',' ']

; Determine location of individual title strings
if (n_elements(xyout) NE 2) then begin
   xyout = fltarr(2)
   xyout(0) = (!x.range(1)-!x.range(0))*0.1 + !x.range(0)
   xyout(1) = (!y.range(1)-!y.range(0))*0.8 + !y.range(0)
endif

; Put multiple plots on page
if (NOT keyword_set(noerase)) then nxny=0 else nxny=si(1)*si(2)
    !p.multi = [nxny,si(1),si(2),0,0]

; Generate plots
  for j = si(2)-1, 0, -1 do begin  ;plot top row first, as in !p.multi order
  for i = 0, si(1)-1 do begin

      ; Determine which axes should be labeled
      ; Use default (i.e., null) or user-defined tick names by default
      ytickname = !y.tickname
      xtickname = !x.tickname
      if (NOT keyword_set(all_axes)) then begin  ;label only bottom and left
         if (i NE 0) then ytickname=[' ',' ',' ',' ',' ',' ',' ',' ',' ',' ']
         if (j NE 0) then xtickname=[' ',' ',' ',' ',' ',' ',' ',' ',' ',' ']
      endif

      ; Determine axis titles (pixel numbers)
      !x.title= '' & !y.title = ''  ;default values
      if (i EQ 0) then !y.title = string(j+xyoff(1), format='(i0)')
      if (j EQ 0) then !x.title = string(i+xyoff(0), format='(i0)')

      ; Extract flare and preflare data
      data_ij =ddata(i,j,*)
      if ((n_elements(diff) EQ 1) OR (n_elements(preflare) EQ 1)) then begin
         pfdata_ij = pfdata(*,i,j)
         diff_ij = data_ij - pfdata_ij  ;difference profile
         ; Determine continuum-variability adjustment for difference profile
         cntm_adj = 0  ;default value (no adjustment)
         if (keyword_set(adjust)) then cntm_adj = min(diff_ij)
      endif

      ; Plot line profile and possibly preflare and/or difference profiles
; ***** Here the data are plotted *******
      plot, wave, data_ij, xtickname=xtickname, ytickname=ytickname, $
                color=color
      if (n_elements(preflare) EQ 1) then oplot, wave, pfdata_ij, line=preflare
      if (n_elements(diff) EQ 1) then oplot, wave, diff_ij - cntm_adj, line=diff

      ; Print title string (ensure !p.linestyle=0 first)
      linestyle = !p.linestyle
      !p.linestyle = 0
;###      xyouts, xyout(0), xyout(1), strtrim(titles(i,j), 2), /data
      !p.linestyle = linestyle

   endfor
endfor

; Write main title by making blank plot with a title specified
if n_elements(maintit) gt 0 then begin
   !p.multi=0
   plot, indgen(10), /nodata, /noerase, xstyle=5, ystyle=5, title=maintit+'!C'
endif

; Close the output file and print file if requested
if (keyword_set(ps) OR keyword_set(ls)) then begin
   device,/close_file
   if (keyword_set(print)) then spawn,'lpr idl.ps'
   set_plot, old_device  ;restore former output device
endif

; Restore system variables
!x = xsave
!y = ysave
!p = psave
clearplot

return
end