Univeristy of Alabama in Huntsville

UAH LTG IDL Library

IDL Routines from Phillip Bitzer and UAH Lightning Group

summary     class     fields     routine details     file attributes

lis/

read_lis.pro

Category


The purpose of this procedure is to read in orbit information from a set of LIS (Lightning Imaging Sensor) HDF VData files and return a single variable containing an array of structures of the field values.

If no keywords are selected, by default the program returns "lightning data" containing area, flash, group, and event data.

Depending on the keyword used, any/some of several structures can be returned. Here are the fields and their descriptions:

ORBIT_SUMMARY: id_number The number of this orbit, where the orbit count starts at launch. (-) TAI93_start Start of this orbit in TAI93 time (sec) UTC_start Start of this orbit in UTC time. (-) GPS_start Sart of this orbit in GPS time. (sec) TAI93_end End of this orbit in TAI93 time. (sec) start_longitude Longitude boundary defining start of this orbit. (deg) end_longitude Longitude boundary defining end of this orbit. (deg) point_data_count Number of point data elements associated with this orbit. (-) point_data_address Address of the first element in point data structure. (-) one_second_count The number of elements in the one second data. (-) one_second_address The address of the first element in the one second data. (-) summary_image_count The number of summary GIF images. (-) summary_image_address The address of the first summary GIF image. (-) inspection_code Code indicating which problem scenarios were checked by the QA inspector. (-) config_code Code indicating which code configuration scenario was used when processing the data. (-) ONE_SECOND: TAI93_time Whole second value starting before and continuting beyond one orbit. (sec) alert_summary Bit masked summary of alert flags (see below). (-) instrumental_alert Bit masked status of instrument (see below). (-) platform_alert Bit masked status of platform (see below). (-) external_alert Bit masked status of external factors (see below). (-) processing_alert Bit masked status of processing algorithms (see below). (-) position_vector Location of platforms in ECR coordinates. (m) velocity_vector Velocity of platform in ECR coordinates. (m) transform_matrix Components of transform from pixel plane-boresight coordinates to ECR coordinates of boresight and pixel plane. (-) solar_vector Unit vector from center of earth to sun in ECR coordinates. (-) ephemeris_quality_flag Bit masked status (see below). (-) attitude_quality_flag Bit masekd status (see below). (-) boresight_threshold Most likely threshold value applied to the boresight position given the solar zenith angle, assuming clouds present. (-) thresholds Values of the instrument threshold settings for each 256 count background interval. (-) noise_index A metric that indicates the noise level. (%*100) event_count Raw evnt count and counts surviving filters at each processing stage. (-) POINT_SUMMARY parent_address Address of parent (orbit). (-) event_count Number of events in orbit. (-) event_address Address of first event. (-) group_count Number of groups in orbit. (-) group_address Address of first group. (-) flash_count Number of flashes in orbit. (-) flash_address Address of first flash. (-) area_count Number of areas in orbit. (-) area_address Address of first area. (-) bg_count Number of background image summary records in orbit. (-) bg_address Address of first background image summary. (-) vt_count Number of viewtime granules in orbit. (-) vt_address Address of first viewtime granule in orbit. (-) VIEWTIME location The Lat/Lon of the center of the grid cell of dimensions 0.5 deg x 0.5 deg. (deg) TAI93_start TAI93 whole second when location was first within FOV. (sec) TAI93_end TAI93 whole second when location was last within FOV. (sec) effective_obs Time of observation of the grid cell, adjusted by the percentage of area in the grid cell within the FOV. (sec) alert_flag Reflects status of instrument, platform, external factors and processing algorithms. (-) approx_threshold Threshold of instrument corresponding with grid cell position, proxied from solar zenith angle at a time halfway between start and end time. (-) BG_SUMMARY TAI93_time TAI93 time of the background image. (sec) address Image number within orbit. (-) boresight The Lat/Lon location of center pixel (63,64). (deg) corners The Lat/Lon locations of corner pixels. (-) AREA TAI93_time TAI93 time of 1st event in area. (sec) delta_time Time between first and last event that compose the area. (sec) observe_time Duration of observation of the region where the area occurred. (sec) location Lat/Lon radiance-weighted centroid. (deg) net_radiance Sum of event radiances composing this area. (uJ/ster/m2/um) footprint Unique areal extent. (sq km) address Area address. (-) parent_address Pointer to parent's address (point data). (-) child_address Address of 1st flash in a sequential list. (-) child_count Number of flashes in area. (-) grandchild_count Number of groups in area. (-) greatgrandchild_count Number of events in area. (-) approx_threshold Estimated value of 8-bit threshold for the area determined from background level or solar zenith angle. (-) alert_flag Bit masked status of instrument, platform, external factors, and processing algorithms. (-) cluster_index Pixel density metric; higher numbers indicate area is less likely to be noise. (0-99) density_index Spatial density metric; higher if area geolocated in a region of high lightning activity. (-) noise_index Signal - to - signal plus noise ratio. (%*100) oblong_index Metric indicating how oblong the area is. (-) grouping_sequence Time sequence of area used when grouping algorithm is supplied. (-) grouping_status 0 = area grouped normally; 1 = area split between orbits; 2 = area aplit between orbits; 3 = grouping algorithm failed (-) FLASH TAI93_time TAI93 time of 1st event in flash. (sec) delta_time Time between first and last group that compose the flash. (sec) observe_time Duration of observation of the region where the flash occurred. (sec) location Lat/Lon radiance-weighted centroid. (deg) radiance Sum of event radiances composing this flash. (uJ/ster/m2/uum) footprint Unique areal extent. (-) address Flash address. (-) parent_address Pointer to parent's address (area). (-) child_address Address of 1st group in a sequential list. (-) child_count Number of groups in flash. (-) grandchild_count Number of events in flash. (-) approx_threshold Estimated value of 8-bit threshold for the flash determined from background level or solar zenith angle. (-) alert_flag Bit masked status of instument, platform, external factors and processing algorithm. (-) cluster_index Pixel density metric; higher numbers indicate flash is less likely to be noise. (0-99) density_index Spatial density metric; higher if flash geolocated ina region of high lightning activity. (-) noise_index Signal - to - signal plus noise ratio. (%*100) glint_index Cosine of angle. (-) oblong_index Metric indicating how oblong the flash is. (-) grouping_sequence Time sequence of flash used when grouping algorithm is applied. (-) grouping_status 0 = flash grouped normally; 1 = flash aplit betwen orbits; (-) 2 = flash split between orbits; 3 = grouping algorithm failed. GROUP TAI93_time TAI93 time of 1st event in group. (sec) observe_time Duration of observation of the region where the group occurred. (sec) locaiton Lat/Lon radiance-weighted centroid. (deg) radiance Sum of event radicnes composing this group. (uJ/ster/m2/um) footprint Unique areal extent. (sq km) address Flash address. (-) parent_address Pointer to parent's address (flash). (-) child_address Address of 1st event in a sequential list. (-) child_count Number of events in group. (-) approx_threshold Estimated value of 8-bit threshold for the group determined from background level or solar zenith angle. (-) alert_flag Bit masked status of instrument, platform, external factors and processing algorithm. (-) cluster_index Pixel density metric; higher numbers indicate group is less likely to be nosie. (0-99) density_index Spatial density metric; higher if group geolocated in a region of high lightning activity. (-) noise_index Signal - to - signal plus noise ratio. (%*100) glint_index Cosine of angle. (-) oblong_index Metric indicating how oblong the group is. (-) grouping_sequence Time sequence of group used when grouping algorithm is applied. (-) groupint_status 0 = group grouped normally; 1 = group split between orbits; 2 = group split between orbits; 3 = grouping algorithm failed (-) EVENT TAI93_time TAI93 time of event. (sec) obseve_time Duration of observation of the region where the event occurred. (sec) location Lat/Lon radiance-weighted centroid. (deg) radiance Radiance of this event. (uJ/ster/m2/um) footprint Unique areal extent. (sq km) address Flash address. (-) parent_address Pointer to parent's address (group). (-) x_pixel CCD pixel column. (-) y_pixel CCD pixel row. (-) bg_value Level of background illumination (16-bit) at time of event. (-) bg_radiance Background radiance associated with pixel at time of event. (W/ster/m2/um) amplitude Uncalibrated optical amplitude reported by instrument. (-) sza_index Solar zeith angle. (deg) glint_index Angle between line of sight vector and direct solar reflection vector. (deg) approx_threshold Estimated value of 8-bit threshold for the event; from bg level or solar zenith angle. (-) alert_flag Bit masked status of instrument, platform, external factors, and processing algorithm. (-) cluster_index Pixel density metric; higher numbers indicate event less likely to be noise. (0-99) density_index Spatial density metric; higher if event geolocated in a region of high lightning activity. (-) noise_index Signal - to - signal plus noise ratio. (%*100) bg_value_flag Bg radiance has been 0: estimated from s.z.a. 1: interplated from bgs. (-) groupint_sequence Time sequence of event used when grouping algorithm is applied. (-)

Examples

Provide an example

Author information

Author

Veronica Franklin, University of Alabama in Huntsville, vmf0001@uah.edu

History

Modification History:

First written 20110719 VF 7/26/2011 - added /all keyword to procedure VF 5/02/2012 - added error check for no files selected PMB 5/02/2012 - changed "messages"s to errors printed to console and provided an elegant "out" on (non critical) error PMB 6/18/2012 - Fixed error that occurrs when an orbit containing no flash data is read in. VF 8/17/2012 - When UTC keyword is selected, UTC_Start field in the Orbit Summary will now contain the Unix Time for the start of the orbit in place of the string UTC value. (Due to there being both a TAI93_Start and UTC_Start prohibiting simply switching the TAI93_Start to a UTC_Start due to conflicting names. ) VF 1/30/2013 - Added HDF_VD_DETACH and HDF_CLOSE procedures to properly exit out of HDF Files to prevent memory leaks. Set system variable !Quiet to remove annoying % Warning: Mixed data types. Converting to BYTES. Corrected the records_area = UNDEFINED error when only Groups keyword selected VF RST Docuemntation added 20130210 PMB 05/01/2013 - Added quiet keyword PMB 07/08/2013 - There was a error returned when reading in a LIS file with no data. Implemented an ad hoc fix that works by returning a zero array in the pertinent fields (area, flash, group, event). PMB

Other file information

Uses:

CONVERT_TAI93_TO_UNIX

Routines

top read_lis

result = read_lis( [filename] [, /orbit_summary] [, /one_second] [, /point_summary] [, /viewtime] [, /bg_summary] [, /area] [, /flash] [, /group] [, /event] [, /utc] [, /all] [, /Quiet])

The purpose of this procedure is to read in orbit information from a set of LIS (Lightning Imaging Sensor) HDF VData files and return a single variable containing an array of structures of the field values.

Return value

A structure of values, depending on the keyword used. See the file documentation for a complete description.

Parameters

filename in optional type=string or string array

The LIS files you wish to import. If this is not provided, then a dialog appears to select files.

Keywords

orbit_summary in optional type=boolean default=0B

This keyword returns only Orbit Summary information

one_second in optional type=boolean default=0B

This keyword returns only One Second Information

point_summary in optional type=boolean default=0B

This keyword returns only Point Summary Information

viewtime in optional type=boolean default=0B

This keyword returns only Viewtime Information

bg_summary in optional type=boolean default=0B

This keyword returns only Background Summary Information

area in optional type=boolean default=0B

This keyword returns only Area Information

flash in optional type=boolean default=0B

This keyword returns only Flash Information

group in optional type=boolean default=0B

This keyword returns only Group Information

event in optional type=boolean default=0B

This keyword returns only Event Information

utc in optional type=boolean default=0B

This keyword replaces all TAI93_time variables with the corresponding UTC_time in Unix format

all in optional type=boolean default=0B

This keyword returns all variables - note, this cannot be used in conjunction with individual variables

Quiet in optional type=boolean default=0B

If set, informational messages regarding number of files read and routine completion is suppressed.

File attributes

Modification date: Tue Oct 17 17:31:04 2017
Lines: 718
Docformat: rst rst