##
## HOWTO
## Analyze Chandra ACIS data
##
## Weitian LI <liweitianux@gmail.com>
## Updated: 2017-02-07
##


Step-by-step guide to analyze ACIS data:

 (1) $ chandra_repro indir=. outdir=repro verbose=2
 (2) $ mkdir -p evt bkg img spc/profile mass
(??) <TODO> build 'manifest.yaml' (repro/*)
(??) <TODO> build 'results.yaml' (ra_ned, dec_ned, nh, z, etc.)
 (3) $ cd evt
     $ ln -s ../*_repro_evt2.fits .
 (4) $ clean_evt2.py
 (5) $ cd ../bkg
     $ ln -s ../evt/evt2*_clean.fits .
 (6) $ make_blanksky.py
 (7) $ ds9 evt2*_clean.fits
     Select some region on the CCD edges that are as far from the
     extended source as possible as the *local background*, then
     save to a region file: 'lbkg.reg'.
 (8) Estimate the total photon counts within the local background region:
     $ dmlist "evt2*_clean.fits[sky=region(lbkg.reg)][energy=400:8000]" blocks
     Enlarge the regions if the total photon counts are too small
     (e.g., say 2,000).
 (9) Query the redshift from NED and nH from the HEASARC nH tool
(10) $ ciao_bkg_spectra.sh reg=lbkg.reg
(11) $ xspec
     xspec> @xspec_lbkg_model.xcm
     xspec> fit
     xspec> cpd /xs
     xspec> pl l del
     xspec> @<path>/xspec_bkgcorr.tcl
(??) <TODO> Add background spectrum to manifest:
     $ manifest.py setpath bkg_spec <bkgcorr_blanksky_lbkg.pi | lbkg.pi>
(12) $ cd ../img
     $ ln -s ../evt/evt2*_clean.fits .
     $ ln -s ../bkg/bkgcorr_blanksky_lbkg.pi .  # maybe 'lbkg.pi'
(??) <TODO> create an image (0.7-2 keV) to determine the centroid
     $ event2image.py -H 2000
(13) $ ds9 evt2*_clean.fits
     Roughly select the source center and save the region as 'cstart.reg'
(??) <TODO> Calculate the X-ray centroid:
     $ calc_centroid.py -i img_c*_e700-2000.fits -V
     Check whether the calculated centroid is OK; if not, manually
     adjust the centroid position, and overwrite 'centroid.reg'
(??) <TODO> Generate regions for SBP extraction (sbprofile.reg):
     $ chandra_gensbpreg.sh evt2_c*_clean.fits <bkgd> centroid.reg sbprofile.reg
     $ manifest.py setpath sbp_reg sbprofile.reg
(??) <TODO> Generate regions for deprojected spectral analysis (rspec.reg):
     $ chandra_genspcreg.sh evt2_c*_clean.fits <bkgd> centroid.reg rspec.reg
     $ manifest.py setpath rspec_reg rspec.reg
(15) $ cd ../spc/profile
     $ ln -s ../../evt/evt2*_clean.fits .
     $ ln -s ../../bkg/bkgcorr_blanksky_lbkg.pi .  # maybe 'lbkg.pi'
     $ ln -s ../../img/rspec.reg img_rspec.reg
(16) ds9 open 'evt2*_clean.fits' with regs 'img_rspec.reg';
     adjust the regions and save as 'rspec.reg'
(18) $ ciao_deproj_spectra.sh reg=rspec.reg
(19) Fit the radial spectra to derive the radial temperature profile,
     as well as the average temperature and abundance:
     $ xspec
     xspec> @xspec_deproj.xcm
     xspec> fit
     (tweaks parameters when necessary)
     xspec> @<path>/xspec_tprofile.tcl
     (calculate average temperature and abundance)
     xspec> @<path>/xspec_avg_tz.tcl
     xspec> exit
(20) Fix 'NULL' values in 'tprofile.qdp', 'tprofile.txt' & 'tz_average.txt'
(21) $ cd ../../img;
(22) create config '<NAME>_expcorr.conf' (for batch process):
     basedir    ..
     reg        sbprofile.reg
     nh         <nh>
     z          <redshift>
     temp       <avg_temp>
     abund      <avg_abund>
(23) $ ciao_expcorr_sbp.sh basedir=.. nh=<nh> z=<redshift> temp=<avg_temp> abund=<avg_abund>

## --------------------------------------------------------
(24) $ cd ../mass
     $ ln -s ../img/sbprofile.txt .
     $ ln -s ../spc/profile/tprofile.txt .
(25) Copy the sample config files located at 'files' directory:
     * mass.conf
     * wang2012_param.txt
     * sbp_sbeta.conf
     * sbp_dbeta.conf
(26) Fill 'nH', 'abund' in 'mass.conf';
     and 'z' in 'sbp_sbeta.conf' and 'sbp_dbeta.conf'
(27) $ fittp tprofile.txt wang2012_param.txt
(28) $ qdp fit_result.qdp
     (check fitted temperature profile, and adjust parameter accordingly)
(29) $ fitsbp sbp_sbeta.conf mass.conf   # single-beta sbp
     $ fitsbp sbp_dbeta.conf mass.conf   # double-beta sbp
(30) $ qdp sbp_fit.qdp   # check fitted sbp
(31) $ ln -s sbp_sbeta.conf sbp.cfg   # use single-beta
     $ ln -s sbp_dbeta.conf sbp.cfg   # use double-beta
(32) $ fitnfw <z> [rmin_kpc]
(33) $ qdp nfw_fit_result.qdp   # check fitted nfw profile, and ajust 'rmin_kpc'
(34) Update 'nfw_rmin_kpc' in 'mass.conf
(35) $ fitmass mass.conf c    # calculate the central values
(36) $ fitmass mass.conf 2>&1 | tee mass_<date>.log    # calculate mass data
(37) Update the INFO.json with calculated values from 'final_result.txt':
     $ collect_infodata.sh
(38) $ cd ../img
     $ chandra_update_xcentroid.sh
(39) $ cd ../spc/profile
(40) $ ciao_r500avgt.sh inner=0.1 outer=0.5   # check 0.5R500 range
     $ ciao_r500avgt.sh inner=0.2 outer=0.5
(41) $ xspec
     xspec> @xspec_r500avgt_0.1-0.5.xcm
     xspec> fit; cpd /xs; pl l del;
     xspec> error 1.0 2 3
     (calculate the 1 sigma errors for temperature and abundance)
(42) update the following values in the INFO.json file:
     * 'T(0.1-0.5 R500)'
     * 'Z(0.1-0.5 R500)'
(43) repeat the above two steps for region "0.2-0.5 R500", and update
     the values of 'T(0.2-0.5 R500)' and 'Z(0.2-0.5 R500)'.

## --------------------------------------------------------
(44) $ cd ../..;  # in 'repro' dir
     $ cp -a mass lxfx; cd lxfx;
(45) $ calclxfx global.cfg c 500 200  # 'c' for center values
     $ calclxfx global.cfg 500 200  # calc 'errors'
(46) $ getlxfx . c 500 200  # for center results
     $ getlxfx . 500 200  # for all results (with errors)

## --------------------------------------------------------
(47) $ cd ..; cd spc/profile
(48) Calculate cooling time:
     $ ciao_calc_ct.sh
     check results in file 'cooling_results.txt'
(49) Calculate Csb (surface brightness concentration):
     $ ciao_calc_csb.sh
     (it will open ds9 to show the regions, modify the regions if necessary;
      and answer y/n/m to continue)
     check results in file 'csb_results.txt'