Vertical Profile of Reflectivity (VPR)#

Precipitation is 3-dimensional in space. The vertical distribution of precipitation (and thus reflectivity) is typically non-uniform. As the height of the radar beam increases with the distance from the radar location (beam elevation, earth curvature), one sweep samples from different heights. The effects of the non-uniform VPR and the different sampling heights need to be accounted for if we are interested in the precipitation near the ground or in defined heights. This module is intended to provide a set of tools to account for these effects.

The first step will normally be to reference the polar volume data in a 3-dimensional Cartesian coordinate system. The three-dimensional Cartesian coordinates of the original polar volume data can be computed using wradlib.vpr.volcoords_from_polar.

Then, we can create regular 3-D grids in order to analyse the vertical profile of reflectivity or rainfall intensity. For some applications you might want to create so-called Constant Altitude Plan Position Indicators (CAPPI) in order to make radar observations at different distances from the radar more comparable. Basically, a CAPPI is simply one slice out of a 3-D volume grid. Analoguous, we will refer to the elements in a three-dimensional Cartesian grid as voxels. In wradlib, you can create CAPPIS (CAPPI) and Pseudo CAPPIs (PseudoCAPPI) for different altitudes at once.

volcoords_from_polar

Create Cartesian coordinates for regular polar volumes

make_3d_grid

Generate Cartesian coordinates for a regular 3-D grid based on radar specs.

norm_vpr_stats

Returns the average normalised vertical profile of a volume or any other desired statistics

CartesianVolume

Create 3-D regular volume grid in Cartesian coordinates from polar data with multiple elevation angles

CAPPI

Create a Constant Altitude Plan Position Indicator (CAPPI)

PseudoCAPPI

Create a Pseudo-CAPPI Constant Altitude Plan Position Indicator (CAPPI)

out_of_range

Masks the region outside the radar range

blindspots

Masks blind regions of the radar, marked on a 3-D grid

wradlib.vpr.volcoords_from_polar(site, elevs, azimuths, ranges, *, crs=None)[source]#

Create Cartesian coordinates for regular polar volumes

Parameters
  • site (tuple) – sequence of three floats indicating the radar position (longitude in decimal degrees, latitude in decimal degrees, height a.s.l. in meters)

  • elevs (sequence) – sequence of elevation angles

  • azimuths (sequence) – sequence of azimuth angles

  • ranges (sequence) – sequence of ranges

  • crs (osgeo.osr.SpatialReference) – GDAL OSR Spatial Reference Object describing projection

Returns

output (numpy.ndarray) – Array of shape (num volume bins, 3)

Examples

See Recipe #2: Reading and visualizing an ODIM_H5 polar volume.

wradlib.vpr.make_3d_grid(site, crs, maxrange, maxalt, horiz_res, vert_res, *, minalt=0.0)[source]#

Generate Cartesian coordinates for a regular 3-D grid based on radar specs.

Parameters
  • site (tuple) – Radar location coordinates in lon, lat

  • crs (osgeo.osr.SpatialReference) – GDAL OSR SRS describing projection

  • maxrange (float) – maximum radar range (same unit as CRS defined by crs, typically meters)

  • maxalt (float) – maximum altitude to which the 3-d grid should extend (meters)

  • horiz_res (float) – horizontal resolution of the 3-d grid (same unit as CRS defined by crs, typically meters)

  • vert_res (float) – vertical resolution of the 3-d grid (meters)

  • minalt (float, optional) – minimum altitude to which the 3-d grid should extend (meters), defaults to 0.

Returns

output (numpy.ndarray, tuple) – float array of shape (num grid points, 3), a tuple of 3 representing the grid shape

wradlib.vpr.norm_vpr_stats(volume, reference_layer, *, stat=None, **kwargs)[source]#

Returns the average normalised vertical profile of a volume or any other desired statistics

Given a Cartesian 3-d volume and an arbitrary reference layer index, the function normalises all vertical profiles represented by the volume and computes a static of all profiles (e.g. an average vertical profile using the default stat).

Parameters
  • volume (numpy.ndarray or) – numpy.ma.MaskedArray Cartesian 3-d grid with shape (num vertical layers, num x intervals, num y intervals)

  • reference_layer (int) – This index defines the vertical layers of volume that is used to normalise all vertical profiles

  • stat (callable) – typically a numpy statistics function (defaults to numpy.mean)

  • kwargs (dict) – further keyword arguments taken by stat

Returns

output (numpy.ndarray or numpy.ma.MaskedArray) – Array of shape (num vertical layers, ) which provides the statistic from stat applied over all normalised vertical profiles (e.g. the mean normalised vertical profile if numpy.mean is used)

class wradlib.vpr.CartesianVolume(polcoords, gridcoords, *, maxrange=None, minelev=None, maxelev=None, site=None, ipclass=<class 'wradlib.ipol.Idw'>, **ipargs)[source]#

Bases: object

Create 3-D regular volume grid in Cartesian coordinates from polar data with multiple elevation angles

Parameters
  • polcoords (numpy.ndarray) – of shape (num bins, 3)

  • gridcoords (numpy.ndarray) – of shape (num voxels, 3)

  • maxrange (float) – The maximum radar range (must be the same for each elevation angle)

  • minelev (float) – The minimum elevation angle of the volume (degree)

  • maxelev (float) – The maximum elevation angle of the volume (degree)

  • site (sequence) – the lon / lat / alt coordinates of the radar location and its altitude a.m.s.l. (in meters)

  • ipclass (wradlib.ipol.IpolBase) – an interpolation class from wradlib.ipol

  • ipargs (dict) – keyword arguments corresponding to ipclass

Returns

output (numpy.ndarray) – float 1-d ndarray of the same length as gridcoords (num voxels, )

Examples

See Recipe #2: Reading and visualizing an ODIM_H5 polar volume.

class wradlib.vpr.CAPPI(polcoords, gridcoords, *, maxrange=None, minelev=None, maxelev=None, site=None, ipclass=<class 'wradlib.ipol.Idw'>, **ipargs)[source]#

Bases: CartesianVolume

Create a Constant Altitude Plan Position Indicator (CAPPI)

A CAPPI gives the value of a target variable (typically reflectivity in dBZ, but here also other variables such as e.g. rainfall intensity) in a defined altitude.

In order to create a CAPPI, you first have to create an instance of this class. Calling this instance with the actual polar volume data will return the CAPPI grid.

Parameters
  • polcoords (numpy.ndarray) – coordinate array of shape (num bins, 3) Represents the 3-D coordinates of the original radar bins

  • gridcoords (numpy.ndarray) – coordinate array of shape (num voxels, 3) Represents the 3-D coordinates of the Cartesian grid

  • maxrange (float) – The maximum radar range (must be the same for each elevation angle)

  • ipclass (wradlib.ipol.IpolBase) – an interpolation class from wradlib.ipol

  • ipargs (dict) – keyword arguments corresponding to ipclass

Returns

output (numpy.ndarray) – float 1-d ndarray of the same length as gridcoords (num voxels, )

Examples

See Recipe #2: Reading and visualizing an ODIM_H5 polar volume.

Here’s an example how a set of CAPPIs can be created from synthetic polar volume data:

>>> import wradlib
>>> import numpy as np
>>> from osgeo import osr
>>> import matplotlib.pyplot as plt
>>> plt.interactive(True)
>>> # define elevation and azimuth angles, ranges, radar site coordinates,
>>> # projection
>>> elevs  = np.array([0.5,1.5,2.4,3.4,4.3,5.3,6.2,7.5,8.7,10,12,14,16.7,19.5])
>>> azims  = np.arange(0., 360., 1.)
>>> ranges = np.arange(0., 120000., 1000.)
>>> site = (120.255547,14.924218,500.)
>>> crs = osr.SpatialReference()
>>> _ = crs.ImportFromEPSG(32651)
>>> # create Cartesian coordinates corresponding the location of the
>>> # polar volume bins
>>> polxyz  = wradlib.vpr.volcoords_from_polar(site, elevs,
...                                            azims, ranges, crs=crs)  # noqa
>>> poldata = wradlib.vpr.synthetic_polar_volume(polxyz)
>>> # this is the shape of our polar volume
>>> polshape = (len(elevs),len(azims),len(ranges))
>>> # now we define the coordinates for the 3-D grid (the CAPPI layers)
>>> x = np.linspace(polxyz[:,0].min(), polxyz[:,0].max(), 120)
>>> y = np.linspace(polxyz[:,1].min(), polxyz[:,1].max(), 120)
>>> z = np.arange(500.,10500.,500.)
>>> xyz = wradlib.util.gridaspoints(z, y, x)
>>> gridshape = (len(z), len(y), len(x))
>>> # create an instance of the CAPPI class and
>>> # use it to create a series of CAPPIs
>>> gridder = wradlib.vpr.CAPPI(polxyz, xyz, maxrange=ranges.max(),  # noqa
...                             minelev=elevs.min(), maxelev=elevs.max(),
...                             ipclass=wradlib.ipol.Idw)
>>> gridded = np.ma.masked_invalid( gridder(poldata) ).reshape(gridshape)
>>>
>>> # plot results
>>> levels = np.linspace(0,100,25)
>>> wradlib.vis.plot_max_plan_and_vert(x, y, z, gridded, levels=levels)
>>> plt.show()
class wradlib.vpr.PseudoCAPPI(polcoords, gridcoords, *, maxrange=None, minelev=None, maxelev=None, site=None, ipclass=<class 'wradlib.ipol.Idw'>, **ipargs)[source]#

Bases: CartesianVolume

Create a Pseudo-CAPPI Constant Altitude Plan Position Indicator (CAPPI)

The difference to a CAPPI (wradlib.vpr.CAPPI) is that the blind area below and above the radar are not masked, but filled by interpolation. Only the areas beyond the range of the radar are masked out. As a result, “blind” areas below the radar are particularly filled from the lowest available elevation angle.

In order to create a Pseudo CAPPI, you first have to create an instance of this class. Calling this instance with the actual polar volume data will return the Pseudo CAPPI grid.

Parameters
  • polcoords (numpy.ndarray) – coordinate array of shape (num bins, 3) Represents the 3-D coordinates of the original radar bins

  • gridcoords (numpy.ndarray) – coordinate array of shape (num voxels, 3) Represents the 3-D coordinates of the Cartesian grid

  • maxrange (float) – The maximum radar range (must be the same for each elevation angle)

  • minelev (float) – The minimum elevation angle of the volume (degree)

  • maxelev (float) – The maximum elevation angle of the volume (degree)

  • ipclass (wradlib.ipol.IpolBase) – an interpolation class from wradlib.ipol

  • ipargs (dict) – keyword arguments corresponding to ipclass

Returns

output (numpy.ndarray) – float 1-d ndarray of the same length as gridcoords (num voxels, )

See also

out_of_range

Examples

See Recipe #2: Reading and visualizing an ODIM_H5 polar volume.

wradlib.vpr.out_of_range(center, gridcoords, maxrange)[source]#

Masks the region outside the radar range

Parameters
  • center (tuple) – radar location

  • gridcoords (numpy.ndarray) – array of 3-D coordinates with shape (num voxels, 3)

  • maxrange (float) – maximum range (same unit as gridcoords)

Returns

output (numpy.ndarray) – 1-D Boolean array of length len(gridcoords)

wradlib.vpr.blindspots(center, gridcoords, minelev, maxelev, maxrange)[source]#

Masks blind regions of the radar, marked on a 3-D grid

The radar is blind below the radar, above the radar and beyond the range. The function returns three boolean arrays which indicate whether (1) the grid node is below the radar, (2) the grid node is above the radar, (3) the grid node is beyond the maximum range.

Parameters
  • center (tuple) – radar location

  • gridcoords (numpy.ndarray) – array of 3-D coordinates with shape (num voxels, 3)

  • minelev (float) – The minimum elevation angle of the volume (degree)

  • maxelev (float) – The maximum elevation angle of the volume (degree)

  • maxrange (float) – maximum range (same unit as gridcoords)

Returns

output (tuple) – tuple of three boolean arrays (below, above, out_of_range) each of length (num grid points)