-----------------------------------
-----------------------------------
1 - Intro 
-----------------------------------
-----------------------------------

When downloading a ZIP file, the user should put it in a working directory 
dedicated to PFS  software,then unzip it.
This will create a two subdirectory :

/SOFTWARE/
|
|- /DATA/
|
|- /GEOMETRY/
|
|- /CALIB/

The essential functions to open and read the data are in the FUNCTIONS 
subdirectory of each directory. The examples programs given in both DATA and 
GEOMETRY are intended only as reader of the PFS data. 

The CALIB subdirectory contains both the programs to read calibrated PFS 
spectra stored in the /CALIB_SAMPLE/ directory at root level and the code to 
produce that outputs starting from the RAW data and the calibration tables 
stored in the /CALIB / directory at root level.

Essentially the software in the /SOFTWARE/CALIB/CALIBRATOR/ use the same 
functions stored in the /SOFTWARE/CALIB/DATA/ to read raw data, then read the 
right calibration tables  and apply the calibration operation to obtain the 
calibrated spectra (further details should be found in the calibration 
documents PFS_LWC_CALIB.PDF and PFS_SWC_CALIB.PDF as well in the 
PFS_CAL_LAB_1.PDF , PFS_CAL_LAB_2.PDF and PFS_CAL_NEAREARTH.PDF, in the 
/DOCUMENT/ directory).

-----------------------------------
-----------------------------------
2 - Running the code
-----------------------------------
-----------------------------------

To run example code do the following steps:

- open a .PRJ file (for DATA or for GEOMETRY)

- change the PATH variable to your PFS Data directory 

- Menu Project > Compile > All Files

- Menù Project > Run

Only for the software stored in the /CALIBRATOR/ subdirectory, the last step
 must be substituted with :
 
- Menù Run > Run 'program_name' (LWC_CAL.pro, SWC_CAL_LASER-OFF.pro or 
                                 SWC_CAL_LASER-ON)

The LWC_CAL.pro, SWC_CAL_LASER-OFF.pro and SWC_CAL_LASER-ON.pro will give to 
the user the calibrated spectra calculated directly from the raw data and 
from the calibration tables. The final variables available to the user will 
be the same as the output of the function read_pfs_data_calib (see below) 
for a direct comparison with the archived examples calibrated files.

-----------------------------------
-----------------------------------
3 - Code detailed description
-----------------------------------
-----------------------------------

 
I) Input definition

 1 - Data path definition.
 
 2 - Call the read_pfs_label to retrieve the number of spectra.
 
 3 - Call the read_pfs_hk to read the housekeeping information.
 
 4 - Call the read_pfs_label to retrieve data_points, the number of point in 
     the interferogram.
     
 5 - Call the read_pfs_data to retrieve the raw data (interferograms).
 
II) Calibration Tables definition

 6 - Calibration Tables path definition.
 
 7 - Read the Calibration Tables (simple ASCII files).
 
III) Calibration

 8 - Calibration of the spectral grid.
 
 9 - Subtraction of the mean for every single interferogram.
 
10 - FFT on every single interferogram to obtain uncalibrated spectra.

11 - Spectra separation on the basis of the Double Pendulum direction (stored 
     in the housekeeping information), Forward (FWD) and Reverse (REV).
     
12 - Rebin the calibration table "Deep_space" to match the Spectra matrix, 
     using two different tables for each Double Pendulum direction.
     
12 - Rebin the calibration table "Responsivity" to match the Spectra matrix, 
     using two different tables for each Double Pendulum direction.
     
13 - Radiance calibration, as described in the calibration documents in 
     /DOCUMENT/ .
     
14 - Extraction of the spectra stored in the /CALIB_SAMPLES/ directory, that 
are subsets of the whole orbit.

At the end the user will have Julian_Time, SCET, the spectral grid and the 
calibrated radiance of PFS, as the output of the read_pfs_data_calib for a 
direct comparison.

-----------------------------------
-----------------------------------
4 - CALIB_SAMPLES
-----------------------------------
-----------------------------------

The files gives as calibration samples are stored in /CALIB_SAMPLES/ 
directory. The structure is:

/CALIB_SAMPLES/
|
|- /LWC/-|               
|        |- PFS_0037_MEAS_RAD_LW.DAT               
|        |- PFS_0037_MEAS_RAD_LW.LBL
|       
|- /SWC/-|
         |- /LASER_ON/-|                            
         |             |- PFS_0037_MEAS_RAD_SW.DAT  
         |             |- PFS_0037_MEAS_RAD_SW.LBL          
         |
         |- /LASER_OFF/-|                            
                        |- PFS_1401_MEAS_RAD_LW.DAT  
                        |- PFS_1401_MEAS_RAD_LW.LBL  
           

The differences  between the two SWC subdirectories are addressed in the 
technical note about calibration in /DOCUMENT directory/
      

----------------------------------------------------------------------------

Function and Resulting Variables:

read_pfs_data_calib(FILE,NUM,RECORDS): return a structured variable array 
                                       with the data. Array length is NUM.
                                       Each array element is defined as :
                                 
                               OBT_OBSERVATION_TIME  : DOUBLE PRECISION FLOAT
                               SCET_OBSERVATION_TIME : DOUBLE PRECISION FLOAT
                               WAVENUMBER            : DOUBLE PRECISION ARRAY
                                                       WITH LENGTH = RECORDS
                               RADIANCE              : DOUBLE PRECISION ARRAY
                                                       WITH LENGTH = RECORDS
INPUT:
   FILE     : path of the data file to open                               
   NUM      : total number of the field (= observation) stored in the file
   RECORDS  : length of a single spectra, the same for the WAVENUMBER and 
              RADIANCE fields.