***** This is a 'stand alone' reduction/extraction example of FORS1 data *****

	Here, we do not use all the Python higher-level scripts, which are
	meant to work with the SNLS-VLT spectroscopic data-base.

	The raw FITS data from one night are given in the 
	'phAse/data/rawdata_031102/' directory.
	The input Data-Cards are given in 'phAse/data/CARDS',
	the calibration frames produced are given in 'phAse/data/MASTER'
	and the extraction products are given in 'phAse/data/REDUCE'


** Run the 'setup.csh' to build the executables.
   (you need CFITSIO installed, and $CFITSIOINCDIR and $CFITSIOLIBDIR declared. 
   Also the CERN library 'lapack' must be installed, 
   and the 'cernlib' executable be under your $PATH )

** You will also need to define a $PHASEDIR environment variable
   as your '/home/username/whereis/phAse/'

** Running any executable under '$PHASEDIR/bin/' without arguments will
   display it's usage.

** All Reduction executables 'make_Nxxxx.exe' have a common syntax :
   '> bin/make_Nxxxx.exe ImgType DataCard.sof OutName [-options]',
   where 'ImgType' is the field name of the images to be treated, as
   given in the DataCard.sof.
   They create a combined and reduced 'OutName_combN.fits'.

** All Reduction executables 'make_Nxxxx.exe' have a [-v] verbose option,
   for a detailed screen output, and if it is not used, the main 
   informations are listed in a 'OutName_comb.log' text file.



   ***********    How to Use the Example Data given     ***********

** Edit all Data-Cards given under 'phAse/data/CARDS/*.sof' to replace the 
   'DATA_DIR' field with your own phAse directory
   ( also the root of the 'STD-DIR' field of the STD Data-Card ). 
   I have edited them manually to fit to the example data locations.
   The associated Master calibration images are already associated 
   in the Cards, although you should try to create them.


** Move to the phAse directory (to use the commands hereafter):
   > cd $PHASEDIR

** Run the Master Bias creation (~ 1 minute):

   > bin/make_Nbias.exe IMG_BIAS data/CARDS/FORS1_BIAS_2080x2048_T4.sof\
     data/MASTER/FORS1_BIAS_2080x2048_T4 -nkv

     => This creates the FORS1_BIAS_2080x2048_T4_comb5.fits Bias image, and the
     RON map as HDU#1 [NOISE] (visualize it with ds9 i.e.).


** Run the Master Flat creation (~ 1'30"):

   > bin/make_Nflat.exe LSS_FLAT data/CARDS/FORS1_LSS_FLAT_1.01_300V_306.sof\
     data/MASTER/FORS1_LSS_FLAT_1.01_300V_306 -kv

     => This creates the 'FORS1_LSS_FLAT_1.01_300V_306_comb5.fits' Flat Field image,
     together with some HDUs (Rejected pixels, Central mean flux profil and 
     Lamp Model Spectra, due to option [-k]).
     You can list those HDUs with ESO-eclipse tools :
     dfits -x 0 data/MASTER/FORS1_FLAT_..._comb5.fits | grep EXTNAME


** Run the Master Wave creation (dispersion function, ~ 1') :

   > bin/make_Nwave.exe LSS_WAVE data/CARDS/FORS1_LSS_WAVE_1.01_300V_306.sof\
     data/MASTER/FORS1_LSS_WAVE_1.01_300V_306 -kv

     => This creates the FORS1_LSS_WAVE_1.01_300V_306_comb1.fits' Wave image,
     together with the 'DISP_COEFS' HDU#3, giving the 9 dispersion coefficients.

** Run the Standard Star reduction (~ 1'30") :

   > bin/make_Nstd.exe LSS_STD data/CARDS/FORS1_LSS_STD_1.01_300V_306.sof\
     data/MASTER/FORS1_LSS_STD_1.01_300V_306 -nkv

     => This creates the 'FORS1_LSS_STD_1.01_300V_306_comb1.fits' Reduced Standard
     Star 2D-spectrum, together with the 'PROFILS' HDU#7 of the integrated PSF in CFHT bands 
     and the 'SPECTRA' HDU#8 of the true standard star spectrum.

** Run the Standard Star Spectrum Extraction -> Instrumental Response (~ 30") :
   
   > bin/StdExtract.exe data/MASTER/FORS1_LSS_STD_1.01_300V_306_comb1.fits\
     data/REDUCE/FORS1_LSS_STD_1.01_306 -Iv

     => This creates some files.dat, and the 'FORS1_LSS_STD_1.01_306_2Dresidu.fits' of
     the image of the extraction residuals, together with the 'RESPONSE' HDU#3 of the
     instrumental response.


     ***********     Now we have all Calibrations ready !    ***********

     Let's star the Science reduction and extraction :


** Run the Sky Frames Combining (~ 3') :

   > bin/make_Nsky.exe LSS_SKY data/CARDS/FORS1_LSS_03D1bt_1.01_300V_306.sof\
     data/MASTER/FORS1_LSS_03D1bt_1.01_300V_306 -nkv

     => This creates the 'FORS1_LSS_03D1bt_1.01_300V_306_comb3.fits' Reduced Science
     2D-spectrum, together with HDUs of the Dispersion coefs and the Instrumental 
     Response taken from the HDUs of the calibration frames given in the Data-Card.

** Now run the PHASE Extraction, using the already prepared Extraction Profils (~ 10"):

   > bin/SpecExtract.exe bin/SpecExtract.exe data/MASTER/FORS1_LSS_03D1bt_1.01_300V_306_comb3.fits\
    data/ExtractionProfils/03D1bt_306_REFextr.dat data/REDUCE/03D1bt_306 -rxlav

    => This is similar to the 'StdExtract.exe', but the extraction profils are 
    given in the '03D1bt_306_REFextr.dat' file.
    The created '03D1bt_306_2Dresidu.fits' is the extraction 2D-residuals, 
    together with the 'NORM-SPEC' HDU#3 of the extracted spectra of all sources 
    defined in '03D1bt_306_REFextr.dat', corrected for instrumental response, 
    extinction, slit-losses and absorption (due to [-rxla]).
    Also, an ASCII file with those spectra is created : '03D1bt_306_PSFspec.dat' 
    (easy to plot with gnuplot! : plot '03D1bt_306_PSFspec.dat' u 2:5;
    will you guess the type of this SN ?) .


    ***************     This is it.     **************


** The main subtelty is to create those Extraction Profils.

   It is done, for SNLS-VLT, by '$PHASEDIR/src/PhotoPriors/PrepareSN.py'
   (itself using 'C_VLTobs.py', calling 'findsourcesTools.py' and others...), 
   before running 'SpecExtract.exe' .
   
   But it needs the SuperNova photometry to anticipate it's flux at the date of 
   spectroscopy, and the Deep-stack images of the field.
   
   Using this informations and the combined 2D-spectrum, 
   it computes the SN trace equation on the 2D-spectrum by cross-correlation
   (with the 3 photo-bands g,r,i covered by the spectrum, and fitting only a 
   linear law since there is very little trace curvature), 
   and it defines the number of sources to be extracted and their profil 
   (bolometric: g+r+i).

   Also, we use the Active-Optics data (guiding star FWHM) to estimate the seeing 
   of the observation, and set the point-sources gaussian width to this value
   (the mean seeings are computed when creating the science Data-Cards, by 
   'ReducProd/SkyCards.py' and are listed in the Data-Cards : 'FWHM_k' fields).


** Adapting PHASE to another survey will imply to rewrite some of the routines 
   under 'PhotoPriors' in order to use your own photometric informations.

   You also need to create a combined 2D-spectrum, clean of cosmic-rays and 
   of sky background.
   Ideally, it will also contains the 'RESPONSE' table, 'DISP_COEFS' table
   and 'NOISE' image HDUs.