PRO dustem_fit_intensity_example,model=model $
                                ,sed_file=sed_file $
                                ,Nitermax=Nitermax $
                                ,postscript=postscript $
                                ,fits_save_and_restore=fits_save_and_restore $
                                 ,help=help $
                                 ,wait=wait $
                                 ,verbose=verbose

;This routine is an example of how to fit an observational SED (Stokes
;I only) with DustEM and DustEMWrap. The objective is to illustrate how to use DustEMWrap
; (and not to do science -- the fit obtained by running this example is
; likely to be poor!)
;  
;For this example, the code uses the SED in the file example_SED_1.xcat,
;which is distributed in the Data/EXAMPLE_OBSDATA/ directory 
;
;The example SED has Stokes I photometric data points from SPITZER
;IRAC and MIPS and IRAS. Examples illustrating running DustEMWrap to
;fit spectral data, polarisation data and extinction data
;are provided in other _example routines in the src/idl/ directory.
  
;+
; NAME:
;    dustem_fit_intensity_example  
; PURPOSE:
;
;  This routine is an example of how to fit an observational SED
;  (Stokes I only) using DustEM and DustEMWrap. The objective is to
;  illustrate how to use DustEMWrap (and not to do science -- the fit
;  obtained by running this example is likely to be poor!)
;  
;  For this example, the code uses the SED in the file example_SED_1.xcat,
;  which is distributed in the Data/EXAMPLE_OBSDATA/ directory 
;
;  The example SED has Stokes I photometric data points from SPITZER
;  IRAC and MIPS and IRAS. Examples illustrating running DustEMWrap to
;  fit spectral data, polarisation data and extinction data
;  are provided in other _example routines in the src/idl/ directory.
; CATEGORY:
;    DustEMWrap, Distributed, High-Level, User Example
; CALLING SEQUENCE:
;    dustem_fit_intensity_example[,model=][sed_file=][,postscript=][,Nitermax=][,fits_save_and_restore=][,/help]
; INPUTS:
;    None
; OPTIONAL INPUT PARAMETERS:
;    None
; OUTPUTS:
;    None
; OPTIONAL OUTPUT PARAMETERS:
;    Plots, results structure in binary FITS table format
; ACCEPTED KEY-WORDS:
;    model = specifies the interstellar dust mixture used by DustEM
;           'MC10' model from Compiegne et al 2010 (default)
;           'DBP90' model from Desert et al 1990
;           'DL01' model from Draine & Li 2001
;           'WD01_RV5p5B' model from Weingartner & Draine 2002 with Rv=5.5
;           'DL07' model from Draine & Li 2007
;           'J13' model from Jones et al 2013, as updated in
;                 Koehler et al 2014
;           'G17_ModelA' model A from Guillet et al (2018). Includes
;                 polarisation. See Tables 2 and 3 of that paper for details.
;           'G17_ModelB' model B from Guillet et al (2018)
;           'G17_ModelC' model C from Guillet et al (2018)
;           'G17_ModelD' model A from Guillet et al (2018)
;    sed_file = string naming the path to text file in .xcat format that
;          describes the observational SED. If not set, the file
;          'Data/SEDs/sample_SED.xcat' is used.  
;    postscript = if set, final plot is saved as postscript in the
;                 current working directory
;    Nitermax = maximum number of fit iterations. Default is 5.
;    fits_save_and_restore = if set, save the fit results in a binary
;               FITS file. The code then restore this file and plots
;               the results using the saved results information.
;    help      = if set, print this help
;    wait      = if set, wait this many seconds between each step of
;                the code (for illustration purposes)
;    verbose      = if set, subroutines will run in verbose mode
; COMMON BLOCKS:
;    None
; SIDE EFFECTS:
;    None
; RESTRICTIONS:
;    The DustEM fortran code must be installed
;    The DustEMWrap IDL code must be installed
; PROCEDURES AND SUBROUTINES USED:
;    *** COMMENT AH --> is this really NONE? ****
; EXAMPLES
;    dustem_fit_intensity_example
;    dustem_fit_intensity_example,Nitermax=1,fits_save_and_restore='/tmp/mysavefile.fits'
;    dustem_fit_intensity_example,model='DBP90'
; MODIFICATION HISTORY:
;    Written by JPB Apr-2011
;    Evolution details on the DustEMWrap gitlab.
;    See http://dustemwrap.irap.omp.eu/ for FAQ and help.  
;-

IF keyword_set(help) THEN BEGIN
  doc_library,'dustem_fit_intensity_example'
  goto,the_end
END

IF keyword_set(model) THEN BEGIN
  use_model=strupcase(model)
ENDIF ELSE BEGIN
  use_model='MC10'    ;Default is the Compeigne et al (2011) model
ENDELSE

use_polarization=0   ; initialize Dustemwrap in no polarization mode 
use_window=2          ; default graphics window number to use for plotting the results
use_verbose=0
if keyword_set(verbose) then use_verbose=1

;=== Set the (model-dependent) parameters  that you want to fit (pd)
;    their initial values (iv)
;    and whether they are bounded (ulimed,llimed,llims,ulims)
;    fixed parameters (fpd) and their values (fiv) are also set here
;=== Refer to the DustEM and DustEMWrap userguides for an explanation
;    of the different grain types

CASE use_model OF
      'DBP90':BEGIN
         pd = [ $
             '(*!dustem_params).G0', $      ;G0
             '(*!dustem_params).grains(0).mdust_o_mh',$  ;PAH0 mass fraction
             '(*!dustem_params).grains(1).mdust_o_mh',$  ;VSG mass fraction
             '(*!dustem_params).grains(2).mdust_o_mh', $ ;BG mass fraction
             'dustem_plugin_continuum_2']                ;Intensity of NIR continuum
        iv =   [1.0, 4.3e-4, 4.7e-4,6.4e-3,0.001]
        Npar=n_elements(pd)
        ulimed=replicate(0,Npar)
        llimed=replicate(1,Npar)
        llims=replicate(0.,Npar)
        fpd=[] & fiv=[]
     END
      'DL01':BEGIN
         pd = [ $
             '(*!dustem_params).G0', $      ;G0
             '(*!dustem_params).grains(0).mdust_o_mh',$     ;PAH0 mass fraction
             '(*!dustem_params).grains(1).mdust_o_mh',$     ;PAH1 mass fraction
             '(*!dustem_params).grains(2).mdust_o_mh', $    ;Gra
             '(*!dustem_params).grains(3).mdust_o_mh', $    ;Gra
             '(*!dustem_params).grains(4).mdust_o_mh', $    ;aSil
             'dustem_plugin_continuum_2']                ;Intensity of NIR continuum
        iv =   [1.0,5.4e-4, 5.4e-4,1.8e-4,2.33e-3,8.27e-3,0.001]
        Npar=n_elements(pd)
        ulimed=replicate(0,Npar)
        llimed=replicate(1,Npar)
        llims=replicate(0.,Npar)
        fpd=[] & fiv=[]
      END
      'WD01_RV5p5B':BEGIN
         pd = [ $
             '(*!dustem_params).G0', $      ;G0
             '(*!dustem_params).grains(0).mdust_o_mh',$     ;PAH0 mass fraction
             '(*!dustem_params).grains(1).mdust_o_mh',$     ;PAH1 mass fraction
             '(*!dustem_params).grains(2).mdust_o_mh', $    ;Gra
             '(*!dustem_params).grains(3).mdust_o_mh', $    ;Gra
             '(*!dustem_params).grains(4).mdust_o_mh', $    ;aSil
             'dustem_plugin_continuum_2']                ;Intensity of NIR continuum
        iv =   [1.0,5.4e-4, 5.4e-4,1.8e-4,1.64e-3,6.99e-3,0.001]
        Npar=n_elements(pd)
        ulimed=replicate(0,Npar)
        llimed=replicate(1,Npar)
        llims=replicate(0.,Npar)
        fpd=[] & fiv=[]
       END
      'DL07':BEGIN
          pd = [ $
              '(*!dustem_params).G0', $      ;G0
              '(*!dustem_params).grains(0).mdust_o_mh',$     ;PAH0 mass fraction
              '(*!dustem_params).grains(1).mdust_o_mh',$     ;PAH1 mass fraction
              '(*!dustem_params).grains(2).mdust_o_mh', $    ;Gra
              '(*!dustem_params).grains(3).mdust_o_mh', $    ;Gra
              '(*!dustem_params).grains(4).mdust_o_mh', $    ;aSil
              'dustem_plugin_continuum_2']                ;Intensity of NIR continuum
        iv =   [1.0,4.97e-4, 4.97e-4,1.66e-4,2.21e-3,7.64e-3,0.001]
        Npar=n_elements(pd)
        ulimed=replicate(0,Npar)
        llimed=replicate(1,Npar)
        llims=replicate(0.,Npar)
        fpd=[] & fiv=[]
      END
      'MC10':BEGIN
; parameters of the model to fit
         pd = [ $
              '(*!dustem_params).grains(0).mdust_o_mh',$     ;PAH0 mass fraction
              '(*!dustem_params).grains(1).mdust_o_mh',$     ;PAH1 mass fraction
              '(*!dustem_params).grains(2).mdust_o_mh', $    ;amCBEx
              '(*!dustem_params).grains(3).mdust_o_mh', $    ;amCBEx
              '(*!dustem_params).grains(4).mdust_o_mh' $     ;aSilx
              ]
; initial values of the model parameters that are to be varied during the fit
         iv =   [ 7.8e-4, 7.8e-4, 1.65e-4, 1.45e-3, 6.7e-3]
        Npar=n_elements(pd)
; flags for whether the parameters are upper/lower bounded
        ulimed=replicate(0,Npar)
        llimed=replicate(1,Npar)
; lower bound value
        llims=replicate(0.,Npar)
; parameters of the model that are fixed
        fpd=[ $
          '(*!dustem_params).gas.G0' ,  $   ; ISRF intensity (multiplicative factor x G0)
          'dustem_plugin_continuum_2' $     ;intensity of NIR continuum
            ]
; values of the fixed model parameters
        fiv=[2.4, 3.e-3]
      END
     'J13':BEGIN
        pd = [ $
             '(*!dustem_params).G0', $      ;G0
             '(*!dustem_params).grains(0).mdust_o_mh',$     ;CM20 -- power law size distribution
             '(*!dustem_params).grains(1).mdust_o_mh',$     ;CM20 -- logN size distribution
             '(*!dustem_params).grains(2).mdust_o_mh', $    ;aPyM5
             '(*!dustem_params).grains(3).mdust_o_mh', $    ;aOlM5
             'dustem_plugin_continuum_2']                ;Intensity of NIR continuum
        iv =   [1.0, 1.7e-3, 6.3e-4,2.55e-3,2.55e-3,0.001]
        Npar=n_elements(pd)
        ulimed=replicate(0,Npar)
        llimed=replicate(1,Npar)
        llims=replicate(0.,Npar)
        fpd=[] & fiv=[]
     END
      'G17_MODELA':BEGIN
         pd = [ $
             '(*!dustem_params).G0', $      ;G0
             '(*!dustem_params).grains(0).mdust_o_mh',$  ;PAH0 mass fraction
             '(*!dustem_params).grains(1).mdust_o_mh',$     ;amCB_0.3333x
             '(*!dustem_params).grains(2).mdust_o_mh', $    ;aSil2001_0.3333_p20B
             'dustem_plugin_continuum_2']                ;Intensity of NIR continuum
        iv =   [1.0, 7.094483e-4, 1.319896e-3, 5.588265e-3, 0.001]
        Npar=n_elements(pd)
        ulimed=replicate(0,Npar)
        llimed=replicate(1,Npar)
        llims=replicate(0.,Npar)
        use_polarization=1
        fpd=[] & fiv=[]
      END
      'G17_MODELB':BEGIN
         pd = [ $
            '(*!dustem_params).G0', $      ;G0
             '(*!dustem_params).grains(0).mdust_o_mh',$  ;PAH0 mass fraction
             '(*!dustem_params).grains(1).mdust_o_mh',$     ;amCB_0.3333x
             '(*!dustem_params).grains(2).mdust_o_mh', $    ;aSil_0.3333_p20B
             'dustem_plugin_continuum_2']                ;Intensity of NIR continuum
        iv =   [1.0, 6.480655e-4, 1.327672e-3, 5.267745e-3, 0.001]
        Npar=n_elements(pd)
        ulimed=replicate(0,Npar)
        llimed=replicate(1,Npar)
        llims=replicate(0.,Npar)
        use_polarization=1
        fpd=[] & fiv=[]
     END
      'G17_MODELC':BEGIN
         pd = [ $
             '(*!dustem_params).G0', $      ;G0
             '(*!dustem_params).grains(0).mdust_o_mh',$  ;PAH0 mass fraction
             '(*!dustem_params).grains(1).mdust_o_mh',$     ;amCBE_0.3333x
             '(*!dustem_params).grains(2).mdust_o_mh', $    ;aSil2001_0.3333_p20B
             'dustem_plugin_continuum_2']                ;Intensity of NIR continuum
        iv =   [1.0, 6.979060e-4, 1.555919e-3, 4.366849e-3, 0.001]
        Npar=n_elements(pd)
        ulimed=replicate(0,Npar)
        llimed=replicate(1,Npar)
        llims=replicate(0.,Npar)
        use_polarization=1
        fpd=[] & fiv=[]
      END
      'G17_MODELD':BEGIN
         pd = [ $
            '(*!dustem_params).G0', $      ;G0
             '(*!dustem_params).grains(0).mdust_o_mh',$  ;PAH0 mass fraction
             '(*!dustem_params).grains(1).mdust_o_mh',$     ;amCBE_0.3333x
             '(*!dustem_params).grains(2).mdust_o_mh', $    ;aSil2001BE6pctG_0.4x
             'dustem_plugin_continuum_2']                ;Intensity of NIR continuum
        iv =   [1.0, 7.235580e-4, 1.222725e-3, 5.324418e-3, 0.001]
        Npar=n_elements(pd)
        ulimed=replicate(0,Npar)
        llimed=replicate(1,Npar)
        llims=replicate(0.,Npar)
        use_polarization=1
        fpd=[] & fiv=[]
     END
      'ELSE':BEGIN
         message,'model '+model+' unknown',/continue
         message,'Known models are MC10,DBP90,DL01,WD01_RV5p5B,DL07,J13,G17_MODELA,G17_MODELB,G17_MODELC,G17_MODELD',/continue
         stop
      END
ENDCASE
Nfix=n_elements(fpd)
if n_elements(fiv) ne Nfix then begin
   message,'Number of fixed parameters (fpd) does not equal number of initial values of fixed parameters (fiv)',/info
   stop
end

if keyword_set(wait) then begin
   message,'Finished setting dust model: '+model,/info
   wait,wait
end


;== INITIALISE DUSTEM
dustem_init,model=use_model,polarization=use_polarization
!dustem_nocatch=1
!dustem_verbose=use_verbose
!dustem_show_plot=1


;=== READ EXAMPLE SED DATA
dir=!dustem_wrap_soft_dir+'/Data/EXAMPLE_OBSDATA/'
file=dir+'example_SED_1.xcat'
IF keyword_set(sed_file) THEN file=sed_file
sed=read_xcat(file,/silent)

if keyword_set(wait) then begin
   message,'Finished reading SED data: '+file,/info
   wait,wait
end

;;=== ADJUST THE UNCERTAINTIES (FOR ILLUSTRATION)
ind=where(sed.sigmaII LT (0.2*sed.StokesI)^2,count)
IF count NE 0 THEN sed[ind].sigmaII=(0.2*sed[ind].StokesI)^2

;== SET THE OBSERVATIONAL STRUCTURE
;== sed is passed twice -- the first occurrence is the SED that you
;== wish to fit, the second occurrence is the
;== SED that you wish to visualise / plot. These are often, but not
;== always!, the same SED.
dustem_set_data,sed,sed

;== SET INITIAL VALUES AND LIMITS OF THE PARAMETERS THAT WILL BE
;== ADJUSTED DURING THE FIT
dustem_init_parinfo,pd,iv,up_limited=ulimed,lo_limited=llimed,up_limits=ulims,lo_limits=llims

;== INITIALIZE ANY PLUGINS
dustem_init_plugins,pd,fpd 

;== INITIALIZE ANY FIXED PARAMETERS FOR PLUGINS
if Nfix gt 0 then dustem_init_fixed_params,fpd,fiv

if keyword_set(wait) then begin
   message,'Finished initializing DustEmWrap, including plugins and fixed parameters',/info
   wait,wait
end

;=== INFORMATION TO RUN THE FIT
tol=1.e-16     ;fit tolerence
use_Nitermax=5 ;maximum number of iterations. 
IF keyword_set(Nitermax) THEN use_Nitermax=Nitermax

;=== INFORMATION TO MAKE THE PLOT
yr=[1.00e-4,1.00E2] ; y-axis limits
xr=[1.00E0,6.00e4] ; x-axis limits
tit='SED -- Example 1' ; plot title
ytit=textoidl('I_\nu (MJy/sr) for N_H=10^{20} H/cm^2') ; y-axis title
xtit=textoidl('\lambda (\mum)') ; x-axis title

;===  RUN THE FIT
t1=systime(0,/sec)
res=dustem_mpfit_data(tol=tol,Nitermax=use_Nitermax,gtol=gtol $
                      ,/xlog,/ylog,xr=xr,yr=yr,xtit=xtit,ytit=ytit,title=tit $
                      ,legend_xpos=legend_xpos,legend_ypos=legend_ypos $
                      ,errors=errors,chi2=chi2,rchi2=rchi2)
t2=systime(0,/sec)

if keyword_set(wait) then begin
   message,'Finished running DustEmWrap, using Niters: '+strtrim(string(use_Nitermax),2),/info
   message,'Time taken [sec]: '+sigfig(t2-t1,2,/sci),/info
   wait,wait
end
;=== MAKE THE FINAL PLOT
IF keyword_set(postscript) THEN BEGIN
    dir_ps='./'
    set_plot,'PS'
    ps_file=dir_ps+postscript
    device,filename=ps_file,/color
ENDIF
dustemwrap_plot,*(*!dustem_fit).CURRENT_PARAM_VALUES,dummy,xr=xr,/xstyle,yr=yr,/ysty,/ylog,/xlog,title=tit+' (Final fit)'
IF keyword_set(postscript) THEN BEGIN
  set_plot,'X'
  device,/close
  message,'Wrote '+ps_file,/info
ENDIF

if keyword_set(wait) then begin
   message,'Made the plot of the final results',/info
   wait,wait
end

IF keyword_set(fits_save_and_restore) THEN BEGIN
   message,'Writing out results structure: '+fits_save_and_restore,/info
   dustem_write_fits_table,filename=fits_save_and_restore,help=help
;=== at this point, you could erase all dustem system variables, or exit idl... all the
; information needed has been saved in the FITS table
  dustem_read_fits_table,filename=fits_save_and_restore,dustem_spectra_st=dustem_spectra_st
  ;==== plot result taken from the saved fits table
  res=*(*!dustem_fit).CURRENT_PARAM_VALUES
  dustemwrap_plot,res,dustem_spectra_st,xr=xr,/xstyle,yr=yr,/ysty,/ylog,/xlog,title=tit+' (From Saved FITS file)'
  if keyword_set(wait) then begin
     message,'Saved the results as FITS in the file: '+fits_save_and_restore+', and made a plot using the data in this file',/info
     wait,wait
  end
ENDIF

message,'Finished dustem_fit_intensity_example',/info

the_end:

END