gpm.retrievals package#
Submodules#
gpm.retrievals.retrieval_1b_c_pmw module#
This module contains GPM PMW 1B and 1C products community-based retrievals.
- gpm.retrievals.retrieval_1b_c_pmw.retrieve_PCA_RGB(ds, scaler=None)[source][source]#
Create a PCA RGB composite.
- gpm.retrievals.retrieval_1b_c_pmw.retrieve_PCT(xr_obj, variable=None)[source]#
Retrieve PMW Polarization-Corrected Temperature (PCT).
Coefficients are taken from Cecil et al., 2018.
References
Cecil, D. J., and T. Chronis, 2018. Polarization-Corrected Temperatures for 10-, 19-, 37-, and 89-GHz Passive Microwave Frequencies. J. Appl. Meteor. Climatol., 57, 2249-2265, https://doi.org/10.1175/JAMC-D-18-0022.1.
- gpm.retrievals.retrieval_1b_c_pmw.retrieve_PD(xr_obj, variable=None)[source]#
Retrieve PMW Channels Polarized Difference (PD).
- gpm.retrievals.retrieval_1b_c_pmw.retrieve_PESCA(ds, t2m='t2m')[source][source]#
Retrieve PESCA snow-classification.
- gpm.retrievals.retrieval_1b_c_pmw.retrieve_PR(xr_obj, variable=None)[source]#
Retrieve PMW Channels Polarization Ratio (PR).
- gpm.retrievals.retrieval_1b_c_pmw.retrieve_UMAP_RGB(ds, scaler=None, n_neighbors=10, min_dist=0.01, random_state=None, **kwargs)[source][source]#
Create a UMAP RGB composite.
- gpm.retrievals.retrieval_1b_c_pmw.retrieve_mwcc_hail_probability(ds)[source][source]#
Compute MWCC-H hail probability from GMI, SSMIS, ATMS and MHS sensors.
This function implements the MWCC-H (Microwave Cloud Classification - Hail) method to estimate the probability of hail from microwave radiometer observations.
- For GMI, ATMS, and SSMIS, the native channel brightness temperatures are first
mapped to an equivalent MHS 157 GHz V-polarization brightness temperature
(TB_157V,eq) using a linear intercalibration plus a piecewise correction factor. For MHS, the native 157V channel is used directly. The hail probability is then computed as a function of TB_157V,eq following the references below.
- Returns:
Hail probability as a unitless field in the range [0, 1]
- Return type:
Notes
The algorithm uses:
alpha = 104
K = alpha / TB_157V,eq
P_hail = 0.9844 * ln(K) + 0.9072
References
Laviola, S., Levizzani, V., Ferraro, R. R., & Beauchamp, J. 2020. Hailstorm Detection by Satellite Microwave Radiometers. Remote Sensing 12(4), 621. https://doi.org/10.3390/rs12040621
Laviola, S., Monte, G., Levizzani, V., Ferraro, R. R., & Beauchamp, J. 2020. A New Method for Hail Detection from the GPM Constellation: A Prospect for a Global Hailstorm Climatology. Remote Sensing, 12(21), 3553. https://doi.org/10.3390/rs12213553
- gpm.retrievals.retrieval_1b_c_pmw.retrieve_polarization_corrected_temperature(xr_obj, variable=None)[source][source]#
Retrieve PMW Polarization-Corrected Temperature (PCT).
Coefficients are taken from Cecil et al., 2018.
References
Cecil, D. J., and T. Chronis, 2018. Polarization-Corrected Temperatures for 10-, 19-, 37-, and 89-GHz Passive Microwave Frequencies. J. Appl. Meteor. Climatol., 57, 2249-2265, https://doi.org/10.1175/JAMC-D-18-0022.1.
- gpm.retrievals.retrieval_1b_c_pmw.retrieve_polarization_difference(xr_obj, variable=None)[source][source]#
Retrieve PMW Channels Polarized Difference (PD).
gpm.retrievals.retrieval_1b_radar module#
This module contains GPM RADAR L1B products community-based retrievals.
- gpm.retrievals.retrieval_1b_radar.get_dielectric_constant(ds, dielectric_constant=None)[source][source]#
Return the dielectric constant.
- gpm.retrievals.retrieval_1b_radar.get_radar_wavelength(ds)[source][source]#
Return the radar wavelength.
- gpm.retrievals.retrieval_1b_radar.open_dataset_1b_ka_fs(start_time, end_time, variables=None, groups=None, product_type='RS', chunks={}, verbose=False, parallel=False, l2_format=True, **kwargs)[source][source]#
Open 1B-Ka dataset in FS scan_mode format in either L1B or L2 format.
It expects start_time after the GPM DPR scan pattern change occurred the 8 May 2018. (Over)Resample HS on MS (using LUT/range distance). The L2 FS format has 176 bins.
Notes
1B-Ka HS has a zig-zag pattern after scan change in 2018 !
1B-Ka HS has 1 scan more than 1B-Ka MS (when queried by time)
1B-Ka HS have range resolution of 250 m (130 bins)
1B-Ka MS have range resolution of 125 m (260 bins)
2A-Ka HS have range resolution of 125 m (88 bins)
2A-Ka MS have range resolution of 125 m (176 bins)
- gpm.retrievals.retrieval_1b_radar.resample_hs_to_fs(ds_hs, smooth=True, except_vars=['echoCount', 'sampling_type'])[source][source]#
Resample HS using LUT.
This function takes care of updating the bin variables and startBinRange`,
rangeBinSizeandellipsoidBinOffset.- Parameters:
ds_hs (xarray.Dataset) – L1B or L2 Ka-band Dataset with HS scan mode.
smooth (bool, optional) – If
smooth=True, applies averaging as presented in the L2 DPR ATBD. Note that ifsmooth=True, the vertical variables and height/distance coordinates will have a duplicated values at range index 0 and 1!. The default is True.except_vars (list, optional) – List of vertical variables to not be smoothed (i.e. count variables).. The default is [“echoCount”].
- Returns:
ds_r – L1B or L2 Ka-band Dataset with resampled range gates (as in FS/NS/MS scan modes).
- Return type:
- gpm.retrievals.retrieval_1b_radar.retrieve_Psignal(ds, echoPower_variable='echoPower')[source][source]#
Retrieve the signal echo power in milliWatt (received echo - noise echo).
- gpm.retrievals.retrieval_1b_radar.retrieve_ellipsoidBinOffset(ds, binEllipsoid_variable='binEllipsoid')[source][source]#
Retrieve distance offset from ellipsoid to the center of the ellipsoid bin.
This can only be used in L1B format.
- gpm.retrievals.retrieval_1b_radar.retrieve_geolocation_3d(ds)[source][source]#
Retrieve the lat, lon, height 3D array.
Requires: scLon, scLat, scLocalZenith, height.
- gpm.retrievals.retrieval_1b_radar.retrieve_height(ds, mask_below_ellipsoid=False)[source][source]#
Retrieve (normal) height from the the ellipsoid.
From GPM DPR ATBD Level 2. Requires: scLocalZenith, ellipsoidBinOffset, rangeBinSize, binEllipsoid
- gpm.retrievals.retrieval_1b_radar.retrieve_range_distance_from_ellipsoid(ds, mask_below_ellipsoid=False)[source][source]#
Retrieve range distance from the ellipsoid.
Requires: ellipsoidBinOffset, rangeBinSize, binEllipsoid
- gpm.retrievals.retrieval_1b_radar.retrieve_range_distance_from_satellite(ds, mask_below_ellipsoid=False, first_option=True)[source][source]#
Retrieve range distance from the satellite (at bin center).
If
first_option=True, requires: scRangeEllipsoid, ellipsoidBinOffset, rangeBinSize, binEllipsoid Iffirst_option=False, requires: startBinRange, rangeBinSize (binEllipsoid)
- gpm.retrievals.retrieval_1b_radar.retrieve_sampling_type(ds)[source][source]#
Retrieve sampling type: low vs high resolution.
- gpm.retrievals.retrieval_1b_radar.retrieve_scRangeDEM(ds)[source][source]#
Retrieve range distance from statellite to DEM.
Requires: scRangeEllipsoid, DEMHmean, scLocalZenith
- gpm.retrievals.retrieval_1b_radar.retrieve_sigmaMeasured(ds, signal_variable='signalPower', local_zenith_angle='scLocalZenith')[source][source]#
Return the Normalized Radar Cross Section (NRCS) (in dB) of a power signal (in dBm).
scLocalZenith in L1B product. LocalZenithAngle in L2 products.
- gpm.retrievals.retrieval_1b_radar.retrieve_signalPower(ds, echoPower_variable='echoPower')[source][source]#
Retrieve the signal power in dBm (received echo - noise echo).
0 dBm means the measured power level is exactly one milliwatt. The higher the power, the more energy is returned. (Echo)Power in dBm is always between -20 and -120 dBm for GPM radar.
gpm.retrievals.retrieval_2a_pmw module#
This module contains GPM PMW 2A products community-based retrievals.
gpm.retrievals.retrieval_2a_radar module#
This module contains GPM RADAR 2A products community-based retrievals.
- gpm.retrievals.retrieval_2a_radar.get_nrange(ds)[source][source]#
Return the number of radar gates in L2 products.
- gpm.retrievals.retrieval_2a_radar.get_range_resolution(ds)[source][source]#
Return the range bin size.
- gpm.retrievals.retrieval_2a_radar.retrieve_EchoDepth(ds, threshold, variable='zFactorFinal', radar_frequency='Ku', min_threshold=0, mask_liquid_phase=False)[source][source]#
Retrieve Echo Depth with reflectivity above xx dBZ.
Common thresholds are 18, 30, 50, 60 dbZ.
- gpm.retrievals.retrieval_2a_radar.retrieve_EchoTopHeight(ds, threshold, variable='zFactorFinal', radar_frequency='Ku', min_threshold=0)[source][source]#
Retrieve Echo Top Height (maximum altitude) for a particular reflectivity threshold.
Common thresholds are 18, 30, 50, 60 dbZ. References: Delobbe and Holleman, 2006; Stefan and Barbu, 2018
- gpm.retrievals.retrieval_2a_radar.retrieve_HailKineticEnergy(ds, variable='zFactorFinal', radar_frequency='Ku', lower_threshold=40, upper_threshold=50)[source][source]#
Compute Hail Kinetic Energy.
Lower and upper reflectivity thresholds are used to retain only higher reflectivities typically associated with hail and filtering out most of the lower reflectivities typically associated with liquid water.
- gpm.retrievals.retrieval_2a_radar.retrieve_MESH(ds, scale_factor=2)[source][source]#
Retrieve the Maximum Estimated Size of Hail (MESH).
Also known as the Maximum Expected Hail Size (MEHS).
The “size” in MESH refers to the maximum diameter (in mm) of a hailstone. It’s an indicator that transforms SHI into hail size by fitting SHI to a chosen percentile of maximum observed hail size (using a power-law)
- gpm.retrievals.retrieval_2a_radar.retrieve_MESHS(ds)[source][source]#
The Maximum Expected Severe Hail Size at the surface.
Based on EchoTop45dBZ.
No hail if EchoDepth45dBZ above melting layer < 1.65 km. 100% hail if EchoDepth45dBZ above melting layer > 5.5 / 5.8 km.
- gpm.retrievals.retrieval_2a_radar.retrieve_POH(ds, method='Foote2005')[source][source]#
The Probability of Hail (POH) at the surface.
Based on EchoDepth45dBZ above melting layer.
No hail if EchoDepth45dBZ above melting layer < 1.65 km. 100% hail if EchoDepth45dBZ above melting layer > 5.5 / 5.8 km. to 100% (hail; Δz > 5.5 km)
- Reference:
Foote et al., 2005. Hail metrics using conventional radar.
- Output probabilities are rounded off to the nearest 10%, to avoid
conveying an unrealistic degree of precision.
- gpm.retrievals.retrieval_2a_radar.retrieve_POSH(ds)[source][source]#
The Probability of Severe Hail (POSH).
The probability of 0.75-inch diameter hail occurring.
When SHI = WT, POSH = 50%. Output probabilities are rounded off to the nearest 10%, to avoid conveying an unrealistic degree of precision.
- gpm.retrievals.retrieval_2a_radar.retrieve_REFC(ds, variable='zFactorFinal', radar_frequency='Ku', mask_bright_band=False, mask_solid_phase=False, mask_liquid_phase=False)[source][source]#
Retrieve the vertical maximum radar reflectivity in the column.
Also called: Composite REFlectivity
- gpm.retrievals.retrieval_2a_radar.retrieve_REFCH(ds, variable='zFactorFinal', radar_frequency='Ku')[source][source]#
Retrieve the height at which the maximum radar reflectivity is observed.
Also called: Composite REFlectivity Height
- gpm.retrievals.retrieval_2a_radar.retrieve_SHI(ds, variable='zFactorFinal', radar_frequency='Ku', lower_z_threshold=40, upper_z_threshold=50)[source][source]#
Retrieve the Severe Hail Index (SHI).
SHI is used to compute the Probability of Severe Hail (POSH) and Maximum Estimated Size of Hail (MESH). SHI applies a thermally weighted vertical integration of reflectivity from the melting level to the top of the storm, neglecting any reflectivity less than 40 dBZ, thereby attempting to capture only the ice content of a storm.
Reference: Witt et al., 1998
- Parameters:
ds (xarray.Dataset) – GPM L2 RADAR Dataset.
variable (str, optional) – Reflectivity field. The default is “zFactorFinal”.
radar_frequency (str, optional) – Radar frequency. The default is “Ku”.
lower_z_threshold (int or float, optional) – Lower reflectivity threshold. The default is 40 dBZ.
upper_z_threshold (int or float, optional) – Upper reflectivity threshold. The default is 50 dBZ.
- Returns:
da_shi – Severe Hail Index (SHI)
- Return type:
- gpm.retrievals.retrieval_2a_radar.retrieve_VIL(ds, variable='zFactorFinal', radar_frequency='Ku')[source][source]#
Compute Vertically Integrated Liquid indicator.
Represents the total amount of rain that would fall if all the liquid water in a column inside a rain cloud (usually a thunderstorm) would be brought to the surface.
- Reference:
Greene, D.R., and R.A. Clark, 1972: Vertically integrated liquid water - A new analysis tool. Mon. Wea. Rev., 100, 548-552. Amburn and Wolf (1997)
- gpm.retrievals.retrieval_2a_radar.retrieve_VILD(ds, variable='zFactorFinal', radar_frequency='Ku', threshold=18, use_echo_top=False)[source][source]#
Compute Vertically Integrated Liquid Density.
VIL Density = VIL/Echo Top Height
By default, the Echo Top Height (or Echo Depth) is computed for 18 dBZ. More info at https://www.weather.gov/lmk/vil_density
- gpm.retrievals.retrieval_2a_radar.retrieve_bright_band_ratio(ds, return_bb_mask=True)[source][source]#
Returns the Bright Band (BB) Ratio.
A BB ratio of < 0 indicates that a bin is located below the melting layer (ML). A BB ratio of > 0 indicates that a bin is located above the ML. A BB ratio with values in between 0 and 1 indicates that the radar is inside the ML.
This function has been ported as it is from wradlib.
- Parameters:
ds (xarray.Dataset) –
- Returns:
BB Ratio (3D) and BB (2D) mask.
- Return type:
- gpm.retrievals.retrieval_2a_radar.retrieve_c_band_tan(ds, reflectivity='zFactorFinal', bb_ratio=None, precip_type=None)[source][source]#
Retrieve C-band reflectivity from Ku-band reflectivity.
- gpm.retrievals.retrieval_2a_radar.retrieve_dfrFinalNearSurface(ds)[source][source]#
Retrieve final DFR near the surface.
- gpm.retrievals.retrieval_2a_radar.retrieve_flagHydroClass(ds, reflectivity='zFactorFinal', bb_ratio=None, precip_type=None)[source][source]#
Classify reflectivity profile into rain, snow, hail and melting layer.
- gpm.retrievals.retrieval_2a_radar.retrieve_flagPrecipitationType(xr_obj, method='major_rain_type')[source][source]#
Retrieve major rain type from the 2A-<RADAR> typePrecip variable.
- gpm.retrievals.retrieval_2a_radar.retrieve_gate_resolution(ds, beam_width, range_distance=None, scan_angle=None)[source][source]#
Retrieve the horizontal and vertical ‘resolution’ of each radar gates.
The gate horizontal resolution is computed by projecting the radius of the radar gate onto the horizontal plane, averaging the projected radii in the along-track and cross-track directions.
The gate vertical resolution is computed by projecting the radar gate range resolution onto the vertical plane.
- Parameters:
ds (xarray.Dataset) – GPM radar dataset.
beam_width (float) – The cross-track aperture angle of the radar beam [degree]. The accurate cross-track aperture angle is provided by ‘crossTrackBeamWidth’ in the L1B product.
range_distance (xarray.DataArray) – DataArray with range distance from each satellite at each radar gate. If not specified, is computed using a rough approximation.
scan_angle (xarray.DataArray) – Used to estimate range_distance if not specified. Cross-track scan angle in degree. If not specified, assumes
np.abs(np.linspace(-17.04, 17.04, 49))for Ku.
- Returns:
Tuple with (h_res, v_res).
- Return type:
- gpm.retrievals.retrieval_2a_radar.retrieve_gate_volume(ds, beam_width=None, range_distance=None, scan_angle=None)[source][source]#
Calculates the sampling volume of the radar beam.
We assume a cone frustum which has the volume \(V=(\\pi/3) \\cdot h \\cdot (R^2 + R \\cdot r + r^2)\). R and r are the radii of the two frustum surface circles. Assuming that the pulse width is small compared to the range, we get \(R=r= \\tan ( 0.5 \\cdot \\theta \\cdot \\pi/180 ) \\cdot range\), with theta being the aperture angle (beam width). Thus, the radar gate volume simply becomes the volume of a cylinder with \(V=\\pi \\cdot h \\cdot range^2 \\cdot \\tan(0.5 \\cdot \\theta \\cdot \\pi/180)^2\)
- Parameters:
ds (xarray.Dataset) – GPM radar dataset.
beam_width (float) – The cross-track aperture angle of the radar beam [degree]. The accurate cross-track aperture angle is provided by ‘crossTrackBeamWidth’ in the L1B product.
range_distance (xarray.DataArray) – DataArray with range distance from each satellite at each radar gate. If not specified, is computed using a rough approximation.
scan_angle (xarray.DataArray) – Used to estimate range_distance if not specified. Cross-track scan angle in degree. If not specified, assumes
np.abs(np.linspace(-17.04, 17.04, 49))for Ku.
- Returns:
Volume of radar gates in cubic meters.
- Return type:
- gpm.retrievals.retrieval_2a_radar.retrieve_heightClutterFreeBottom(ds)[source][source]#
Retrieve clutter height.
- gpm.retrievals.retrieval_2a_radar.retrieve_heightRealSurfaceKa(ds)[source][source]#
Retrieve height of real surface at Ka band.
- gpm.retrievals.retrieval_2a_radar.retrieve_heightRealSurfaceKu(ds)[source][source]#
Retrieve height of real surface at Ku band.
- gpm.retrievals.retrieval_2a_radar.retrieve_range_distance_from_ellipsoid(ds)[source][source]#
Retrieve distance from the ellipsoid along the radar beam.
Accurate range resolution is provided by ‘rangeBinSize’ in the L1B product. Requires: ellipsoidBinOffset, height, localZenithAngle.
- gpm.retrievals.retrieval_2a_radar.retrieve_range_distance_from_satellite(ds, scan_angle=None, earth_radius=6371000)[source][source]#
Retrieve range distance in meters (at bin center) from the satellite.
This is a rough approximation took from wradlib dist_from_orbit function.
- Parameters:
ds (xarray.Dataset) – GPM radar dataset.
scan_angle (xarray.DataArray, optional) – Cross-track scan angle in degree. If not specified, assumes
np.abs(np.linspace(-17.04, 17.04, 49))for Ku.earth_radius (float, optional) – Earth radius.
- Returns:
da – Range distances from the satellite.
- Return type:
- gpm.retrievals.retrieval_2a_radar.retrieve_range_resolution(ds)[source][source]#
Retrieve range resolution.
- gpm.retrievals.retrieval_2a_radar.retrieve_s_band_cao2013(ds, reflectivity='zFactorFinal', bb_ratio=None, precip_type=None)[source][source]#
Retrieve S-band reflectivity from Ku-band reflectivity.
Cao et al., 2013 provides coefficients to compute DFR (S-Ku) using the following polynomial:
\[\text{DFR (S-Ku)} = a_0 + a_1 Z(\text{Ku})^1 + a_2 Z(\text{Ku})^2 + a_3 Z(\text{Ku})^3 + a_4 Z(\text{Ku})^4\]S-band reflectivity is derived by summing Ku-reflectivity to DFR (S-Ku).
The Bright Band Ratio and the Precipitation Type are used to discriminate between rain, snow, hail, mixed phase gates, and use the adequate coefficients.
The method : - uses snow coefficients if precipitation type is assumed to be stratiform (precip_type=1) - uses hail coefficients if precipitation type is assumed to be convective (precip_type=2) - assumes no mixed-phase (either snow or hail) above the melting layer - assumes no mixed-phase (either rain or full hail) below the melting layer
Please ensure precip_type to have values 0, 1 or 2. precip type = 0 means no rain.
- Parameters:
ds (xarray.Dataset) – GPM Radar dataset.
reflectivity (xarray.DataArray or str) – 3D reflectivity array or dataset variable name. The default is “zFactorFinal”.
bb_ratio (xarray.DataArray, optional) – Bright Band Ratio. If not specified,
gpm.retrieve("bright_band_ratio")is called.precip_type (xarray.DataArray, optional) – DataArray indicating the precipitation class. Please ensure
precip_typeto have values 0, 1 or 2.precip type = 0means no rain.
- Returns:
S band reflectivity.
- Return type:
gpm.retrievals.routines module#
This module contains functions to search the GPM-API community-based retrievals.
- gpm.retrievals.routines.available_retrievals(ds)[source][source]#
Return the available GPM-API retrievals of the GPM product.
Module contents#
This directory contains the GPM-API community-based retrievals encodings.
- gpm.retrievals.open_dataset_1b_ka_fs(start_time, end_time, variables=None, groups=None, product_type='RS', chunks={}, verbose=False, parallel=False, l2_format=True, **kwargs)[source][source]#
Open 1B-Ka dataset in FS scan_mode format in either L1B or L2 format.
It expects start_time after the GPM DPR scan pattern change occurred the 8 May 2018. (Over)Resample HS on MS (using LUT/range distance). The L2 FS format has 176 bins.
Notes
1B-Ka HS has a zig-zag pattern after scan change in 2018 !
1B-Ka HS has 1 scan more than 1B-Ka MS (when queried by time)
1B-Ka HS have range resolution of 250 m (130 bins)
1B-Ka MS have range resolution of 125 m (260 bins)
2A-Ka HS have range resolution of 125 m (88 bins)
2A-Ka MS have range resolution of 125 m (176 bins)