gpm.gv package

gpm.gv package#

Subpackages#

Submodules#

gpm.gv.plots module#

This module contains plotting utility for SR/GR validation.

gpm.gv.plots.calibration_summary(df, gr_z_column, sr_z_column, hue_column, gr_range=None, sr_range=None, marker='+', cbar_kwargs=None, bin_width=2, **plot_kwargs)[source][source]#

Creates a summary plot for comparison between GR and SR reflectivity data.

The function draw a scatter plot and overlaid histograms of GR and SR reflectivity values.

Parameters:

  • df (pandas.DataFrame, geopandas.GeoDataFrame) – The dataframe containing the reflectivity data.

  • gr_z_column (str) – The column name for the GR (ground radar) reflectivity data.

  • sr_z_column (str) – The column name for the SR (spaceborne radar) reflectivity data.

  • hue_column (str) – The column name used for color mapping in the scatter plot.

  • gr_range (list, optional) – The limits for the x-axis in the scatter plot as [min, max]. If None, limits are determined from data.

  • sr_range (list, optional) – The limits for the y-axis in the scatter plot as [min, max]. If None, limits are determined from data.

  • marker (str, optional) – The marker style for the scatter plot. The default is "+".

  • cbar_kwargs (dict, optional) – Additional keyword arguments for the colorbar.

  • bin_width (float, optional) – The width of the histogram bins. The default is 2 dBZ.

  • **plot_kwargs (dict) – Additional keyword arguments passed to the scatter plot.

Returns:

The figure object containing the calibration summary plots.

Return type:

matplotlib.figure.Figure

gpm.gv.plots.compare_maps(gdf, sr_column, gr_column, sr_label=None, gr_label=None, sr_title=None, gr_title=None, cmap='Spectral_r', vmin=None, vmax=None, grid_color='grey', grid_linewidth=0.25, unified_color_scale=True, shared_colorbar=False, subplot_kwargs=None, fig_kwargs=None, cbar_kwargs=None, **plot_kwargs)[source][source]#

Compare and plot side-by-side maps of SR and GR data from a GeoDataFrame.

Parameters:

  • gdf (geopandas.GeoDataFrame) – The GeoDataFrame containing the matched SR/GR data.

  • sr_column (str) – The column name for SR data.

  • gr_column (str) – The column name for GR data.

  • sr_label (str, optional) – Label for the SR sensor colorbar.

  • gr_label (str, optional) – Label for the GR sensor colorbar.

  • cmap (str, optional) – Colormap to use for both plots. The default is “Spectral_r”.

  • vmin (float, optional) – Minimum value for color scale. Defaults to the minimum value across SR and GR data if unified_color_scale is True.

  • vmax (float, optional) – Maximum value for color scale. Defaults to the maximum value across SR and GR data if unified_color_scale is True.

  • unified_color_scale (str, optional) – If True and vmin or vmax are not specified, it automatically set a common vmin/vmax value. The default is True.

  • shared_colorbar (bool, optional) – If True, a single colorbar is shared across both plots.

  • grid_color (str, optional) – Color of the grid lines. The default is “grey”.

  • grid_linewidth (float, optional) – Linewidth of the grid lines. The default is 0.25.

  • cbar_kwargs (dict, optional) – Keyword arguments for customizing the colorbar passed to matplotlib.pyplot.colorbar.

  • fig_kwargs (dict, optional) – Keyword arguments for customizing the figure passed to matplotlib.pyplot.subplots. The default is None and figsize is set to (14,7).

  • subplot_kwargs (dict, optional) – Keyword arguments for matplotlib.pyplot.subplots. Can include a projection key to set a Cartopy CRS.

Returns:

Displays SR and GR fields side-by-side.

Return type:

None

gpm.gv.plots.plot_gdf_map(gdf, column, extent_xy=None, title=None, grid_color='grey', grid_linewidth=0.25, add_colorbar=True, cbar_kwargs=None, **plot_kwargs)[source][source]#
gpm.gv.plots.reflectivity_distribution(df, gr_z_column, sr_z_column, ax=None, bin_width=2)[source][source]#

Plots overlaid histograms of GR and SR reflectivity distributions.

Parameters:

  • df (pandas.DataFrame, geopandas.GeoDataFrame) – The dataframe containing the reflectivity data.

  • gr_z_column (str) – The column name for the GR (ground radar) reflectivity data.

  • sr_z_column (str) – The column name for the SR (spaceborne radar) reflectivity data.

  • ax (matplotlib.axes.Axes, optional) – The axes to plot on. If None, a new figure and axis are created.

  • bin_width (float, optional) – The width of the histogram bins. The default is 2 dBZ.

Returns:

The histogram plot objects for GR and SR.

Return type:

tuple

gpm.gv.plots.reflectivity_scatterplot(df, gr_z_column, sr_z_column, hue_column, ax=None, gr_range=None, sr_range=None, add_colorbar=True, marker='+', title='GR / SR Offset', cbar_kwargs=None, **plot_kwargs)[source][source]#

Plots a scatterplot comparing GR and SR reflectivity columns.

Parameters:

  • df (pandas.DataFrame, geopandas.GeoDataFrame) – The dataframe containing the reflectivity data.

  • gr_z_column (str) – The column name for the GR (ground radar) reflectivity data on the x-axis.

  • sr_z_column (str) – The column name for the SR (spaceborne radar) reflectivity data on the y-axis.

  • hue_column (str) – The column name used for color mapping in the scatter plot.

  • ax (matplotlib.axes.Axes, optional) – The axes to plot on. If None, a new figure and axis are created.

  • gr_range (list, optional) – The limits for the x-axis as [min, max]. If None, limits are determined from data.

  • sr_range (list, optional) – The limits for the y-axis as [min, max]. If None, limits are determined from data.

  • add_colorbar (bool, optional) – If True, adds a colorbar to the plot. The default is True.

  • marker (str, optional) – The marker style for the scatter plot. The default is "+".

  • title (str, optional) – The title of the scatter plot. The default is “GR / SR Offset”.

  • cbar_kwargs (dict, optional) – Additional keyword arguments for the colorbar.

  • **plot_kwargs (dict) – Additional keyword arguments passed to ax.scatter.

Returns:

The scatter plot object.

Return type:

matplotlib.collections.PathCollection

gpm.gv.plots.reflectivity_scatterplots(df, gr_z_column, sr_z_column, hue_columns, ncols=2, fig_kwargs=None, gr_range=None, sr_range=None, marker='+', cbar_kwargs=None, **plot_kwargs)[source][source]#

Plots multiple scatter plots comparing GR and SR reflectivity for each specified hue variable.

Parameters:

  • df (pandas.DataFrame) – The dataframe containing the reflectivity data.

  • gr_z_column (str) – The column name for the GR (ground radar) reflectivity data on the x-axis.

  • sr_z_column (str) – The column name for the SR (spaceborne radar) reflectivity data on the y-axis.

  • hue_variables (list of str) – A list of column names to be used as hue variables for individual scatter plots.

  • ncols (int, optional) – Number of columns in the subplot grid. The default is 2.

  • gr_range (list, optional) – The limits for the x-axis as [min, max]. If None, limits are determined from data.

  • sr_range (list, optional) – The limits for the y-axis as [min, max]. If None, limits are determined from data.

  • marker (str, optional) – The marker style for the scatter plot. The default is “+”.

  • fig_kwargs (dict, optional) – Keyword arguments for customizing the figure passed to matplotlib.pyplot.subplots. If figsize is not specified, defaults to (ncols * 6, nrows * 5).

  • cbar_kwargs (dict, optional) – Additional keyword arguments common to all colorbars.

  • **plot_kwargs (dict) – Additional keyword arguments common to all scatter plot.

Returns:

The figure object containing all the scatter plots.

Return type:

matplotlib.figure.Figure

gpm.gv.routines module#

This module contains the routine for SR/GR validation.

gpm.gv.routines.add_radar_info(ax, ds_gr, radar_size)[source][source]#
gpm.gv.routines.antenna_to_cartesian(r, azimuth, elevation, crs, effective_radius_fraction=None, site_altitude=0)[source][source]#

Return Cartesian coordinates from antenna coordinates.

Parameters:

  • r (array-like) – Distances to the center of the radar gates (bins) in meters.

  • azimuth (array-like) – Azimuth angle of the radar in degrees.

  • elevation (array-like) – Elevation angle of the radar in degrees.

  • crs (pyproj.crs.CRS) – Azimuthal equidistant projection CRS centered on the ground radar site. The latitude of the projection center is used to determine the Earth radius.

  • effective_radius_fraction (float) – Fraction of earth to use for the effective radius. The default is 4/3.

  • site_altitude (float) – Altitude above sea level of the radar site (in meters).

Returns:

x, y, z – Cartesian coordinates in meters from the radar.

Return type:

array-like

Notes

The calculation for Cartesian coordinate is adapted from equations 2.28(b) and 2.28(c) of Doviak and Zrnić [1] assuming a standard atmosphere (4/3 Earth’s radius model).

\\begin{gather*} z = \\sqrt{r^2+R^2+2*r*R*sin(\\theta_e)} - R \\\\ s = R * arcsin(\\frac{r*cos(\\theta_e)}{R+z}) \\\\ x = s * sin(\\theta_a) \\\\ y = s * cos(\\theta_a) \\end{gather*}

Where r is the distance from the radar to the center of the gate, \(\\theta_a\) is the azimuth angle, \(\\theta_e\) is the elevation angle, s is the arc length, and R is the effective radius of the earth, taken to be 4/3 the mean radius of earth (6371 km).

References

gpm.gv.routines.convert_s_to_ku_band(ds_gr, bright_band_height, z_variable='DBZH')[source][source]#

Convert S-band GR reflectivities to Ku-band.

Does not account for mixed-phase and hail.

gpm.gv.routines.get_crs_center_latitude(crs)[source][source]#

Retrieve the center latitude of a pyproj CRS.

Parameters:

crs (pyproj.crs.CRS) – The Coordinate Reference System.

Returns:

center_latitude – The center latitude of the CRS.

Return type:

float

gpm.gv.routines.get_gr_crs(latitude, longitude, datum='WGS84')[source][source]#
gpm.gv.routines.plot_quicklook(ds_gr, gdf, sr_z_column, gr_z_column, z_variable_gr='DBZH', ds_sr=None)[source][source]#
gpm.gv.routines.retrieve_ds_sr(start_time, end_time, extent_gr, download_sr=False)[source][source]#
gpm.gv.routines.retrieve_gates_geographic_coordinates(ds)[source][source]#

Retrieve the radar gates (lat, lon, height) coordinates.

The longitude and latitude coordinates provided in the GPM products correspond to the location where the radar gate centroid cross the ellipsoid.

This routine returns the coordinates array at each radar gate, correcting for the satellite parallax.

It does not account for the curvature of the Earth in the calculations.

Requires: scLon, scLat, localZenithAngle, height.

Parameters:

ds (xarray.Dataset) – GPM radar dataset.

Returns:

Tuple with the (lon, lat, height) coordinates.

Return type:

tuple

gpm.gv.routines.retrieve_gates_projection_coordinates(ds, dst_crs)[source][source]#

Retrieve the radar gates (x,y,z) coordinates in a custom CRS.

The longitude and latitude coordinates provided in the GPM products correspond to the location where the radar gate centroid cross the ellipsoid.

This routine returns the coordinates array at each radar gate, correcting for the satellite parallax.

It does not account for the curvature of the Earth in the calculations.

Parameters:
Returns:

Tuple with the (x,y,z) coordinates in specified target CRS.

Return type:

tuple

gpm.gv.routines.xyz_to_antenna_coordinates(x, y, z, site_altitude, crs, effective_radius_fraction=None)[source][source]#

Returns the ground radar spherical representation (r, theta, phi).

Parameters:

  • x (array-like) – Cartesian x coordinates.

  • y (array-like) – Cartesian y coordinates.

  • z (array-like) – Cartesian z coordinates.

  • site_altitude (float) – Radar site elevation (in meters, asl).

  • crs (pyproj.crs.CRS) – Azimuthal equidistant projection CRS centered on the ground radar site. The latitude of the projection center is used to determine the Earth radius.

  • effective_radius_fraction (float) – Adjustment factor to account for the refractivity gradient that affects radar beam propagation. In principle this is wavelength- dependent. The default of 4/3 is a good approximation for most weather radar wavelengths.

Returns:

  • r (array-like) – Array containing the radial distances.

  • azimuth (array-like) – Array containing the azimuthal angles.

  • elevation (array-like) – Array containing the elevation angles.

Module contents#

This directory contains utility for SR/GR validation.

gpm.gv.calibration_summary(df, gr_z_column, sr_z_column, hue_column, gr_range=None, sr_range=None, marker='+', cbar_kwargs=None, bin_width=2, **plot_kwargs)[source][source]#

Creates a summary plot for comparison between GR and SR reflectivity data.

The function draw a scatter plot and overlaid histograms of GR and SR reflectivity values.

Parameters:

  • df (pandas.DataFrame, geopandas.GeoDataFrame) – The dataframe containing the reflectivity data.

  • gr_z_column (str) – The column name for the GR (ground radar) reflectivity data.

  • sr_z_column (str) – The column name for the SR (spaceborne radar) reflectivity data.

  • hue_column (str) – The column name used for color mapping in the scatter plot.

  • gr_range (list, optional) – The limits for the x-axis in the scatter plot as [min, max]. If None, limits are determined from data.

  • sr_range (list, optional) – The limits for the y-axis in the scatter plot as [min, max]. If None, limits are determined from data.

  • marker (str, optional) – The marker style for the scatter plot. The default is "+".

  • cbar_kwargs (dict, optional) – Additional keyword arguments for the colorbar.

  • bin_width (float, optional) – The width of the histogram bins. The default is 2 dBZ.

  • **plot_kwargs (dict) – Additional keyword arguments passed to the scatter plot.

Returns:

The figure object containing the calibration summary plots.

Return type:

matplotlib.figure.Figure

gpm.gv.compare_maps(gdf, sr_column, gr_column, sr_label=None, gr_label=None, sr_title=None, gr_title=None, cmap='Spectral_r', vmin=None, vmax=None, grid_color='grey', grid_linewidth=0.25, unified_color_scale=True, shared_colorbar=False, subplot_kwargs=None, fig_kwargs=None, cbar_kwargs=None, **plot_kwargs)[source][source]#

Compare and plot side-by-side maps of SR and GR data from a GeoDataFrame.

Parameters:

  • gdf (geopandas.GeoDataFrame) – The GeoDataFrame containing the matched SR/GR data.

  • sr_column (str) – The column name for SR data.

  • gr_column (str) – The column name for GR data.

  • sr_label (str, optional) – Label for the SR sensor colorbar.

  • gr_label (str, optional) – Label for the GR sensor colorbar.

  • cmap (str, optional) – Colormap to use for both plots. The default is “Spectral_r”.

  • vmin (float, optional) – Minimum value for color scale. Defaults to the minimum value across SR and GR data if unified_color_scale is True.

  • vmax (float, optional) – Maximum value for color scale. Defaults to the maximum value across SR and GR data if unified_color_scale is True.

  • unified_color_scale (str, optional) – If True and vmin or vmax are not specified, it automatically set a common vmin/vmax value. The default is True.

  • shared_colorbar (bool, optional) – If True, a single colorbar is shared across both plots.

  • grid_color (str, optional) – Color of the grid lines. The default is “grey”.

  • grid_linewidth (float, optional) – Linewidth of the grid lines. The default is 0.25.

  • cbar_kwargs (dict, optional) – Keyword arguments for customizing the colorbar passed to matplotlib.pyplot.colorbar.

  • fig_kwargs (dict, optional) – Keyword arguments for customizing the figure passed to matplotlib.pyplot.subplots. The default is None and figsize is set to (14,7).

  • subplot_kwargs (dict, optional) – Keyword arguments for matplotlib.pyplot.subplots. Can include a projection key to set a Cartopy CRS.

Returns:

Displays SR and GR fields side-by-side.

Return type:

None

gpm.gv.reflectivity_distribution(df, gr_z_column, sr_z_column, ax=None, bin_width=2)[source][source]#

Plots overlaid histograms of GR and SR reflectivity distributions.

Parameters:

  • df (pandas.DataFrame, geopandas.GeoDataFrame) – The dataframe containing the reflectivity data.

  • gr_z_column (str) – The column name for the GR (ground radar) reflectivity data.

  • sr_z_column (str) – The column name for the SR (spaceborne radar) reflectivity data.

  • ax (matplotlib.axes.Axes, optional) – The axes to plot on. If None, a new figure and axis are created.

  • bin_width (float, optional) – The width of the histogram bins. The default is 2 dBZ.

Returns:

The histogram plot objects for GR and SR.

Return type:

tuple

gpm.gv.reflectivity_scatterplot(df, gr_z_column, sr_z_column, hue_column, ax=None, gr_range=None, sr_range=None, add_colorbar=True, marker='+', title='GR / SR Offset', cbar_kwargs=None, **plot_kwargs)[source][source]#

Plots a scatterplot comparing GR and SR reflectivity columns.

Parameters:

  • df (pandas.DataFrame, geopandas.GeoDataFrame) – The dataframe containing the reflectivity data.

  • gr_z_column (str) – The column name for the GR (ground radar) reflectivity data on the x-axis.

  • sr_z_column (str) – The column name for the SR (spaceborne radar) reflectivity data on the y-axis.

  • hue_column (str) – The column name used for color mapping in the scatter plot.

  • ax (matplotlib.axes.Axes, optional) – The axes to plot on. If None, a new figure and axis are created.

  • gr_range (list, optional) – The limits for the x-axis as [min, max]. If None, limits are determined from data.

  • sr_range (list, optional) – The limits for the y-axis as [min, max]. If None, limits are determined from data.

  • add_colorbar (bool, optional) – If True, adds a colorbar to the plot. The default is True.

  • marker (str, optional) – The marker style for the scatter plot. The default is "+".

  • title (str, optional) – The title of the scatter plot. The default is “GR / SR Offset”.

  • cbar_kwargs (dict, optional) – Additional keyword arguments for the colorbar.

  • **plot_kwargs (dict) – Additional keyword arguments passed to ax.scatter.

Returns:

The scatter plot object.

Return type:

matplotlib.collections.PathCollection

gpm.gv.reflectivity_scatterplots(df, gr_z_column, sr_z_column, hue_columns, ncols=2, fig_kwargs=None, gr_range=None, sr_range=None, marker='+', cbar_kwargs=None, **plot_kwargs)[source][source]#

Plots multiple scatter plots comparing GR and SR reflectivity for each specified hue variable.

Parameters:

  • df (pandas.DataFrame) – The dataframe containing the reflectivity data.

  • gr_z_column (str) – The column name for the GR (ground radar) reflectivity data on the x-axis.

  • sr_z_column (str) – The column name for the SR (spaceborne radar) reflectivity data on the y-axis.

  • hue_variables (list of str) – A list of column names to be used as hue variables for individual scatter plots.

  • ncols (int, optional) – Number of columns in the subplot grid. The default is 2.

  • gr_range (list, optional) – The limits for the x-axis as [min, max]. If None, limits are determined from data.

  • sr_range (list, optional) – The limits for the y-axis as [min, max]. If None, limits are determined from data.

  • marker (str, optional) – The marker style for the scatter plot. The default is “+”.

  • fig_kwargs (dict, optional) – Keyword arguments for customizing the figure passed to matplotlib.pyplot.subplots. If figsize is not specified, defaults to (ncols * 6, nrows * 5).

  • cbar_kwargs (dict, optional) – Additional keyword arguments common to all colorbars.

  • **plot_kwargs (dict) – Additional keyword arguments common to all scatter plot.

Returns:

The figure object containing all the scatter plots.

Return type:

matplotlib.figure.Figure

gpm.gv.retrieve_ds_sr(start_time, end_time, extent_gr, download_sr=False)[source][source]#
gpm.gv.volume_matching(*args, **kwargs)[source]#