API Reference

Submodules

impacts_tools.er2 module

Classes for IMPACTS ER2 Instruments

class impacts_tools.er2.Crs(filepath, start_time=None, end_time=None, atten_file=None, max_roll=None, dbz_sigma=None, vel_sigma=None, width_sigma=None, ldr_sigma=None, dbz_min=None, vel_min=None, width_min=None)

Bases: impacts_tools.er2.Radar

A class to represent the CRS nadir pointing radar flown on the ER2 during the IMPACTS field campaign. Inherits from Radar()

Parameters

  • filepath (str) – File path to the CRS data file

  • start_time (np.datetime64 or None) – The initial time of interest eg. if looking at a single flight leg

  • end_time (np.datetime64 or None) – The final time of interest eg. if looking at a single flight leg

  • atten_file (str or None) – Path to file containing gridded attenuation due to atmospheric gases

  • max_roll (float or None) – The maximum roll angle of the aircraft in degrees, used to mask times with the aircraft is turning and the radars are off-nadir

  • dbz_sigma (float or None) – The standard deviation to use in despeckling the radar reflectivity. Data above threshold is masked using a Gaussian filter

  • vel_sigma (float or None) – The standard deviation to use in despeckling the radar Doppler velocity. Data above threshold is masked using a Gaussian filter

  • width_sigma (float or None) – The standard deviation to use in despeckling the radar spectrum width. Data above threshold is masked using a Gaussian filter

  • ldr_sigma (float or None) – The standard deviation to use in despeckling the radar linear depolarization ratio. Data above threshold is masked using a Gaussian filter

  • dbz_min (float or None) – The minimum radar reflectivity value

  • vel_min (float or None) – The minimum Doppler velocity value of interest. Data will be masked below threshold (m/s)

  • width_min (float or None) – The minimum spectrum width value of interest. Data will be masked below threshold (m/s)

correct_ice_atten(hiwrap, hrrr)
data

xarray.Dataset of radar variables and attributes

Dimensions:

  • range: xarray.DataArray(float) - The radar range gate

  • time: np.array(np.datetime64[ns]) - The UTC time stamp

Coordinates:

  • range (range): xarray.DataArray(float) - The radar range gate

  • height (range, time): xarray.DataArray(float) - Altitude of each range gate (m)

  • time (time): np.array(np.datetime64[ns]) - The UTC time stamp

  • distance (time): xarray.DataArray(float) - Along-track distance from the flight origin (m)

  • lat (time): xarray.DataArray(float) - Latitude (degrees)

  • lon (time): xarray.DataArray(float) - Longitude (degrees)

Variables:

  • dbz (range, time) : xarray.DataArray(float) - Equivalent reflectivity factor (db) with 1-sigma noise threshold applied

  • vel (range, time) : xarray.DataArray(float) - Doppler velocity corrected to account for intrusion of horizontal reanalysis winds and nonuniform beam filling (m/s)

  • width (range, time) : xarray.DataArray(float) - Doppler velocity spectrum width estimate including aircraft motion. 1-sigma noise threshold applied (m/s)

  • ldr (range, time) : xarray.DataArray(float) - Linear depolarization ratio thresholded at 3-sigma (dB)

  • vel_horiz_offset (range, time) : xarray.DataArray(float) - The horizontal wind offset used to correct Ka-band Doppler velocity [Vel_corr = Vel_uncorr - nubf_offset - horizwind_offset] (m/s)

  • vel_nubf_offset (range, time) : xarray.DataArray(float) - The nonuniform beam filling (NUBF) offset used to correct Ku-band Doppler velocity (m/s)

  • channel_mask (range, time): xarray.DataArray(int) - Composite image channel mask. 0: No signal, 1: Low-resolution pulse, 2: High-resolution pulse, 3: Chirp

  • horizontal_resolution_ku (range) : xarray.DataArray(float) - Approximate horizontal resolution defined as width of spatial weighting after averaging as a function of radar range (m)

  • dxdr (time) : xarray.DataArray(float) - Data cross-track distance from aircraft per radar range. Positive is starboard direction (m/m)

  • dydr (time) : xarray.DataArray(float) - Data along-track distance from aircraft per radar range. Positive is forward direction (m/m)

  • dzdr (time) : xarray.DataArray(float) - Data vertical distance from aircraft per radar range. Positive is upward direction (m/m)

  • er2_altitude (time) : xarray.DataArray(float) - Aircraft height above sea level (m)

  • er2_heading (time) : xarray.DataArray(float) - Aircraft heading in degrees from north. 90 degrees is eastward pointing (degrees)

  • er2_pitch (time) : xarray.DataArray(float) - Aircraft pitch (degrees)

  • er2_roll (time) : xarray.DataArray(float) - Aircraft roll (degrees)

  • er2_drift (time) : xarray.DataArray(float) - Distance between track and heading (degrees)

  • er2_EastVel (time) : xarray.DataArray(float) - Eastward component of velocity (m/s)

  • er2_NorthVel (time) : xarray.DataArray(float) - Northward component of velocity (m/s)

  • er2_upVel (time) : xarray.DataArray(float) - Upward velocity (m/s)

  • er2_track (time) : xarray.DataArray(float) - Direction from motion in degrees from north. 90 degrees is eastward motion (degrees)

  • er2_motion (time) : xarray.DataArray(float) - Estimated aircraft motion notmal to the beam, subtracted from Doppler estimate. Smoothed to a 2 second average motion (m/s)

Attribute Information:

Experiment, Date, Aircraft, Radar Name, Data Contact, Instrument PI, Mission PI, Antenna Size, Antenna one-way 3dB beamwidth (degrees), Number of pulses, Radar transmit frequency (Hz), Radar transmit wavelength (m), Range gate spacing (m), Nominal antenna pointing, PRI, vertical resolution

readfile(filepath, start_time=None, end_time=None)

Reads the CRS data file and unpacks the fields into an xarray.Dataset

Parameters

  • filepath (str) – Path to the data file

  • start_time (np.datetime64 or None) – The initial time of interest

  • end_time (np.datetime64 or None) – The final time of interest

Returns

data – The unpacked dataset

Return type

xarray.Dataset

class impacts_tools.er2.Er2(date, filepath)

Bases: object

A class to represent the ER2 aircraft during the IMPACTS field campaign

timearray(datetime)

the time in UTC

latarray(float)

the latitude of the ER2

lonarray(float)

the longitude of the ER2

altarray(float)

the altitude of the ER2

pitcharray(float)

the pitch of the aircraft

rollarray(float)

the roll of the aircraft

driftarray(float)

the drift of the aircraft

flight_legs: array(datetime)

an array containing the start and end time of each flight leg during a storm

classmethod from_instrument(er2params)

Alternative constructor to initialize the ER2 object directly from an instrument data file

Parameters

er2params (xarray.DataSet()) – a dataset of attributes to populate the ER2 object if it’s initialized from an instrument

readfile(filepath)
class impacts_tools.er2.Exrad(filepath, start_time=None, end_time=None, atten_file=None, max_roll=None, dbz_sigma=None, vel_sigma=None, width_sigma=None, dbz_min=None, vel_min=None, width_min=None)

Bases: impacts_tools.er2.Radar

A class to represent the EXRAD nadir pointing radar flown on the ER2 during the IMPACTS field campaign. Inherits from Radar()

Parameters

  • filepath (str) – File path to the CRS data file

  • start_time (np.datetime64 or None) – The initial time of interest eg. if looking at a single flight leg

  • end_time (np.datetime64 or None) – The final time of interest eg. if looking at a single flight leg

  • atten_file (str or None) – Path to file containing gridded attenuation due to atmospheric gases

  • max_roll (float or None) – The maximum roll angle of the aircraft in degrees, used to mask times with the aircraft is turning and the radars are off-nadir

  • dbz_sigma (float or None) – The standard deviation to use in despeckling the radar reflectivity. Data above threshold is masked using a Gaussian filter

  • vel_sigma (float or None) – The standard deviation to use in despeckling the radar Doppler velocity. Data above threshold is masked using a Gaussian filter

  • width_sigma (float or None) – The standard deviation to use in despeckling the radar spectrum width. Data above threshold is masked using a Gaussian filter

  • dbz_min (float or None) – The minimum radar reflectivity value

  • vel_min (float or None) – The minimum Doppler velocity value of interest. Data will be masked below threshold (m/s)

  • width_min (float or None) – The minimum spectrum width value of interest. Data will be masked below threshold (m/s)

correct_attenuation(atten_file)

Correct reflectivity for attenuation at X-band due to atmospheric gases.

Parameters

atten_file (str) – filepath to attenuation data

data

xarray.Dataset of radar variables and attributes

Dimensions:

  • range: xarray.DataArray(float) - The radar range gate

  • time: np.array(np.datetime64[ns]) - The UTC time stamp

Coordinates:

  • range (range): xarray.DataArray(float) - The radar range gate

  • height (range, time): xarray.DataArray(float) - Altitude of each range gate (m)

  • time (time): np.array(np.datetime64[ns]) - The UTC time stamp

  • distance (time): xarray.DataArray(float) - Along-track distance from the flight origin (m)

  • lat (time): xarray.DataArray(float) - Latitude (degrees)

  • lon (time): xarray.DataArray(float) - Longitude (degrees)

Variables:

  • dbz (range, time) : xarray.DataArray(float) - Equivalent reflectivity factor (db) with 1-sigma noise threshold applied

  • vel (range, time) : xarray.DataArray(float) - Doppler velocity corrected to account for intrusion of horizontal reanalysis winds and nonuniform beam filling (m/s)

  • width (range, time) : xarray.DataArray(float) - Doppler velocity spectrum width estimate including aircraft motion. 1-sigma noise threshold applied (m/s)

  • vel_horiz_offset (range, time) : xarray.DataArray(float) - The horizontal wind offset used to correct Ka-band Doppler velocity [Vel_corr = Vel_uncorr - nubf_offset - horizwind_offset] (m/s)

  • vel_nubf_offset (range, time) : xarray.DataArray(float) - The nonuniform beam filling (NUBF) offset used to correct Ku-band Doppler velocity (m/s)

  • channel_mask (range, time): xarray.DataArray(int) - Composite image channel mask. 0: No signal, 1: Low-resolution pulse, 2: High-resolution pulse, 3: Chirp

  • horizontal_resolution_ku (range) : xarray.DataArray(float) - Approximate horizontal resolution defined as width of spatial weighting after averaging as a function of radar range (m)

  • dxdr (time) : xarray.DataArray(float) - Data cross-track distance from aircraft per radar range. Positive is starboard direction (m/m)

  • dydr (time) : xarray.DataArray(float) - Data along-track distance from aircraft per radar range. Positive is forward direction (m/m)

  • dzdr (time) : xarray.DataArray(float) - Data vertical distance from aircraft per radar range. Positive is upward direction (m/m)

  • er2_altitude (time) : xarray.DataArray(float) - Aircraft height above sea level (m)

  • er2_heading (time) : xarray.DataArray(float) - Aircraft heading in degrees from north. 90 degrees is eastward pointing (degrees)

  • er2_pitch (time) : xarray.DataArray(float) - Aircraft pitch (degrees)

  • er2_roll (time) : xarray.DataArray(float) - Aircraft roll (degrees)

  • er2_drift (time) : xarray.DataArray(float) - Distance between track and heading (degrees)

  • er2_EastVel (time) : xarray.DataArray(float) - Eastward component of velocity (m/s)

  • er2_NorthVel (time) : xarray.DataArray(float) - Northward component of velocity (m/s)

  • er2_upVel (time) : xarray.DataArray(float) - Upward velocity (m/s)

  • er2_track (time) : xarray.DataArray(float) - Direction from motion in degrees from north. 90 degrees is eastward motion (degrees)

  • er2_motion (time) : xarray.DataArray(float) - Estimated aircraft motion notmal to the beam, subtracted from Doppler estimate. Smoothed to a 2 second average motion (m/s)

Attribute Information:

Experiment, Date, Aircraft, Radar Name, Data Contact, Instrument PI, Mission PI, Antenna Size, Antenna one-way 3dB beamwidth (degrees), Number of pulses, Radar transmit frequency (Hz), Radar transmit wavelength (m), Range gate spacing (m), Nominal antenna pointing, PRI, vertical resolution

readfile(filepath, start_time=None, end_time=None)

Reads the EXRAD data file and unpacks the fields into an xarray.Dataset

Parameters

  • filepath (str) – Path to the data file

  • start_time (np.datetime64 or None) – The initial time of interest

  • end_time (np.datetime64 or None) – The final time of interest

Returns

data – The unpacked dataset

Return type

xarray.Dataset

class impacts_tools.er2.Hiwrap(filepath, start_time=None, end_time=None, atten_file=None, max_roll=None, dbz_sigma=None, vel_sigma=None, width_sigma=None, dbz_min=None, vel_min=None, width_min=None)

Bases: impacts_tools.er2.Radar

A class to represent the HIWRAP nadir pointing radar flown on the ER2 during the IMPACTS field campaign. Inherits from Radar()

Parameters

  • filepath (str) – File path to the CRS data file

  • start_time (np.datetime64 or None) – The initial time of interest eg. if looking at a single flight leg

  • end_time (np.datetime64 or None) – The final time of interest eg. if looking at a single flight leg

  • atten_file (str or None) – Path to file containing gridded attenuation due to atmospheric gases

  • max_roll (float or None) – The maximum roll angle of the aircraft in degrees, used to mask times with the aircraft is turning and the radars are off-nadir

  • dbz_sigma (float or None) – The standard deviation to use in despeckling the radar reflectivity. Data above threshold is masked using a Gaussian filter

  • vel_sigma (float or None) – The standard deviation to use in despeckling the radar Doppler velocity. Data above threshold is masked using a Gaussian filter

  • width_sigma (float or None) – The standard deviation to use in despeckling the radar spectrum width. Data above threshold is masked using a Gaussian filter

  • ldr_sigma (float or None) – The standard deviation to use in despeckling the radar linear depolarization ratio. Data above threshold is masked using a Gaussian filter

  • dbz_min (float or None) – The minimum radar reflectivity value

  • vel_min (float or None) – The minimum Doppler velocity value of interest. Data will be masked below threshold (m/s)

  • width_min (float or None) – The minimum spectrum width value of interest. Data will be masked below threshold (m/s)

correct_attenuation(atten_file)
correct_roll(max_roll)

Mask values in the dataset where the roll angle of the ER2 is greater than the maximum value provided

Parameters

max_roll (float) – The maximum roll angle of the aircraft in degrees

data

xarray.Dataset of radar variables and attributes

Dimensions:

  • range: xarray.DataArray(float) - The radar range gate

  • time: np.array(np.datetime64[ns]) - The UTC time stamp

Coordinates:

  • range (range): xarray.DataArray(float) - The radar range gate

  • height (range, time): xarray.DataArray(float) - Altitude of each range gate (m)

  • time (time): np.array(np.datetime64[ns]) - The UTC time stamp

  • distance (time): xarray.DataArray(float) - Along-track distance from the flight origin (m)

  • lat (time): xarray.DataArray(float) - Latitude (degrees)

  • lon (time): xarray.DataArray(float) - Longitude (degrees)

Variables:

  • dbz_ka (range, time) : xarray.DataArray(float) - Ka-band equivalent reflectivity factor (db) with 1-sigma noise threshold applied

  • dbz_ku (range, time) : xarray.DataArray(float) - Ku-band equivalent reflectivity factor (db) with 1-sigma noise threshold applied

  • vel_ka (range, time) : xarray.DataArray(float) - Ka-band Doppler velocity corrected to account for intrusion of horizontal reanalysis winds and nonuniform beam filling (m/s)

  • vel_ku (range, time) : xarray.DataArray(float) - Ku-band Doppler velocity corrected to account for intrusion of horizontal reanalysis winds and nonuniform beam filling (m/s)

  • width_ka (range, time) : xarray.DataArray(float) - Ka-band Doppler velocity spectrum width estimate including aircraft motion. 1-sigma noise threshold applied (m/s)

  • width_ku (range, time) : xarray.DataArray(float) - Ku-band Doppler velocity spectrum width estimate including aircraft motion. 1-sigma noise threshold applied (m/s)

  • ldr_ka (range, time) : xarray.DataArray(float) - Ka-band linear depolarization ratio thresholded at 3-sigma (dB)

  • ldr_ku (range, time) : xarray.DataArray(float) - Ku-band linear depolarization ratio thresholded at 3-sigma (dB)

  • vel_horiz_offset_ka (range, time) : xarray.DataArray(float) - The horizontal wind offset used to correct Ka-band Doppler velocity [Vel_corr = Vel_uncorr - nubf_offset - horizwind_offset] (m/s)

  • vel_horiz_offset_ku (range, time) : xarray.DataArray(float) - The horizontal wind offset used to correct Ku-band Doppler velocity [Vel_corr = Vel_uncorr - nubf_offset - horizwind_offset] (m/s)

  • vel_nubf_offset_ku (range, time) : xarray.DataArray(float) - The nonuniform beam filling (NUBF) offset used to correct Ku-band Doppler velocity (m/s)

  • channel_mask_ka (range, time): xarray.DataArray(int) - Composite Ka-band image channel mask. 0: No signal, 1: Low-resolution pulse, 2: High-resolution pulse, 3: Chirp

  • channel_mask_ku (range, time): xarray.DataArray(int) - Composite Ku-band image channel mask. 0: No signal, 1: Low-resolution pulse, 2: High-resolution pulse, 3: Chirp

  • horizontal_resolution_ka (range) : xarray.DataArray(float) - Approximate horizontal resolution defined as width of spatial weighting after averaging as a function of radar range (m)

  • horizontal_resolution_ku (range) : xarray.DataArray(float) - Approximate horizontal resolution defined as width of spatial weighting after averaging as a function of radar range (m)

  • dxdr (time) : xarray.DataArray(float) - Data cross-track distance from aircraft per radar range. Positive is starboard direction (m/m)

  • dydr (time) : xarray.DataArray(float) - Data along-track distance from aircraft per radar range. Positive is forward direction (m/m)

  • dzdr (time) : xarray.DataArray(float) - Data vertical distance from aircraft per radar range. Positive is upward direction (m/m)

  • er2_altitude (time) : xarray.DataArray(float) - Aircraft height above sea level (m)

  • er2_heading (time) : xarray.DataArray(float) - Aircraft heading in degrees from north. 90 degrees is eastward pointing (degrees)

  • er2_pitch (time) : xarray.DataArray(float) - Aircraft pitch (degrees)

  • er2_roll (time) : xarray.DataArray(float) - Aircraft roll (degrees)

  • er2_drift (time) : xarray.DataArray(float) - Distance between track and heading (degrees)

  • er2_EastVel (time) : xarray.DataArray(float) - Eastward component of velocity (m/s)

  • er2_NorthVel (time) : xarray.DataArray(float) - Northward component of velocity (m/s)

  • er2_upVel (time) : xarray.DataArray(float) - Upward velocity (m/s)

  • er2_track (time) : xarray.DataArray(float) - Direction from motion in degrees from north. 90 degrees is eastward motion (degrees)

  • er2_motion (time) : xarray.DataArray(float) - Estimated aircraft motion notmal to the beam, subtracted from Doppler estimate. Smoothed to a 2 second average motion (m/s)

Attribute Information:

Experiment, Date, Aircraft, Radar Name, Data Contact, Instrument PI, Mission PI, Antenna Size, Antenna one-way 3dB beamwidth (degrees), Number of pulses, Radar transmit frequency (Hz), Radar transmit wavelength (m), Range gate spacing (m), Nominal antenna pointing, PRI, vertical resolution

readfile(filepath, start_time=None, end_time=None)

Reads the HIWRAP data file and unpacks the fields into an xarray.Dataset

Parameters

  • filepath (str) – Path to the data file

  • start_time (np.datetime64 or None) – The initial time of interest

  • end_time (np.datetime64 or None) – The final time of interest

Returns

data – The unpacked dataset

Return type

xarray.Dataset

class impacts_tools.er2.Radar

Bases: abc.ABC

A class to represent the various radars flown on the ER-2 aircraft during IMAPCTS. Radar is an Abstract Base Class - meaning we always require a more specific class to be instantiated - ie you have to call Exrad() or Hiwrap(), you can’t just call Radar()

Parameters

data (xarray.Dataset()) – Radar data and attributes

correct_roll(max_roll)

Mask values in the dataset where the roll angle of the ER2 is greater than the maximum value provided

Parameters

max_roll (float) – The maximum roll angle of the aircraft in degrees

despeckle(data_array=None, sigma=1.0)

Despeckle the radar data by applying a Gaussion filter with a given standard deviation

Parameters

  • data_array (xarray.DataArray()) – The field to despeckle

  • sigma (float) – The standard deviation to apply to the gaussian filter

get_flight_legs()

Get the start and end time stamps for each leg of this flight.

Returns

flight_leg – Tuples of the start and end time of each flight leg.

Return type

list of tuples

abstract readfile(filepath)

This is an abstract method since only inherited classes will be used to read radar data into objects.

class impacts_tools.er2.VAD(filepath)

Bases: object

A class to represent the Velocity-Azimuth Display (VAD) wind product derived from the EXRAD conical scans during the IMPACTS field campaign.

Parameters

data (xarray.Dataset) – dataset containing VAD data and attributes

readfile(filepath, start_time=None, end_time=None)

Reads the VAD data file and unpacks the fields into an xarray.Dataset

Parameters

  • filepath (str) – Path to the data file

  • start_time (np.datetime64 or None) – The initial time of interest

  • end_time (np.datetime64 or None) – The final time of interest

Returns

data – The unpacked dataset

Return type

xarray.Dataset

regrid_to_radar(radar)

Regrids the VAD data to a nadir radar object, EXRAD, HIWRAP, or CRS

Parameters

radar (er2.Radar) – the radar object to regrid to

Returns

regridded_data_2 – the VAD data set interpolated to the Radar grid

Return type

xarray.Dataset

impacts_tools.p3 module

Classes for IMPACTS P3 Instruments

class impacts_tools.p3.P3(filepath, date)

Bases: object

readfile(filepath)

Module contents