IASI read_l1c IDL Program
21JAN20
Latest version (v20JAN20): read_l1c.pro

Contents

Overview

read_l1c.pro is a self-contained IDL procedure for reading an IASI L1C .nat file (equivalent to an orbit of data), without requiring any additional libraries such as BEAT/CODA.

Syntax

IDL> READ_L1C, L1CFIL, LOC, SPC, /AVHRR, /BBT, SKPQAL=SKPQAL, WNOLIM=WNOLIM, MPH=MPH, FAIL=FAIL, ERRMSG=ERRMSG

Argument Type I/O Description
L1CFIL STRING I Name of IASI L1C .nat file to be read
LOC STRUCT(*) I/O Structure containing pixel time/location info.
SPC STRUCT(*) O Structure containing selected spectra
AVHRR FLAG I (Optional) 1=Include AVHRR radiance cluster analyses in LOC
BBT FLAG I (Optional) 1=SPC in brightness temperatures [K], 0=Radiance [nW/(cm2.sr.cm-1)]
SKPQAL INT(3) I (Optional) Over-ride band quality flags [v20JAN20 onwards]
MPH STRUCT O (Optional) Main Product Header [v29DEC18 onwards]
FAIL FLAG O (Optional) 0=normal, 1=fatal error occurred
ERRMSG STRING O (Optional) Text describing fatal error, ''=normal

Usage

The initial call of the procedure establishes information about each pixel/spectrum in the file, eg
IDL> READ_L1C, l1cfile.nat, loc
This creates an array structure loc containing information for each pixel. Typically this contains around 91200 array elements (=760 scan lines per orbit x 30 scan steps per line x 4 pixels per scan step). The exact contents of loc are likely to evolve depending on user-requirements but the current structure is outlined below.

The user then calls the procedure again, this time using a subset of loc as input to select specific spectra, and with an additional argument to hold the result. For example, to select only spectra with less than 5% cloud fraction

IDL> idx = WHERE ( loc.cld LT 5.0, nspc )
IDL> READ_L1C, l1cfile.nat, loc[idx], spc
which will return an array structure spc.rad where spc has nspc elements and each spc.rad is a real array of 8461 elements represent radiances in nW/(cm2.sr.cm-1) spanning 645-2760 cm-1 @ 0.25 cm-1.

Alternatively, since spc could still be a very large array, the procedure could also be called to extract spectra sequentially

FOR ipix = 0, npix-1 DO BEGIN
  READ_L1C, l1cfile.nat, loc[idx[ipix]], spc
  [ deal with spc[0].rad ]
ENDFOR
Optional arguments
AVHRR
If set, include AVHRR radiance cluster analyses in LOC output, eg
IDL> READ_L1C, l1cfile.nat, loc, /AVHRR
BBT
If set, convert spectra to brightness temperatures, eg
IDL> READ_L1C, l1cfile.nat, loc[idx], spc, /BBT
will generate spectra as spc.bbt containing brightness temperature spectra [K].
SKPQAL [v20JAN20 onwards]
3-element integer array corresponding to IASI bands (645-1210, 1210-2000, 2000-2760 cm-1) to force the code to include bands otherwise flagged as bad - usually the code would exclude any locations for which any band was flagged as bad.
IDL> READ_L1C, l1cfile.nat, loc, SKPQAL=[1,1,1]
would extract all pixels irrespective of quality flags (although this information is still in the LOC.QAL variable), and
IDL> READ_L1C, l1cfile.nat, loc, SKPQAL=[0,1,1]
would select all pixels for which band 1 quality is good but ignoring the quality flags of the other bands.
ERRMSG
Text string containing any fatal error message, otherwise returned empty, e.g.
IDL> READ_L1C, l1cfile.nat, loc, ERRMSG=ERRMSG
IDL> IF ERRMSG EQ '' THEN PRINT, 'Error: ' + ERRMSG
In the absence of FAIL or ERRMSG arguments the procedure will halt on encountering a fatal error and print the message to the terminal.
FAIL
Output flag showing status of read: 0=OK, 1=fatal error occurred, eg
IDL> READ_L1C, l1cfile.nat, loc, FAIL=FAIL
IDL> IF FAIL THEN PRINT, 'a fatal error occurred'
It can also be combined with the ERRMSG argument:
IDL> READ_L1C, l1cfile.nat, loc, FAIL=FAIL, ERRMSG=ERRMSG
IDL> IF FAIL THEN PRINT, ERRMSG
In the absence of FAIL or ERRMSG arguments the procedure will halt on encountering a fatal error and print the message to the terminal.
MPH [v29DEC18 onwards]
Output structure containing (some) Main Product Header values, eg
IDL> READ_L1C, l1cfile.nat, loc, MPH=MPH
Currently this is limited to MPH.SPACECRAFT_ID, MPH.SENSING_START, MPH.SENSING_END, MPH.ORBIT_START, MPH.ORBIT_END but it should be straightforward to add more if you need them.
WNOLIM
Limit wavenumber range of spectra, where WNOLIM is a 2 element array, eg
IDL> READ_L1C, l1cfile.nat, loc[idx], spc, wnolim=[700,800]
will limit the spc.rad arrays to 700-800cm-1 (ie 401 elements instead of 8461).

LOC Structure

Variable Type Description
LOC.IOF LONG Byte offset of associated spectrum (for internal use) [v29DEC18 onwards]
LOC.LIN INT Scan line# (1-761 typically for a complete orbit)
LOC.STP INT Across track step# (1-30)
LOC.PIX INT Pixel# (1-4)
LOC.DAY UINT Day# since 1 Jan 2000 (= Day 0)
LOC.DAYLIN UINT Day# at start of MDR (= scan line) [v04APR18 onwards]
LOC.MSC LONG Millisecs since start of day
LOC.MSCLIN LONG Millisecs at start of MDR (= scan line) [v04APR18 onwards]
LOC.QAL BYTE(3) Quality flags for each band (0=OK, 1=bad)
LOC.LAT FLOAT Latitude [deg N]
LOC.LON FLOAT Longitude [deg E]
LOC.ZEN FLOAT Zenith angle [deg] at surface (0=nadir view)
LOC.SZA FLOAT Solar zenith angle [deg] at surce (<90=day-time)
LOC.CLD FLOAT Cloud fraction [%] (set -1 for old IASI data)
LOC.LND FLOAT Land fraction [%] (set -1 for old IASI data)
And, with AVHRR flag set:
LOC.NCL INT No. of radiance clusters identified (max 7)
LOC.PCT FLOAT(7) Fraction of FOV occupied by each cluster [%]
LOC.RAV FLOAT(6,7) Mean radiance* for each channel,cluster
LOC.RSD FLOAT(6,7) Radiance* SD for each channel,cluster
* For AVHRR Ch1,2,3a radiances in W/(m2.sr)
For Ch3b,4,5 radiances in nW/(cm2.sr.cm-1)

Version History

20JAN20
Change CHKQAL to SKPQAL (basically inverting definition) so that it actually works!
23AUG19
Fix READU error caused if first MDR is lost data record
Also correct problem reading V4 data
08AUG19
More robust handling of cases with more than 3 IPR records
29DEC18
Internal rewrite. Add optional MPH argument. Add IOF to LOC structure.
04APR18
Add .DAYLIN and .MSCLIN to LOC structure
Change .MSC from ULONG to LONG to allow differencing
19MAR18
Check for Dummy Measurement Data Record
07JUL17
Check for valid geolocation data
21APR17
Add optional FAIL and ERRMSG arguments to control fatal error handling
17APR17
Correction to error messages using MESSGE
Allow for unexpected size MDR - exclude as bad locations (with warning)
02MAR17
Fix bug causing error from -ve value of POINT_LUN (due to byte offset exceeding standard 4 byte LONG integer limit).
28FEB17
Fix bug causing 60cm-1 offset for v4 spectra
24FEB17
Corrects a bug in the BBT conversion when combined with WNOLIM
Add LOC.QAL band quality flags, checks for quality flags, and CHKQAL option to override these.
06FEB17
handle the older format of IASI data which had v4 Measurement Data Records instead of the current v5. The difference is that v5 contains cloud and land % values for each pixel, while v4 does not (these fields are set to -1 in the READ_L1C LOC structure).
13DEC16
Original