MORSE Common File Format

30APR24
Many MORSE output files have a common file structure (so should be readable with the same software). This consists of a file header, followed by multiple pixel (ie profile location) sections, each pixel section being divided into a common header and data sections.
Common File Structure
Common_File_Header
For iPix = 1, nPix
   Common_Pixel_Header
   Common_Pixel_Data

Common File Header

Structure
Common File Header
! FILTYP generated by MORSE v.VERSID
! HDRREC Header record set in driver file
FMT File format version
IGEOM Viewing geometry (eg 1=limb-viewing)
INST_ID SAT_ID Instrument, Satellite
YYYYMMDD JDAY Nominal date, Day# since 1Jan2000
ORBIT ORBSTA      ORBEND Orbit#, Start HHMMSS, End HHMMSS
NPIX NSET No. pixels or limb scans, No. sets/scan
NLEV NPRF (Max) No. Levels/Profile, No. Profiles/Set
*GRD Vertical grid coordinate
  GRD(1) GRD(2) ... Vertical grid levels
  ... GRD(NLEV)
For j=1, NPRF List of types of data profile
    PRF(j) NLVPRF(j) Profile type, No. levels in profile
    If NLVPRF(j) ≠ NLEV the following record is added
    LEV_FLG(1,j) LEV_FLG(2,j) ... LEV_FLG(NLEV,j)
*END End of Header marker record
Fields
FieldFormat Description Units Range
FILTYP C* Type of file eg Retrieval State Vector
VERSID C11 MORSE version identifier eg 27APR23
HDRREC C79 Copied from *HDR section of the driver table
FMT F10.2 MORSE output file format identifier 2.00
IGEOM I10 Viewing geometry 1, 2 or 3
INST_ID C10 Instrument identification eg IASI-A
SAT_ID C10 Satellite identification eg MetOp-A
YYYYMMDD I10 Year, Month, Day of data yyyymmdd
JDAY I10 Day# since 1 Jan 2000 (JDAY=0) ≥ 0
ORBIT I10 Orbit number since launch ≥ 0
ORBSTA I10 Orbit start time hhmmss
ORBEND I10 Orbit end time hhmmss
NPIX I10 No. of pixels or profile locations ≥1
NSET I10 No. sets of retrievals per pixel [1] ≥1
NLEV I10 Max. No. levels in each profile ≥1
NPRF I10 No. different profiles (or scalars) listed per pixel ≥1
*GRD C Profile grid [2] ∈ {*PRE, *HGT, *HGT_NOM }
GRD(:) * (NLEV) Profile grid values, lowest alt to highest km or hPa
PRF(:) C7 (NPRF) Profile type #j [3]
NLVPRF(:) I5 (NPRF) No. levels on which profile#j is represented ≥0 [4]
LEV_FLG(:,:) I2 (NLEV,NPRF) 1 if Profile#j is retrieved on Level#i, else 0 [5] ∈ { 0, 1 }

Notes
  1. NSET is normally 1, but increased by 1 if the APR flag is set, and/or increased by the number of microwindows/bands if the MWO flag is set.
  2. *GRD is determined by the grid set in section#4 of the morse.drv file
    Driver File *GRD in output File Grid type
    *PRE *PRE [hPa] Pressure levels
    *ALT *HGT [km] Altitude levels
    *TAN *HGT_NOM [km] Nominal tangent point altitudes
  3. PRF: Apart from the retrieved species this includes diagnostic and supplementary information, including scalar quantities. See descriptions of individual file types for possible values.
  4. NLVPRF: A value 0 is used for column or scalar retrievals, to distinguish these from profiles where a single retrieval level is specified.
  5. LEV_FLG: It is possible to specify individual retrievals on subsets of the full grid, in which case NLVPRF(j) < NLEV, and then the PRF record in the header section is immediately followed by a records containing NLEV LEV_FLG values to indicate the particular retrieval levels (1=used, 0=skipped).

Common Pixel Headers

Structure
3 records, different for limb and nadir-viewing geometries.
Common Pixel Header (Nadir-Viewing)
IPIX       = Pixel# Pixel counter
!YYYYMMDD HHMMSS MILLISEC STP FOV LAT LON ZEN SZA %CLD %LND Header record
        YMD HMS MSC STP FOV LAT LON ZEN SZA CLD LND
Common Pixel Header (Limb-Viewing)
IPIX       = Pixel# Profile location counter
!YYYYMMDD HHMMSS MILLISEC LAT LON LST SZA Header record
        YMD HMS MSC LAT LON LST SZA

Fields
Field Format Description Units Range
IPIX I10 Pixel number 1 : NPIX
YMD I9.8 Date of the scan eg ' 20020724' yyyymmdd
HMS I7.6 Time (UT) of the scan eg ' 113640' hhmmss 000000 : 235959
MSC I9 Milliseconds into day ms 0 : 86 399 999
STP I4 (Nadir) IASI Mirror step# 1 : 30
FOV I4 (Nadir Only) IASI Pixel/FOV# 1:4
LAT F7.2 Latitude in [deg N] -90:+90
LON F8.2 Longitude in [deg E] -180:+180
ZEN F7.2 (Nadir Only) Satellite Zenith Angle [deg from zenith] 0:90
LST F7.4 (Limb Only) Local Solar Time [h] eg '10.1200'
SZA F7.2 Solar Zenith Angle [deg from zenith] -90:+90 (>0 for daytime)
CLD F7.1 (Nadir Only) Cloud fraction in FOV [%] 0:100
LND F7.1 (Nadir Only) Land fraction in FOV [%] 0:100

Notes
  1. HMS,MSC: while all the information in HMS is also contained in MSC, it is a more 'human' readable indication of time of day.
  2. The pixel header record HDRPIX is constructed in subroutine l1cnad_sub.f90 (nadir) or l1clim_sub.f90 (limb).
  3. The time and location information for a limb scan is based on that of the central sweep in the scan

Common Pixel Data Structure

The data section for each pixel contains the profile data
Structure
For ISET = 1, NSET
    ! SET_HEADER
    For IPRF = 1, NPRF
        *PRF(j)
        DAT(1,j) DAT(2,j) ... DAT(NLVPRF(j),j)
Fields
FieldTypeDescription
SET_HEADER C* Retrieval step of data within set:
'! Final Result' if ISET=NSET
'! A Priori' if ISET=1 and APR flag
Microwindow Header if ISET<NSET and MWO flag
*PRF(j) C7 Profile j as listed in Common File Header
DAT(i,j) R Profile j data on level i

Common Microwindow Header

Structure
1 record, can be interpreted as comment record
! IMIC MWLABEL WNOMIN WNOUPP [ALTMIN ALTMAX]
Fields
Field Type Description
IMIC I2 Microwindow# in list
MWLABEL A8 Microwindow label
WNOMIN F10.4 Lower wavenumber limit [cm-1]
WNOMAX F10.4 Upper wavenumber limit [cm-1]
ALTMIN F5.1 Lower tangent height limit [km] (if specified)
ALTMAX F5.1 Upper tangent height limit [km] (if specified)
Notes
  1. The header record is composed in subroutine addmic_sub.f90

morse.log

Description
Text file for logging all status/progress messages.

Format
Text records of any of the following kind
Messages with 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 opening a file
! [comment] 1st record of file just opened (usually a comment)

Notes
  1. The first record will always be:
    R-MORSE: Running MORSE vVERSID
    where VERSID identifies the     MORSE version being run (C11 variable VIDHDR in file hdrcom_dat.f90, set in main program module morse.f90).
  2. For a successfully completed run the last message will be
    R-MORSE: Successful completion

Examples
morse.log from NH3 retrieval (generated with driver table morse_nh3.drv)

morse.rtv

Description
Retrieved State Vector & Standard Deviation (random error)

Structure
Common File Format

Common File Header
  1. NSET is normally 1, but increased by 1 if the APR flag is set, and/or increased by N.Mic if the MWO flag is set.
  2. NPRF: Apart from the retrieved profiles and their associated SD profiles, the total includes the following additional profiles
    • Nadir-viewing: SFCPRE(1) (single value)
    • Limb-viewing: HGT
    • Limb-viewing: CLD_FLG (if CLD flag is set, 1=cloud-contaminated sweep, 0=cloud free)
    • Limb-viewing: PRE (if not retrieving pressure)
  3. PRF The name/label of the profile is the same as entered in the *RTV section of the driver table (and, if more than one, in the same order). For limb-viewing, the microwindow-specified retrievals of continuum (CTM) and radiometric offset (OFF), will only be output if the MWO Flag is enabled.
  4. LEV_FLG It is possible to specify certain retrievals on subsets of the full grid, in which case the PRF record in the header section is immediately followed by a records containing LEV_FLG values to indicate the particular retrieval levels (1=used, 0=skipped).

Examples
morse_pt.rtv from pT limb retrieval
morse_nh3.rtv from NH3 nadir (column) retrieval

morse.orb

Description
Retrieved atmospheric profiles for orbit

Structure
Common File Format

Common File Header

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.orb files are recommended for passing the information from one retrieval into another retrieval from the same scan via the *ATM section of the driver table.

Examples
morse_pt.orb from MIPAS pT retrieval

morse.res (optional)

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

Format
! Residual spectra generated by MORSE v.VERSID
! HDRREC
NPIX NMIC = No. pixels, microwindows
For IPIX = 1, NPIX
   [Common Pixel Header]
   For IMIC = 1, NMIC
     [Common Microwindow Header]
IMIC NSWP NPTS = MW#, NSweeps, NPoints
     For ISWP = 1, NSWP
ISWP = Sweep index
FLG(1), FLG(2) ... FLG(NPTS)
SPC(1), SPC(2) ... SPC(NPTS)
FieldTypeDescription
VERSID C11 MORSE version identifier
HDRREC C79 From *HDR section of the driver table
NPIX I10 No. of pixels or profile locations
NMIC I10 No. of microwindows used in retrieval
IMIC I10 Index of microwindow, in range 1:NMIC
NSWP I10 No. of sweeps for MW
NPTS I10 No. of spectral points for MW
ISWP I10 Index of sweep, in range 1:NSWP
FLG(i) I2 1=used point, 0=masked point
SPC(i) F Residual spectrum values

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.

Example
morse.res

morse.swp

Description
Sweep(=spectrum) Diagnostics

Structure
Common File Format
  1. NSET is normally 1, but set to NMIC (No. of microwindows) if the MWO Flag is set
  2. NPRF = 7 for limb-viewing, 4 for nadir-viewing, with the following profiles.
PRF Geometry Description
CLD_FLG Limb 1=flagged/excluded as cloudy, 0=Not flagged
CLD_IDX Limb ULe Cloud Index (ratio of radiances in 2 regions)
CLD_RAD Limb Cloud channel radiance
N_MIC Both No. of microwindows used from this sweep
N_ITR Both Total No. of iterations for this sweep
N_NOCNV Both No. microwindows which did not converge
CHISQ Both Average chi-squared statistic for retrievals

Examples
morse_pt.swp from pT retrieval
morse_h2o.swp from H2O retrieval
Back to MORSE Index