PDS_VERSION_ID = PDS3 RECORD_TYPE = STREAM RELEASE_ID = 0001 REVISION_ID = 0000 OBJECT = TEXT PUBLICATION_DATE = 2015-11-20 NOTE = "Description of the SOFTWARE directory contents" END_OBJECT = TEXT END PFS software (tested on IDL version 8) December 2011 Set of softwares able to open and read raw and geometry data, and to read the right calibration tables and apply the calibration operation to obtain the calibrated spectra. ----------------------------------------------------------------------------- Intro When downloading the ZIP file, the user should put it in a working directory dedicated to PFS software,then unzip it. This will create the following subdirectories : | |- /CALIB/ | |- /DATA/ | |- /FUNCTIONS/ | |- /GEOMETRY/ The essential functions to open and read the data are in the FUNCTIONS 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 dataset root level and the code to produce that outputs starting from the RAW data and the calibration tables stored in the /CALIB / directory at dataset root level. To run example code do the following steps: - set working directory as current idl directory - open the main procedure - compile source files by running TWO TIMES the following command in the Command Input Prompt: IDL> @buildAll - execute the main procedure 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. ----------------------------------------------------------------------------- Functions general usage description Using the SOFTWARE/DATA/Data_Opener.pro, you can read both RAW data and HK data. 1. If your input is a RAW file you have as output the variable “raw_struct” containing the following data: OBT_OBSERVATION_TIME : Julian date; SCET_OBSERVATION_TIME : Seconds since the 3rd ofMay 2003; INTERFEROGRAM : Array[16384] Example: If you want to write the i-th interferogram of the selected orbit and its related data, you can use the following IDL commands: - print, raw_struct(i).interferogram - print, raw_struct(i).obt_observation_time - print, raw_struct(i).scet_observation_time 2.If your input is a HK file you have as output the variable “hk_struct” containing various data described in the documents provided into the /DOCUMENT folder: MEX-PFS-PSA-ICD-25.PDF and FUM*.PDF. Example: If you want to write the laser diode temperature of the SW channel during the i-th acquisition you can use the following IDL command: -print, hk_struct(i).LDTEMPSW_10V Using the SOFTWARE/GEOMETRY/Geometry_READER.pro, you can read the geo data. 1. The input is a GEO file and the output is the variable “geo_struct” containing variables described in /GEOMETRY/GEOMINFO.TXT document. Example: If you want to write the geographic longitude and the latitude of the i-th acquisition you can use the following IDL command: -print, geo_struc(i).LONGITUDE, geo_struc(i).LATITUDE Using the SOFTWARE/CALIB/LWC_OPENER.PRO and SOFTWARE/CALIB/SWC_OPENER.PRO you can read calibrated data samples, while using the LWC_CAL.PRO, SWC_CAL_LASER-ON.PRO and SWC_CAL_LASER-OFF.PRO you can calibrate raw data. 1. If you want to read calibrated data samples, you have to run the LWC_OPENER.PRO (or the SWC_OPENER.PRO). The input is a RAD file (/DATA/CALIB_SAMPLES/ folder) and the output is the variable “cal_struct” containing the following data: OBT_OBSERVATION_TIME SCET_OBSERVATION_TIME WAVENUMBER RADIANCE Example: If you want to plot the i-th spectrum of the selected orbit and its related data, you can use the following IDL command: -plot, cal_struct(i).WAVENUMBER,cal_struct(i).RADIANCE 2. If you want to calibrate raw data, you have to run the LWC_CAL.PRO (or the SWC_CAL_LASER-OFF.PRO / SWC_CAL_LASER-ON.PRO). The input is a RAW file with its label file, a HK file with its label file and the calibration curves (/CALIB/ folder). The output is the calibrated radiance of all the spectra in the selected orbit (variable “MarsRadiance” [erg s-1 cm-2 sr-1 / cm-1]) and their wavenumber grid (variable “x_axes” [cm-1]). These variables are calculated following the formulas: > For LWC: spectra = abs(fft(interferograms,-1) MarsRadiance = (Deep_space - spectra)/Responsivity*1.E07 lambda = 263.928E-06*hk_struct.LDTEMPLW_10V + 1.13351 spectral_step = 10000.00/(8192.00*lambda) x_axes = indgen(points/2) x_axes = Rebin(x_axes,points/2,num) x_axes = x_axes*rebin(spectral_step,num,points/2) > For the SWC LASER-ON (up to orbit 633): spectra = abs(fft(interferograms,-1) MarsRadiance = (Deep_space + spectra)/Responsivity lambda = 8.01631e-005*hk_struct.LDTEMPSW_10V + 1.16774 spectral_step = 10000.00/(8192.00*lambda) x_axes = indgen(points/2) x_axes= Rebin(x_axes,points/2,num) x_axes= x_axes*rebin(spectral_step,num,points/2) > For the SWC LASER-OFF (from orbit 634): spectra = abs(fft(interferograms,-1) MarsRadiance = (Deep_space + spectra)/Responsivity lambda = 6.06520e-005*hk_struct.LDTEMPLW_10V + 1.19203 spectral_step = 1.04149*(10000.00/(8192.00*lambda)) x_axes = indgen(points/2) x_axes = Rebin(x_axes,points/2,num) x_axes = x_axes*rebin(spectral_step,num,points/2) ----------------------------------------------------------------------------- List of Functions and Resulting Variables Data_Opener() : Open both RAW or HK data file. If the the input is a RAW file, the output variable is "raw_struct" containing the following data: OBT_OBSERVATION_TIME : Julian date; SCET_OBSERVATION_TIME : Seconds since the 3rd ofMay 2003; INTERFEROGRAM : Array[16384] If the the input is a HK file, the output variable is "hk_struct" containing various data described in the documents provided into the /DOCUMENT folder: MEX-PFS-PSA-ICD-25.PDF and FUM*.PDF. -------- Geometry_Opener : Open geometry data The INPUT is a GEO file and the output is the variable "geo_Struct" containing the following data: SCET LONGITUDE LATITUDE SPACECRAFT_ALTITUDE LOCAL_TIME SOLAR_LONGITUDE INCIDENC_EANGLE EMISSION_ANGLE PHASE_ANGLE MOLA_ALTIMETRY LW_TANGENT_ALTITUDE LW_TARGET_DISTANCE SOLAR_DISTANCE SUBSOLAR_LONGITUDE SUBSOLAR_LATITUDE PLANETARY_PHASE_ANGLE SUB_SPACECRAFT_LONGITUDE SUB_SPACECRAFT_LATITUDE JULIAN_DATE AIR_MASS The meaning of these variables is provided in /GEOMETRY/GEOMINFO.TXT. -------- lwc_opener : Read calibrated LWC data The INPUT is a RAD file and the OUTPUT is the variable "cal_struct" containing the following data: OBT_OBSERVATION_TIME SCET_OBSERVATION_TIME WAVENUMBER RADIANCE -------- swc_opener : Read calibrated SWC data The INPUT is a RAD file and the OUTPUT is the variable "cal_struct" containing the following data: OBT_OBSERVATION_TIME SCET_OBSERVATION_TIME WAVENUMBER RADIANCE -------- lwc_cal : Calibrate raw LWC data The INPUT is a raw file with its label file, a HK file with its label file and the calibration curves (into /CALIB directory). The OUTPUT is the calibrated radiance of all spectra in the selected orbit (variable “MarsRadiance” [erg s-1 cm-2 sr-1 / cm-1]) and their wavenumber grid (variable “x_axes” [cm-1]). These variables are calculated following this formula: spectra = abs(fft(interferograms,-1) MarsRadiance = (Deep_space - spectra)/Responsivity*1.E07 lambda = 263.928E-06*hk_struct.LDTEMPLW_10V + 1.13351 spectral_step = 10000.00/(8192.00*lambda) x_axes = indgen(points/2) x_axes = Rebin(x_axes,points/2,num) x_axes = x_axes*rebin(spectral_step,num,points/2) -------- swc_cal_laser-off.pro : Calibrate raw SWC data for orbits with laser off The INPUT is a raw file with its label file, a HK file with its label file and the calibration curves (into /CALIB directory). The OUTPUT is the calibrated radiance of all spectra in the selected orbit (variable “MarsRadiance” [erg s-1 cm-2 sr-1 / cm-1]) and their wavenumber grid (variable “x_axes” [cm-1]). These variables are calculated following this formula: spectra = abs(fft(interferograms,-1) MarsRadiance = (Deep_space + spectra)/Responsivity lambda = 6.06520e-005*hk_struct.LDTEMPLW_10V + 1.19203 spectral_step = 1.04149*(10000.00/(8192.00*lambda)) x_axes = indgen(points/2) x_axes = Rebin(x_axes,points/2,num) x_axes = x_axes*rebin(spectral_step,num,points/2) -------- swc_cal_laser-on.pro : Calibrate raw SWC data for orbits with laser on The INPUT is a raw file with its label file, a HK file with its label file and the calibration curves (into /CALIB directory). The OUTPUT is the calibrated radiance of all spectra in the selected orbit (variable “MarsRadiance” [erg s-1 cm-2 sr-1 / cm-1]) and their wavenumber grid (variable “x_axes” [cm-1]). These variables are calculated following this formula: spectra = abs(fft(interferograms,-1) MarsRadiance = (Deep_space + spectra)/Responsivity lambda = 8.01631e-005*hk_struct.LDTEMPSW_10V + 1.16774 spectral_step = 10000.00/(8192.00*lambda) x_axes = indgen(points/2) x_axes= Rebin(x_axes,points/2,num) x_axes= x_axes*rebin(spectral_step,num,points/2) -------- read_pfs_data(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 : UNSIGNED LONG INTEGER INTERFEROGRAM : INTEGER 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 interferogram -------- read_pfs_hk(FILE,NUM): return a structured variable array with the housekeeping data. Array length is NUM. Each array element is defined as : OBT_OBSERVATION_TIME : DOUBLE PRECISION FLOAT SCET_OBSERVATION_TIME : UNSIGNED LONG INTEGER TypeOfMes : UNSIGNED LONG INTEGER SD_Version : UNSIGNED LONG INTEGER ZOPD_SW_FWD : UNSIGNED LONG INTEGER ZOPD_SW_REV : UNSIGNED LONG INTEGER ZOPD_LW_FWD : UNSIGNED LONG INTEGER ZOPD_LW_REV : UNSIGNED LONG INTEGER SCANPOS : UNSIGNED LONG INTEGER SW_ZeroX_Cutoff_Status : DOUBLE PRECISION FLOAT LW_ZeroX_Cutoff_Status : DOUBLE PRECISION FLOAT SPEEDCLOCK_Status : DOUBLE PRECISION FLOAT ADCCLOCK_Status : DOUBLE PRECISION FLOAT SW_Detector_Cutoff_Status : DOUBLE PRECISION FLOAT LW_Detector_Cutoff_Status : DOUBLE PRECISION FLOAT SWGAIN_Status : UNSIGNED LONG INTEGER LWGAIN_Status : UNSIGNED LONG INTEGER First_ADC_1_Status : UNSIGNED LONG INTEGER Second_ADC_1_Status : UNSIGNED LONG INTEGER First_ADC_2_Status : UNSIGNED LONG INTEGER Second_ADC_2_Status : UNSIGNED LONG INTEGER Select_Motor_Coil_Status : UNSIGNED LONG INTEGER DPDIR_Status : UNSIGNED LONG INTEGER SW_ZOPD_Position : UNSIGNED LONG INTEGER LW_ZOPD_Position : UNSIGNED LONG INTEGER Right_Collisions : UNSIGNED LONG INTEGER Left_Collisions : UNSIGNED LONG INTEGER SWLASERPWR_10V : DOUBLE PRECISION FLOAT LWLASERPWR_10V : DOUBLE PRECISION FLOAT SWPHOTODIODEPWR_10V : DOUBLE PRECISION FLOAT LWPHOTODIODEPWR_10V : DOUBLE PRECISION FLOAT T1_10V : DOUBLE PRECISION FLOAT T2_10V : DOUBLE PRECISION FLOAT T3_10V : DOUBLE PRECISION FLOAT T4_10V : DOUBLE PRECISION FLOAT T5_10V : DOUBLE PRECISION FLOAT T6_10V : DOUBLE PRECISION FLOAT T7_10V : DOUBLE PRECISION FLOAT T8_10V : DOUBLE PRECISION FLOAT LDTEMPSW_10V : DOUBLE PRECISION FLOAT LDTEMPLW_10V : DOUBLE PRECISION FLOAT SWTEMP_10V : DOUBLE PRECISION FLOAT LWTEMP_10V : DOUBLE PRECISION FLOAT TEMPA1_10V : DOUBLE PRECISION FLOAT TEMPA2_10V : DOUBLE PRECISION FLOAT SWTRW_10V : DOUBLE PRECISION FLOAT LWTRW_10V : DOUBLE PRECISION FLOAT CLVOLTAGE_10V : DOUBLE PRECISION FLOAT INPUT: FILE : path of the data file to open NUM : total number of the field (= observation) stored in the file -------- read_pfs_label(FILE,NAME): return value stored in a PDS label file in the NAME field INPUT: FILE : path of the label file to open NAME : name if the field to search for (i.e. ROWS or FIELDS) -------- read_pfs_geometry(FILE,NUM): return a structured variable array with all the geometrical information.Array length is NUM. Each array element is defined as : SCET : DOUBLE PRECISION FLOAT LONGITUDE : DOUBLE PRECISION FLOAT LATITUDE : DOUBLE PRECISION FLOAT SPACECRAFT_ALTITUDE : DOUBLE PRECISION FLOAT Local_Time : SINGLE PRECISION FLOAT Solar_Longitude : DOUBLE PRECISION FLOAT INCIDENC_EANGLE : SINGLE PRECISION FLOAT EMISSION_ANGLE : SINGLE PRECISION FLOAT PHASE_ANGLE : SINGLE PRECISION FLOAT MOLA_ALTIMETRY : SINGLE PRECISION FLOAT LW_TANGENT_ALTITUDE : SINGLE PRECISION FLOAT LW_TARGET_DISTANCE : SINGLE PRECISION FLOAT SOLAR_DISTANCE : SINGLE PRECISION FLOAT SUBSOLAR_LONGITUDE : DOUBLE PRECISION FLOAT SUBSOLAR_LATITUDE : DOUBLE PRECISION FLOAT PLANETARY_PHASE_ANGLE : SINGLE PRECISION FLOAT SUB_SPACECRAFT_LONGITUDE : DOUBLE PRECISION FLOAT SUB_SPACECRAFT_LATITUDE : DOUBLE PRECISION FLOAT JULIAN_DATE : DOUBLE PRECISION FLOAT AIR_MASS : SINGLE PRECISION FLOAT INPUT: FILE : path of the geometry file to open NUM : total number of the field (= observation) stored in the file Definition of field in Geometry File: ----------------------------------------------------------------------------- Label Range Units ----------------------------------------------------------------------------- SCET Value of the Spacecraft clock LONG_LW Mars Longitude for the LWC instrument (-180°;+180°) deg LAT_LW Mars Latitude for the LWC instrument (-90°;+90°) deg LONG_SW Mars Longitude for the SWC instrument (-180°;+180°) deg LAT_SW Mars Latitude for the SWC instrument (-90°;+90°) deg The Longitudes are expressed following the Eastward convention SC_ALT Spacecraft altitude km LT Local Time at the SWC target hours LS Solar Longitude (0°;+360°) deg INC_SW Incidence angle for the SWC instrument (0°;+180°) deg EM_SW Emission angle for the SWC instrument (0°;+180°) deg PH_SW Phase angle for the SWC instrument (0°;+180°) deg ALTM Mola Altimetry m TG_ALT Limb altitude for the SWC instrument km This parameter is not null only for limb observations TG_DIST Distance from the spacecraft to the target point (SWC) km S_DIST Solar distance AU SS_LONG Longitude of the sub-solar point (-180°;+180°) deg SS_LAT Latitude of the sub-solar point (-90°;+90°) deg PL_PH Planetary phase angle (0°;+180°) deg SSC_LONG Longitude of the sub-spacecraft point (-180°;+180°) deg SSC_LAT Latitude of the sub-spacecraft point (-90°;+90°) deg JD Julian Date Airmass Secant of the emission angle ============================================================================= -------- 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.