;+
; NAME:
;  inms_plot_density_profiles  - plots one or more density profiles with altitude
;
pro inms_plot_density_profiles, $
   axProfiles, $                        ;; array of density structures
   asSpecies, $                         ;; list of species to plot
   molefraction=molefraction, $         ;; set to plot mole fraction
   samewindow=samewindow, $             ;; set to re-use window
   subtitle=subtitle, $                 ;; subtitle
   debug=debug,    $                    ;; controls additional debug diagnostics
   _extra=extra
;
; PURPOSE:
;   plots the density profiles produced by inms_make_profiles
;
; ARGUMENTS:
;  axProfiles  - an array of density structures containing the data to plot
;  asSpecies   - a list of species to plot, specified as the formula.
;                Note, capitolization is used in forming legend. 
;                Specify Ar, not AR to insure proper atomic symbols 
;
; KEYWORDS:
;  /molefraction - if present the mole-fraction is plotted 
;                  in place of the number density
;  /samewindow   - if present the current window is re-draw,
;                  if absent the plot is place
;                  in a new window
;  subtitle      - supplies a string to be added to the title
;  /debug        - if set, diagnostic information is produced
;  _extra        - any additional plotting keywords
;
;
; CHANGES:
;  30-Aug-2005  D.A. Gell - initial coding
;  13-Sep-2005  D.A. Gell   Character size setting considers value of !p.charsize
;  20-Sep-2006  DAG         Use error handler and inms_post_message
;  30-Nov-2006  DA Gell     form species label from formula using inms_idl_species_label
;-
;--------------------------------------------------------------------------------
  psave = !p
  ;; establish error handler
  ;;
  bDebugSw = keyword_set(debug)
  nError = 0
  catch, nError
  if nError ne 0 then begin
     catch, /cancel
     !p = psave
     inms_post_message, traceback=bDebugSw, console=inms_is_image() or bDebugSw
     if bDebugSw then stop
     return
  endif 


  if n_params() ne 2 then begin
     message,  'Expecting 2 parameters, found '+strtrim(n_params(), 2)
  endif 

  xPrfInfo = size(axProfiles, /structure)
  if total(xPrfInfo.n_dimensions) ne 2 then begin
     message, 'density structure array wrong shape'
  endif

  if xPrfInfo.type ne 8 then begin
     message, 'Expecting a density structure, found a '+xPrfInfo.type_name
  endif

  if keyword_set(subtitle) $
  then sTitle = '!C'+subtitle $
  else sTitle = ''
  sTitle = 'Cassini-INMS Atmospheric Composition' $
           + sTitle
  
  bMoleFraction = keyword_set(molefraction)

  asTagNames = tag_names(axProfiles[0])
  if bMoleFraction then begin
     nDataTag = where(strcmp(asTagNames, 'nMolefcn', /fold) eq 1)
  endif else begin
     nDataTag = where(strcmp(asTagNames, 'nDensity', /fold) eq 1)
  endelse 
  nSigTag = nDataTag + 1

  asColors = ['black', 'red', 'green', 'blue', 'orange', $
              'cyan', 'maroon', 'blueviolet']
  nSpecies = n_elements(asSpecies)
  ;;
  ;; determine limits
  nXmin = 1E10
  nXmax = -1E10

  inms_make_window, 'Density Profile', keyword_set(samewindow)

  for nI=0, nSpecies-1 do begin
     nIdx = where(strcmp(axProfiles[*, 0].sSpecies, asSpecies[nI], /fold), $
                  nOK)
     if nOK then begin
        nXmin = nXmin < (min(axProfiles[nIdx[0], *].(nDataTag), max=nMax)$
                         > 100)
        nXmax = nXmax > nMax
     endif 
  endfor

  if keyword_set(extra) $
  then sExtras = strjoin(tag_names(extra)) $
  else sExtras = '   '
  
  if strpos(sExtras, 'XRANGE') ge 0 then begin
     nXmin = extra.xrange[0] 
     nXmax = extra.xrange[1]
  endif

  if strpos(sExtras, 'YRANGE') ge 0 then begin
     nYmin = extra.Yrange[0] 
     nYmax = extra.Yrange[1]
  endif else begin
     nYmax = max(axProfiles[*, 0].nAlt, nYmin)
  endelse 

  anXrange = [nXmin, nXmax]
  anYrange = [nYmin, nYmax]
  
  ;; character sizes normal coordinates
  nCharSizeY = float(!d.y_ch_size)/float(!d.y_size)
  nCharSizeX = float(!d.x_ch_size)/float(!d.x_size)
  anPosition = [0.15, 0.15, 0.75, 0.85]

  plot, anXrange, anYrange, /nodata, /xlog, $
        /ynozero, position=anPosition, $
        xtitle=(bMoleFraction)?'Mixing Ratio':'Number Density (cm!U-3!N)', $
        xstyle=2, charsize=inms_set_charsize(2.0), $
        charthick=2.0, xthick=2, ythick=2, $
        ytitle='Altitude (km)', _extra=extra

  xyouts, 0.5, 0.95, /normal, $
          charsize=inms_set_charsize(2.5), align=0.5, $
          charthick=2.0, sTitle

  ;; list masses displayed
  nYpos = anPosition[3, 0] - 5 * nCharSizeY
  nXpos = anPosition[2, 0] + 2 * nCharSizeY

  xyouts, nXpos, nYpos, /normal, $
          'Legend', charsize=inms_set_charsize(2.0), $
          charthick=2.0, $
          width=nXposInc

  plots, [0, nXposInc]+nXpos, $
         [nYpos, nYpos]-0.5*nCharSizeY, /normal
  nYpos = nYpos - 2.50 * nCharSizeY

  for nI=0, nSpecies-1 do begin
     nIdx = where(strcmp(axProfiles[*, 0].sSpecies, asSpecies[nI], /fold), $
                  nOk)

     if nOK gt 0 then begin
        nJdx = where(axProfiles[nIdx[0], *].(nDataTag) gt nXmin, nOK)
        if nOK gt 1 then begin

           ;; plot measured points with std error
           sprl_plot_sym, /circle, size=1.0, /nofill
           sprl_error_plot, axProfiles[nIdx[0], nJdx].(nDataTag), $
                            axProfiles[nIdx[0], nJdx].nAlt, $
                            axProfiles[nIdx[0], nJdx].(nSigTag), $
                            /xerrorbar, $
                            color=sprl_find_color(asColors[nI mod 8]), $
                            psym=8

           ;; add to legend
        endif 
        nYpos = nYpos - 4.0 * nCharSizeY
        plots, [0, 5*nCharSizeX]+nXpos, $
               [nYpos, nYpos]+0.33 * nCharSizeY, /normal, $
               color=sprl_find_color(asColors[nI mod 8])
        
        plots, nXpos+2.5*nCharSizeX, nYpos+0.33*nCharSizeY, /normal, $
               color=sprl_find_color(asColors[nI mod 8]), psym=8
        xyouts, nXpos + 8 * nCharSizeX, nYpos, /normal, $
                inms_idl_species_label(asSpecies[nI]), $
                charsize=inms_set_charsize(2.0), $
                charthick=2.0
     endif 
  endfor 

end