MORSE Output Files

09DEC04

When MORSE is run successfully, 3 output files are always generated, plus a number of optional outputs which can be selected by various comibinations 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
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
morse.*_MW[nn] Microwindow outputs Every Microwindow MWO

Notes
  1. The MWO flag can be used to save the outputs after each microwindow as separate files, but also 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.
! [File_Type] generated by MORSE v.[ddmmmyy]
File_Type C*(*) Describes the output eg Retrieved profiles
ddmmmyy C*11 MORSE version eg 28OCT04
![comment]
comment from the driver table *HDR section
! YMD=[yyyymmdd] HMS=[hhmmss] LAT=[lat.dddd] LON=[long.dddd] LST=[hh.dddd] SZA=[ddd.dddd]
yyyymmdd I8.8 Date of the scan, eg 20020724 (24th July, 2002)
hhmmss I6.6 Time of the scan, eg 113640 (11:36:40 am)
lat.dddd F8.4 Latitude in Degrees North, eg 49.0245
long.dddd F9.4 Longitude in Degrees East, eg -20.6655
hh.dddd F7.4 Local Solar Time in Hours, eg 10.1200 [added in MORSE v16DEC04]
hh.dddd F8.4 Solar Zenith Angle in Degrees, eg 36.8797 [added in MORSE v16DEC04]
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 v[ddmmmyy]
    where [ddmmyyy] identifies the version of MORSE 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

Format
RFM .atm file format
[3 Header Records]
See Common File Headers
NLev
NLev I*4 Number of retrieval levels in *LEV section eg 17
*Profile
Profile Up to C*7 Type of profile to follow (see below) eg *HGT
Prf(1) Prf(2) ... Prf(NLev)
Prf(i) R*4 or I*4 Profile value at level i eg 6.859100 10.32786 ...
*Profile etc
Repeat for next profile, etc ...
*END
End of file marker
The profiles are written in the following sequence:
Profile Type Description Requirement
*HGT R*4 Altitudes [km] of the retrieval grid [always present]
*SWEEP I*4 Sweep index associated with altitude level (or 0) HYD in *FLG section
*CLOUD I*4 Cloud flag associated with altitude level (1=cloud, 0=clear) CLD in *FLG section
*TEM R*4 Retrieved temperature [K] TEM in *RTV section
*TEM_SD R*4 SD of Retrieved temperature [K] TEM in *RTV section
*PRE R*4 Retrieved Pressure [mb] PRE in *RTV section
*PRE_SD R*4 SD of Retrieved Pressure [mb] PRE in *RTV section
*[GAS#n] R*4 Retrieved [GAS#n] VMR [ppmv] [GAS#n] in *RTV section
*[GAS#n]_SD R*4 SD of Retrieved [GAS#n] VMR [ppmv] [GAS#n] in *RTV section
Retrieval Diagnostics (MORSE v25NOV04 onwards)
*NMIC I*4 No. microwindows used [always present]
*NOTCNV I*4 No. microwindows not converged [always present]
*AVGITR R*4 Average no. of iterations [always present]
*AVGCSQ R*4 Average Chi-square statistic [always present]

Notes
  1. If more than one gas is retrieved, these are written in the same order as they are placed in the *RTV section of the driver table.
  2. The diagnostics are defined only for the retrieval levels which correspond to sweep tangent heights, and set to zero for other levels.
  3. The AVGITR and AVGCSQ values are only averaged over the retrievals which did converge
  4. For the microwindow output files (morse.rtv_MW[nn]) the diagnostic outputs apply to that microwindow only, ie NMIC and NOTCNV can only have values 0 or 1 and AVGITR will be an integer.

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

morse.atm (mandatory)

Description
Retrieved Atmosphere

Format
RFM .atm file format
The same profiles/sequence as in the morse.rtv file except that

Notes
  1. 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.

Examples
morse_pt.atm from pT retrieval
morse_h2o.atm 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. The files morse.acv_MW[nn] (written if the MWO flag is used) 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
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.

Notes

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
[3 Header Records]
See Common File Headers
N M
N I*4 First dimension of matrix eg 36
M I*4 Second dimension of matrix (See Note 2) eg 36
SX(1,1) SX(2,1) ... SX(N,M)
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. The files morse.cov_MW[nn] (written if the MWO flag is used) 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.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
[3 Header Records, each starting with '#']
See Common File Headers
#OM=??? DN=? AD=?
Dummy record - See Note 3
MW_Label NPts Nom_Alt Num_Res
MW_Label C*8 Microwindow label eg PT__0001
NPts I*4 No. of spectral points in MW eg 121
Nom_Alt R*4 Nominal Altitude eg 68.00000
Num_Res I*4 No. residual spectra averaged always 1
Res(1), Res(2) ... Res(Npts)
Res(i) R*4 value of the residual at spectral point i
MW_Label NPts Nom_Alt Num_Res etc ...
Repeated for next sweep (eg 60km) for first microwindow ...
Then repeated for next microwindow ...

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. This record is for compatibility with the ESA residuals, and basically states that the occupation matrix, day/ngt and ascending/descending node of the orbit are undefined for these residuals. For MORSE v16DEC04 onwards, the field DN=N is set for solar zenith angles > 90 degrees, and DN=D otherwise.
  4. The format is the same as the residual files extracted from ESA data by the IDL program l2proc_res.pro

Example
morse.res

morse.*_MW[nn] (optional)

Description
Microwindow-specific outputs
Output if the MWO flag is included in the *FLG section of the driver table

Format
_MW[nn] is appended to main output filenames, where [nn] is the number of the microwindow in the processing sequence (ie, 01, 02, ... etc)
File formats are the same as the main files with the following differences

Notes
  1. For the retrieval outputs (.rtv, .rtv, .rtv), the *MW#[nn] files represent the state of the retrieval after the inclusion of MW#nn, so for the final microwindow the main retrieved parameters will be the same as the main output file.
  2. However, for the a priori outputs (.apr, .acv), the *MW#[nn] files represent the state of the retrieval at the start of the includion of MW#nn, so the first files *MW01 will be the same as the main a priori outputs.

Example
morse.rtv_MW01

Back to MORSE Index