;+
; NAME:
; sixplot
;
;
; PURPOSE:
; Produce a 6plot as defined in the NIST engineering statistics handbook
; http://www.itl.nist.gov/div898/handbook/eda/section3/6plot.htm
; The 6-plot is a collection of 6 specific graphical techniques whose 
; purpose is to assess the validity of a Y versus X fit. The fit can
; be a linear fit, a non-linear fit, a LOWESS (locally weighted least
; squares) fit, a spline fit, or any other fit utilizing a single
; independent variable.
;
; The 6 plots are: 
;
;   1. Scatter plot of the response and predicted values versus the independent variable;
;   2. Scatter plot of the residuals versus the independent variable;
;   3. Scatter plot of the residuals versus the predicted values;
;   4. Lag plot of the residuals;
;   5. Histogram of the residuals;
;   6. Normal probability plot of the residuals. 
;
; CATEGORY:
; Statistics
;
;
; INPUTS:
; X: X-values to use for 6plot
; Y: Y-values to use for 6plot
;
;
; KEYWORD PARAMETERS:
; COLORNAME: Name of the color to plot with, see fsc_color()
; BACKNAME: Name of the background color, see fsc_color()
; _EXTRA: Extra keywords to plot, oplot, and histoplot
;
; OUTPUTS:
; the NIST 6-plot
;
;
; RESTRICTIONS:
; Residuals are calculated using regress()
;
;
; EXAMPLE:
; IDL> x = findgen(101)
; IDL> x = x[sort(randomu(seed, 101))]
; IDL> y = x+5+randomn(seed,  101)
; IDL> sixplot, x, y                          
;
; MODIFICATION HISTORY:
;
;-
PRO sixplot, x, y, $
   COLORNAME = colorname, $
   BACKNAME = backname, $
   _EXTRA = _extra

  IF n_elements(colorname) NE 0 THEN $
     color = fsc_color(colorname,  0) ELSE $
        colorname = 'white'   
  
  IF n_elements(backname) EQ 0 THEN $ 
     backname = 'black' ELSE $
        back = fsc_color(backname, 1)

reg = regress(x, y, yfit = yfit)
res = y-yfit

pmulti = !p.multi
!p.multi = [0, 3, 2]
plot, x, yfit, $
        xtitle = 'X',  $
      ytitle = 'Predicted Y', $
        psym = 1, $
        color = fsc_color(colorname), $
        back = fsc_color(backname), $
        _EXTRA = _extra

plot, x, res, $
        xtitle = 'X',  $
      ytitle = 'Residuals', $
        psym = 1, $
        color = fsc_color(colorname), $
        back = fsc_color(backname), $
        _EXTRA = _extra

plot, yfit, res, $
        xtitle = 'Predicted Y',  $
      ytitle = 'Residuals', $
        psym = 1, $
        color = fsc_color(colorname), $
        back = fsc_color(backname), $
        _EXTRA = _extra

plot, res, res[1:*], $
        xtitle = 'RES!li-1',  $
      ytitle = 'RES!li', $
        psym = 1, $
        color = fsc_color(colorname), $
        back = fsc_color(backname), $
        _EXTRA = _extra

  histoplot, res, $
             /fill, $
             xtitle = 'Residuals', $
             AXISCOLOR = colorname, $
             DATACOLOR = colorname, $
             BACKCOLOR = backname,  $
             _EXTRA = _extra
  

normal_prob_plot, res, $
                    /blom,  $
                    color = fsc_color(colorname), $
                    back = fsc_color(backname), $
                    _EXTRA = _extra
  


!p.multi = pmulti

end