; docformat = 'rst'

;+
; Create a theme river style plot.
;
; :Examples:
;    See the main-level program at the end of this file::
; 
;       IDL> .run mg_themeriver
; 
;    This will produce a result like .. image:: themeriver.png
;
; :Params:
;    x : in, required, type=fltarr(n)
;       x-coordinates of data
;    data : in, required, type="fltarr(nlines, n)"
;       multiple y-coordinates of data values (nlines number of datasets)
;    colors : in, required, type=bytarr(nlines - 1)
;       colors of shaded regions between datasets (starting from the bottom)
;
; :Keywords: 
;    show_lines : in, optional, type=lonarr
;       indices of dataset lines in data to overplot
;    axis_color : in, optional, type=color
;       color of axis
;    color : in, optional, type=color
;       color of lines
;    _extra : in, optional, type=keywords
;       keywords to plot (for axis) and oplot (for dataset lines overplotted)
;-
pro mg_themeriver, x, data, colors, show_lines=showLines, $
                   axis_color=axisColor, color=color, _extra=e
  compile_opt strictarr

  sz = size(data, /structure)
  nlines = sz.dimensions[0]

  myShowLines = n_elements(showLines) eq 0L ? -1L : showLines

  if (nlines - 1L ne n_elements(colors)) then begin
    message, 'incorrect number of colors'
  endif

  mind = min(data, max=maxd)
  
  ; setup the coordinate system
  plot, x, x, yrange=[mind, maxd], xstyle=9, ystyle=8, /nodata, $
        color=axisColor, _extra=e

  xvert = [x,  reverse(x), x[0]]  
  for line = 0L, nlines - 2L do begin
    yvert = [reform(data[line, *]), $
             reverse(reform(data[line + 1L, *])), $
             data[line, 0L]]
    polyfill, xvert, yvert, color=colors[line]
  endfor

  for line = 0L, nlines - 1L do begin
    ind = where(myshowlines eq line, show)
    if (show gt 0L) then begin
      oplot, x, data[line, *], color=color, _extra=e
    endif
  endfor  
  
  ; repeated so that the axis is *above* the filled regions
  plot, x, x, yrange=[mind, maxd], xstyle=9, ystyle=8, /nodata, $
        color=axisColor, _extra=e, /noerase  
end

; example using a theme river plot

n = 360
x = findgen(n) * !dtor
r = randomu(seed, n)
r = smooth(r, 5, /edge_truncate)
y = x * sin(x)
data = fltarr(7, n)
data[0, *] = y - 3 * r - 0.1
data[1, *] = y - 2 * r - 0.1
data[2, *] = y - r - 0.01
data[3, *] = y
data[4, *] = y + r + 0.1
data[5, *] = y + 2 * r + 0.1
data[6, *] = y + 3 * r + 0.1

mg_loadct, 16
tvlct, rgb, /get
rgb = rgb[[50, 90, 130], *]
colors = mg_rgb2index(rgb)
colors = [colors, reverse(colors)]

window, title='Theme river example', /free, xsize=600, ysize=300

device, get_decomposed=odec
device, decomposed=1

mg_themeriver, x, data, colors, show_lines=3, $
               color='000000'x, thick=2, linestyle=2, $
               ticklen=0.01, background='FFFFFF'x, axis_color='000000'x
               
device, decomposed=odec

end