MORSE Output Files

05OCT05
Differences from MORSE v2 in maroon
When MORSE is run successfully, 4 output files are always generated, plus a number of optional outputs which can be selected by various combinations of Flags in the driver table.

MORSE Output Files
Mandatory outputs Updated
morse.log Log file Every Iteration
morse.rtv Retrieved state vector Every Microwindow
morse.atm Retrieved atmosphere Every Microwindow
morse.swp Sweep information Every Microwindow Added in MORSE v3
Optional outputs Updated Reqd Flag(s)
morse.acv A Priori Covariance At Start APR + COV
morse.apr A Priori state vector At Start APR
morse.cov Retrieval Covariance Every Microwindow COV
morse.dia Diagnostics Every Iteration DIA
morse.res Residual Spectra Every Microwindow RES

Notes
  1. The MWO Flag can be used to save the outputs after each microwindow as separate files which have the same filenames as the normal outputs but with '_MW[nn]' appended, where [nn] is the microwindow sequence number. This is the only way of examining the continuum retrieval (which is fitted separately for each microwindow).
  2. Output file names and/or directory (apart from morse.log) can be altered using the optional *OUT section of the driver table.

Common File Headers

Apart from morse.log and morse.dia, all MORSE output files have a common header consisting of 3 records, each of which starts with a '!' character so that they are all regarded as 'comment records' when used as input files.

Format
3 records of 80 characters
!FILE_TYPE generated by MORSE v.VERSID
!COMMENT
! YMD=YMD HMS=HMS LAT=LAT LON=LON LST=LST SZA=SZA

FieldTypeDescription
FILE_TYPE C*(*) Describes the output file eg 'Retrieved Profiles'
VERSID C*11 MORSE version identifier eg '28OCT04'
COMMENT C*79 Comment From *HDR section
YMD I8.8 Date of the scan [yyyymmdd] eg '20020724' (=24th July, 2002)
HMS I6.6 Time of the scan [hhmmss] eg '113640'> (=11:36:40 am)
LAT F8.4 Latitude in [deg N] eg '49.0245'
LON F9.4 Longitude in [deg E] eg '-20.6655'
LST F7.4 Local Solar Time [h] eg '10.1200'
SZA F8.4 Solar Zenith Angle [deg] eg '36.8797'

Notes
  1. The time and location information for the scan is based on that of the central sweep in the scan
  2. In the morse.res file header the '!' character at the start of each record is replaced by '#'.

The rest of this document describes each type of output file in more detail.

morse.log (mandatory)

Description
General file for logging all status/progress messages.

Format
Text records of any of the following kind
Identifying message category and subroutine
R-MORSE: ... Start and successful completion
I-[SUB]: ... Information from subroutine [SUB]
W-[SUB]: ... Warning from subroutine [SUB]
F-[SUB]: ... Fatal Error from subroutine [SUB]
Identifying driver table section being read
*[ABC] Reading Driver Table section *[ABC]
Next record after I-OPNFIL: ...
! [comment] 1st record of file just opened (usually a comment)
Next 2 records after I-LUTFIL: ...
[dd-mmm-yyy] [hh.mm.ss.000000] Time stamp of LUT file just opened
# [comment] Comment record for LUT

Notes
  1. The first record will always be:
    R-MORSE: Running MORSE vVERSID
    where VERSID identifies the     MORSE version being run (C*11 variable VIDHDR in file hdrcom.inc, Set in main program module morse.for).
  2. For a successfully completed run the last message will be
    R-MORSE: Successful completion

Examples
morse.log from pT retrieval (generated with driver table morse.drv)
morse.log from H2O retrieval (generated with driver table morse.drv)

morse.rtv (mandatory)

Description
Retrieved State Vector & SD

Format
RFM .atm file format

Notes
  1. If more than one gas/species is retrieved, these are written in the same order as they are placed in the *RTV section of the driver table.
  2. For each retrieved profile (eg H2O) there immediately follows a profile of SD values (eg H2O_SD) containing the square root of the diagonal elements of the retrieval covariance converted to the same units as the profile.
  3. Profiles of Sweep# and Cloud Detection (1=cloud, 0=cloud free) are written only for retrievals on the tangent point grid (these are, in any case, always written in the .swp file).
  4. If the MWO Flag is enabled then the retrieved continuum (*CTM) and SD (*CTM_SD) profiles are to the individual morse.rtv_MW[nn] files.
  5. In MORSE v3 diagnostics are written to the .swp file.

Examples
morse_pt.rtv from pT retrieval
morse_h2o.rtv from H2O retrieval

morse.atm (mandatory)

Description
Retrieved Atmosphere

Format
RFM .atm file format

Notes
  1. The same species profiles are written as in the .rtv output except that profiles extend for full atmosphere used in internal forward model (so included fixed as well as retrieved profile levels), and no SD profiles are included.
  2. The morse.atm files are recommended for passing the information from one retrieval into another retrieval from the same scan via the *L2P section of the driver table.
  3. If the MWO Flag is enabled then the retrieved continuum (*CTM) profiles are to the individual morse.atm_MW[nn] files.

Examples
morse_pt.atm from pT retrieval
morse_h2o.atm from H2O retrieval

morse.swp (mandatory)

Description
Sweep(=spectrum) Diagnostics

Format
RFM .atm file format, except that first profile is Sweep Index rather than altitude and usually in descending altitude order
!CFH#1 Common File Header
!CFH#2 Common File Header
!CFH#3 Common File Header
NSWP ! Number of Sweeps
*PROF Start repeat for profiles
PRFVAL(ISWP) Repeat for ISWP=1, NSWP
End repeat for profiles
*END
Field Type Description
CFH#n C*80 3 Common File Header Records See CFH description
NSWP I*4 No. of sweeps in L1C file eg '17'
Then the following *PROF/PRFVAL arrays
*SWEEP I*4 Sweep Index From L1C file
*HGT_NOM R*4 Nominal Altitude [km] From L1C file
*HGT_LV1 R*4 L1B 'Engineering' Altitude [km] From L1C file
*HGT_RTV R*4 L2 Retrieved Altitude [km] From input .swp file
*CLOUD I*4 Cloud Flags 1=Cloud, 0=No Cloud
*NMIC I*4 No.Microwindows Used
*NOTCNV I*4 No.Microwindows not converged
*AVGITR R*4 Average No.Iterations per MW
*AVGCSQ R*4 Average Chi-Sq per MW

Notes
  1. .swp files contain at least 2 altitude grids derived from the L1C file and usually the *HGT_RTV grid which is generated in the output of the pT retrieval .swp file and input to subsequent retrievals in the *L1C section.
  2. The *CLOUD array is generated whether or not the CLD Flag is used (ie without the CLD Flag microwindows may still be used for sweeps which are indicated here as cloudy).
  3. The MWO Flag generates files morse.swp_MW[nn] containing only the results for a single microwindow, hence *NMIC values are all 1 or 0 and *AVGITR and AVGCSQ refer to single retrievals (so not really averages).

Examples
morse_pt.swp from pT retrieval
morse_h2o.swp from H2O retrieval

morse.acv (optional)

Description
A Priori Covariance
Output if both the APR and COV flags are included in the *FLG section of the driver table.

Format
Same as morse.cov

Notes
  1. The file morse.acv contains the a priori covariance at the start of the retrieval, eg with 100% uncertainties for VMR (converted to [ln(VMR)]^2) unless modified via the *ASD section of the driver table. This is written at the start of the first retrieval and not changed. Continuum and Offset terms are not included.
  2. If the MWO Flag is enabled the files morse.acv_MW[nn] contain the a priori covariance at the start of each microwindow retrieval, including any continuum and offset components.

Example
morse.acv

morse.apr (optional)

Description
A Priori State Vector
Output if the APR flag is included in the *FLG section of the driver table

Format
RFM .atm file format

Notes
  1. Contains the same profiles/sequence as in the morse.rtv file, except referring to a priori profiles at the start of the retrieval, as read in from the *CLI and *L2P sections of the driver table.

Examples
morse.apr

morse.cov (optional)

Description
Retrieval Covariance
Output if the COV flag is included in the *FLG section of the driver table

Format
MORSE matrix file format
!CFH#1 Common File Header
!CFH#2 Common File Header
!CFH#3 Common File Header
N M
SX(i,j) repeat ((for i=1,n), j=1,m)

Field Type Description
CFH#n C*80 3 Common File Header Records See CFH description
N I*4 First dimension of matrix eg '36'
M I*4 Second dimension of matrix eg '36'
SX(i,j) R*8 Element i,j of the Covariance Matrix eg '0.151308903009384'

Notes
  1. The ordering of elements within this covariance matches that of the elements in morse.rtv and excludes microwindow-dependent parameters such as continuum and offset.
  2. Since covariance matrices are always square, M=N, but both dimensions are required as this is a general matrix file format
  3. If the MWO Flag is enabled the files morse.cov_MW[nn] matches the elements of morse.rtv_MW[nn], including any continuum and offset components.
  4. The retrieval covariance file can be used directly as the A Priori Covariance input to the next scan retrieval via the *ACV section of the driver table.

Examples
morse.cov (corresponds to morse_pt.rtv)
morse.cov_MW01 (corresponds to morse.rtv_MW01)

morse.dia (optional)

Description
Diagnostics file.
Output if the DIA flag is included in the *FLG section of the driver table

Format
Not yet defined!
At the moment a bit of a mess with all sorts of possibly useful information output each iteration by subroutine wrtdia.for

Notes
  1. IDL procedure inpdia.pro may be useful in reading the MORSE diagnostics file into a structure.

Example
morse.dia

morse.res (optional)

Description
Residual Spectra
Output if the RES flag is included in the *FLG section of the driver table

Format
!CFH#1 Common File Header
!CFH#2 Common File Header
!CFH#3 Common File Header
#OM=??? DN=DN AD=? Day/Night
MWLABEL NPTS NOMALT NAVG Start Repeat for each MWLABEL,NOMALT
RES(i) Repeat for i=1,NPTS
End Repeat for MWLABEL,NOMALT
FieldTypeDescription
CFH#n C*80 3 Common File Header Records See CFH description
DN C*1 'D'=Daytime, 'N'=Nighttime
MWLABEL C*8 Microwindow label eg 'PT__0001'
NPTS I*4 No. of spectral points in MW eg '121'
NOMALT R*4 Nominal Altitude [km] eg '68.00000'
NAVG I*4 No. residual spectra averaged always 1
RES(i) R*4 Value of the residual at spectral point i

Notes
  1. Residuals are defined as (measurement-forward model), written in swpres.for
  2. MORSE generates residuals after each microwindow/sweep is processed, so these are not 'true' residuals since the retrieved profile (and therefore forward model radiance) continues to change after the residuals are output.
  3. '#OM=???' etc record: this record is for compatibility with the ESA residuals, and basically states that the occupation matrix, and ascending/descending node of the orbit are undefined for these residuals. However, the Day/Night is determined by the solar zenith angle (>90 = nighttime, otherwise daytime).
  4. The format is the same as the residual files extracted from ESA data by the IDL program l2proc_res.pro

Example
morse.res
Back to MORSE Index