wradlib Documentation - Bitbucket

wradlib Documentation 

Release 0.1.1 

Maik Heistermann, Stefan Jacobi, Thomas Pfaff 

November 05, 2012

CONTENTS 

1 Getting Started 3 

1.1 Installing Python . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 

1.2 Installing wradlib . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 

1.3 Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 

1.4 Community . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 

2 Tutorials 7 

2.1 A typical workflow for radar-based rainfall estimation . . . . . . . . . . . . . . . . . . . . . . . . . 7 

2.2 Supported radar data formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 

2.3 Read and plot raw DWD radar data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 

2.4 Converting reflectivities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 

2.5 Integration of precipitation rates (Accumulation) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 

2.6 Clutter correction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 

2.7 Attenuation correction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 

3 Library Reference 35 

3.1 Raw Data I/O . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 

3.2 Reading BUFR Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 

3.3 Data Transformation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 

3.4 Z-R Conversions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 

3.5 Georeferencing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 

3.6 Interpolation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 

3.7 Data Quality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 

3.8 Composition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 

3.9 Clutter Identification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 

3.10 Filling Missing Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 

3.11 Vertical Profile of Reflectivity (VPR) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 

3.12 Attenuation Correction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 

3.13 Gage adjustment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 

3.14 Verification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 

3.15 Visualisation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86 

3.16 Utility functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90 

4 Development Setup 93 

4.1 Documentation Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 

5 Team 95 

5.1 Developers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 

5.2 Contributers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 

i

5.3 Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 

6 Indices and tables 97 

Bibliography 99 

Python Module Index 101 

Python Module Index 103 

ii

wradlib Documentation, Release 0.1.1 

The wradlib project has been initiated in order facilitate the use of weather radar data as well as to provide a common 

platform for research on new algorithms. wradlib is an open source library which is well documented and easy to use. 

It is written in the free programming language Python. 

Note: Please cite wradlib as Heistermann, M., Jacobi, S., and Pfaff, T.: Technical Note: An open source library for 

processing weather radar data (wradlib), Hydrol. Earth Syst. Sci. Discuss., 9, 12333-12356, doi:10.5194/hessd-9- 

12333-2012, 2012 

Weather radar data is potentially useful in meteorology, hydrology and risk management. Its ability to provide information 

on precipitation with high spatio-temporal resolution over large areas makes it an invaluable tool for short term 

weather forecasting or flash flood forecasting. 

wradlib is designed to assist you in the most important steps of processing weather radar data. These may include: 

reading common data formats, georeferencing, converting reflectivity to rainfall intensity, identifying and correcting 

typical error sources (such as clutter or attenuation) and visualising the data. 

This documentation is under steady development. It provides a complete library reference as well as a set of tutorials 

which will get you started in working with wradlib. 

CONTENTS 1


2 CONTENTS

CHAPTER 

ONE 

GETTING STARTED 

1.1 Installing Python 

In order to run wradlib, you need to have a Python interpreter installed on your local computer. wradlib will be guaranteed 

to work with a particular Python version, however, we will not guarantee upward or downward compatibility 

at the moment. The current version of wradlib is designed to be used with Python 2.7, but most features are also 

known to work under Python 2.6. 

wradlib was not designed to be a self-contained library. Besides extensive use of Numpy and Scipy, you might need 

to install additional libraries before you can use wradlib. See Dependencies for a full list of dependencies. Under 

Linux, the Python interpreter is usually pre-installed and installation of additional packages as well as dependency 

management is supposed to be easy. 

Under Windows operating systems, we strongly recommend to install a Python distribution such as 

Python(x,y) (http://code.google.com/p/pythonxy) which will contain most of the required packages. Go to 

http://code.google.com/p/pythonxy/wiki/Downloads, and select one of the Mirrors. Download the latest distribution 

(currently Python(x,y)-2.7.2.3.exe and install it. We recommend to use the full installation mode. 

When installing Python(x,y), make sure you choose “All Users” under the “Install for” menu component! 

Test the integrity of your Python installation by opening a console window and typing python. The console should 

show the Python version and a Python command prompt. Type 

>>> exit() 

in order to exit the Python environment. 

1.2 Installing wradlib 

Download the source from https://bitbucket.org/wradlib/wradlib via the get source button and extract it to any 

location on your computer. Inside the extracted folder, open a console window (on the same directory level as the 

setup.py file) and execute: 

>>> python setup.py install 

This way, the wradlib package will be installed under the Python site-packages directory and will thus be available for 

import. 

Test the integrity of your wradlib installation by opening a console window and typing python. The Python prompt 

should appear. Then type 

3


>>> import wradlib 

If everything is ok, nothing will happen. If the wradlib package is not found by the interpreter, you will get 


ImportError: No module named wradlib 

Check whether your Python installation directory contains the subdirectory /Lib/sitepackages/wradlib/wradlib and the 

corresponding source files. If the wradlib directory is not there, execute python setup.py install, again, and 

inspect the screen output if any helpful error messages are reported. 

You may receive other ImportErrors if required packages are missing. Please make sure the required packages are 

installed (see Dependencies). 

Attention: In order to use wradlib for decoding BUFR files (see Supported radar data formats), the installation (via 

python setup.py install) tries to compile and build the OPERA BUFR software (which is included in the 

wradlib source). This part of the installation has the potential to cause some trouble and was only tested on Windows 

7 machines, yet. The process requires gcc and make. Both are pre-installed on most Linux machines, and can be 

installed on Windows using the MinGW compiler suite. If you are using Python(x,y), gcc and mingw32-make 

should already be available on your machine! You can check this by opening a console window and typing gcc 

--version and mingw32-make --version. For Linux, the required makefile is available and we hope that 

the installation process works. But we never tested it! Please give us your feedback how it works under Linux by 

sending an e-mail to wradlib-users@googlegroups.com or by raising an issue. 

Beyond this issue, wradlib is intended to support at least Windows and Linux platforms, but it was tested only on 

Windows, yet. If you discover any platform issues on Linux, please do not hesitate to raise an issue. 

1.3 Dependencies 

wradlib was not designed to be a self-contained library. Besides extensive use of Numpy and Scipy, wradlib uses 

additional libraries, which you will need to install before you can use wradlib. Note that all libraries marked with a 

(*) are not contained in the Python(x,y) distribution and thus have to be definitely installed manually. 

For Windows users: If possible, we will link binary installer files for the libraries below. However, installers are not 

always available. In this case, you have to install from source. For pure Python packages, this is easy. Just extract the 

source, open a console window on the same level that contains the setup.py file and execute: 

python setup.py install 

• basemap (*): Download installer at http://sourceforge.net/projects/matplotlib/files/matplotlib-toolkits/basemap- 

1.0.2/ 

• h5py 

• matplotlib 

• netCDF4 

• numpy 

• numpydoc (*): Download source at http://pypi.python.org/pypi/numpydoc and install via python setup.py install 

• pylab 

• pyproj (*): Download installer at http://code.google.com/p/pyproj/downloads 

• scipy 

4 Chapter 1. Getting Started


1.4 Community 

wradlib is intended to be a community effort, and community needs communication. The key communication platform 

for wradlib is the wradlib-users mailing list and forum. Through this forum, you can help to improve wradlib 

by reporting bugs, proposing enhancements, or by contributing code snippets (in any programming language) and 

documentation of algorithms. You can also ask other users and developers for help, or use your own knowledge and 

experience to help other users. We strongly encourage you to subscribe to this list. Check it out! 

1.4. Community 5


6 Chapter 1. Getting Started

CHAPTER 

TWO 

TUTORIALS 

The tutorials should give an idea how the individual functions of wradlib can be used for weather radar processing. 

For additional help to certain functions also consider to have look at the code examples distributed with the source 

code. 

2.1 A typical workflow for radar-based rainfall estimation 

Raw, unprocessed reflectivity products can already provide useful visual information about the spatial distribution 

of rainfall fields. However, in order to use weather radar observations for quantitative studies (e.g. in hydrological 

modelling or for assimilation into Numerical Weather Prediction models), the data has to be carefully processed 

in order to account for typical errors sources such as ground echoes (clutter), attenuation of the radar signal, or 

uncertainties in the Z/R relationship. Moreover, it might be necessary to transfer the data from polar coordinates to 

Cartesian grids, or to combine observations from different radar locations in overlapping areas on a common grid 

(composition). And in the end, you would typically like to visualise the spatial rainfall distribution on a map. Many 

users also need to quantify the potential error (uncertainty) of their data-based rainfall estimation. 

These are just some steps that might be necessary in order to make radar data useful in a specific quantitative application 

environment. All steps together are typically referred to as a radar data processing chain. wradlib was designed to 

support you in establishing your own processing chain, suited to your specific requirements. In the following, we will 

provide an outline of a typical processing chain, step-by-step. You might not need all steps for your own workflow, 

or you might need steps which are not yet included here. Consider this just as an example. We will not go into detail 

for each step in this section, but refer to more detailed tutorials (if available) or the corresponding entry in the library 

reference. Most of the steps have a corresponding wradlib module. In order to access the functions of wradlib, you 

have to import wradlib in your Python console: 


If you have trouble with that import, please head back to the Getting Started section. 

Note: The code used in this tutorial can be found in the file wradib/examples/typical_workflow.py of 

the wradlib distribution. The corresponding example data is stored in wradlib/examples/data. 

Warning: Be aware that applying an algorithm for error correction does not guarantee that the error is totally 

removed. Error correction procedures are suceptible to errors, too. Not only might they fail to remove the error. 

They might also introduce new errors. The trade-off between costs (introduction of new errors) and benefits (error 

reduction) can turn out differently for different locations, different points in time, or different rainfall situations. 

7


2.1.1 Reading the data 

The binary encoding of many radar products is a major obstacle for many potential radar users. Often, decoder software 

is not easily available. wradlib support a couple of formats such as the OPERA BUFR and hdf5 implementations, 

NetCDF, and some formats used by the Germany Weather Service. We seek to continuously enhance the range of 

supported formats. 

The basic data type used in wradlib is a multi-dimensional array, the numpy.ndarray. Such an array might e.g. represent 

a polar or Cartesian grid, or a series of rain gage observations. Metadata are normally managed as Python dictionaries. 

In order to read the content of a data file into a numpy array, you would normally use the wradib.io module. In the 

following example, a local PPI from the German Weather Service, a DX file, is read: 

>>> data, metadata = wradlib.io.readDX("DX_sample_file") 

>>> wradlib.vis.polar_plot(data) # simple diagnostic plot 

The metadata object can be inspected via keywords. The data object contains the actual data, in this case a polar 

grid with 360 azimuth angles and 128 range bins. 

See Also: 

Get more info in the section Supported radar data formats and in the library reference section Raw Data I/O. 

2.1.2 Clutter removal 

Clutter are non-precipitation echos. They are caused by the radar beam hitting objects on the earth’s surface (e.g. 

mountain or hill tops, houses, wind turbines) or in the air (e.g. airplanes, birds). These objects can potentially cause 

high reflectivities due large scattering cross sections. Static clutter, if not efficiently removed by Doppler filters, can 

cause permanent echos which could introduce severe bias in quantitative applications. Thus, an efficient identification 

and removal of clutter is mandatory e.g. for hydrological studies. Clutter removal can be based on static maps or 

dynamic filters. Normally, static clutter becomes visible more clearly in rainfall accumulation maps over periods of 

weeks or months. We recommend such accumulations to create static clutter maps which can in turn be used to remove 

the static clutter from an image and fill the resulting gaps by interpolation. In the following example, the clutter filter 

published by Gabella and Notarpietro ([Gabella2002]) is applied to the single radar sweep of the above example. 

>>> clutter = wradlib.clutter.filter_gabella(data, tr1=12, n_p=6, tr2=1.1) 

>>> wradlib.vis.polar_plot(clutter,title=’Clutter Map’,colormap=pl.cm.gray) 

The resulting Boolean array clutter indicates the position of clutter. It can be used to interpolate the values at those 

positons from non-clutter values, as shown in the following line: 

>>> data_no_clutter = wradlib.ipol.interpolate_polar(data, clutter) 

It is generally recommended to remove the clutter before e.g. gridding the data because this might smear the clutter 

signal over multiple grid cells, and result into a decrease in identifiability. 

See Also: 

Get more info in the section Clutter correction and in the library reference section Clutter Identification. 

2.1.3 Attenuation correction 

Attenuation by wet radome and by heavy rainfall can cause serious underestimation of rainfall for C-Band and X- 

Band devices. For such radar devices, situations with heavy rainfall require a correction of attenuation effects. The 

general approach with single-polarized radars is to use a recursive gate-by-gate approach. See Kraemer and Verworn 

([Kraemer2008]) for an introduction to this concept. Basically, the specific attenuation k of the first range gate is 

computed via a so-called k-Z relationship. Based on k, the reflectivity of the second range gate is corrected and then 

used to compute the specific attenuation for the second range gate (and so on). The concept was first introduced by 

8 Chapter 2. Tutorials


Hitchfeld and Bordan ([Hitschfeld1954]). Its main drawback is its suceptibility to instable behaviour. wradlib provides 

a different implementations which address this problem. One example is the algorithm published by Kraemer and 

Verworn ([Kraemer2008]): 

>>> pia = wradlib.atten.correctAttenuationKraemer(data_no_clutter) 

>>> data_attcorr = data_no_clutter + pia 

The first line computes the path integrated attenuation pia for each radar bin. The second line line uses pia to correct 

the reflectivity values. Let’s inspect the effect of attenuation correction for an azimuth angle of 65?: 

>>> import pylab as pl 

>>> pl.plot(data_attcorr[65], label="attcorr") 

>>> pl.plot(data_no_clutter[65], label="no attcorr") 

>>> pl.xlabel("km") 

>>> pl.ylabel("dBZ") 

>>> pl.legend() 

>>> pl.show() 

See Also: 

Get more info in the library reference section Attenuation Correction. Here you will learn to know the algorithms 

available for attenuation correction and how to manipulate their behaviour by using additonal keyword arguments. 

2.1.4 Vertical Profile of Reflectivity 

Not yet available - implementation is ongoing. 

2.1.5 Conversion of reflectivity into rainfall 

Reflectivity (Z) and precipitation rate (R) can be related in form of a power law R=a*Z**b. The parameters a and b 

depend on the type of precipitation in terms of drop size distribution and water temperature. Before applying the Z-R 

relationship, we need to convert from dBZ to Z: 

>>> R = wradlib.zr.z2r( wradlib.trafo.idecibel(data_attcorr) ) 

The above line uses the default parameters parameters a=200 and b=1.6 for the Z-R relationship. In order to 

compute a rainfall depth from rainfall intensity, we have to specify an integration interval in seconds. In this example, 

we choos fove minutes (300 s), corresponding to the sweep return interval: 

>>> depth = wradlib.trafo.r2depth(R, 300) 

See Also: 

Get more info in the section Converting reflectivities and in the library reference sections Z-R Conversions and Data 

Transformation. Here you will learn about the effects of the Z-R parameters a and b. 

2.1.6 Rainfall accumulation 

For many applications, accumulated rainfall depths over specific time intervals are required, e.g. hourly or daily 

accumulations. wradlib supports the corresponding datetime operations. In the following example, we will use a 

synthetic time series of 5 minute intervals. Just imagine we have repeated the above procedure for one day of fiveminute 

sweeps and combined the arrays of rainfall depth in a 3-dimensional array of shape (number of time 

steps, number of azimuth angles, number of range gates). Now we want to ocompute hourly 

accumulations: 

2.1. A typical workflow for radar-based rainfall estimation 9


>>> import numpy as np 

>>> sweep_times = wradlib.util.from_to("2012-10-26 00:00:00", "2012-10-27 00:00:00", 300) 

>>> depths_5min = np.random.uniform(size=(len(sweep_times)-1, 360, 128)) 

>>> hours = wradlib.util.from_to("2012-10-26 00:00:00", "2012-10-27 00:00:00", 3600) 

>>> depths_hourly= wradlib.util.aggregate_in_time(depths_5min, sweep_times, hours, func=’sum’) 

Check the shape and values of your resulting array for plausibility: 

>>> print depths_hourly.shape 

(24, 360, 128) 

>>> print depths_hourly.mean().round() 

6.0 

See Also: 

Get more info in the library reference section Utility functions. 

2.1.7 Georeferencing and projection 

In order to define the horizontal and vertical position of the radar bins, we need to retrieve the corresponding 3- 

dimensional coordinates in terms of latitude, longitude and altitude. This information is required e.g. if the positions 

should be plotted on a map. It is also required for constructing CAPPIs. The position of a radar bin in 3-dimensional 

space depends on the position of the radar device, the elevation angle of the radar beam, as well as the azimuth angle 

and the range of a bin. For the sample data used above, the posiiton of the radar device is the Feldberg in Germany 

(47.8744, 8.005, 1517): 


>>> radar_location = (47.8744, 8.005, 1517) # (lat, lon, alt) in decimal degree and meters 

>>> elevation = 0.5 # in degree 

>>> azimuths = np.arange(0,360) # in degrees 

>>> ranges = np.arange(0, 128000., 1000.) # in meters 

>>> polargrid = np.meshgrid(ranges, azimuths) 

>>> lat, lon, alt = wradlib.georef.polar2latlonalt(polargrid[0], polargrid[1], elevation, radar_locat 

wradlib supports the projection of geographical coordinates (lat/lon) to a Cartesian reference system. Basically, you 

have to provide a string which represents the projection - based on the proj.4 library. You can look up projection 

strings, but for some projections, wradlib helps you to define a projection string. In the following example, the target 

projection is Gauss-Krueger (zone 3): 

>>> gk3 = wradlib.georef.create_projstr("gk", zone=3) 

>>> x, y = wradlib.georef.project(lat, lon, gk3) 

See Also: 

Get more info in the library reference section Georeferencing. 

2.1.8 Gridding 

Assume you would like to transfer the rainfall intensity from the above example (Conversion of reflectivity into rainfall) 

from polar coordinates to a Cartesian grid, or to an arbitrary set of irregular points in space (e.g. centroids of 

sub-catchments). You already retrieved the Cartesian coordinates of the radar bins in the previous section (Georeferencing 

and projection). Now you only need to define the target coordinates (e.g. a grid) and apply the togrid 

function of the wradlib.comp module. In this example, we want our grid only to represent the South-West sector 

of our radar circle on a 100 x 100 grid. First, we define the target grid coordinates (these must be an array of 100x100 

rows with one coordinate pair each): 



>>> xgrid = np.linspace(x.min(), x.mean(), 100) 

>>> ygrid = np.linspace(y.min(), y.mean(), 100) 

>>> grid_xy = np.meshgrid(xgrid, ygrid) 

>>> grid_xy = np.vstack((grid_xy[0].ravel(), grid_xy[1].ravel())).transpose() 

Now we transfer the polar data to the grid and mask out invalid values for plotting (values outside the radar circle 

receive NaN): 

>>> gridded = wradlib.comp.togrid(xy, grid_xy, 128000., np.array([x.mean(), y.mean()]), data.ravel(), 

>>> gridded = np.ma.masked_invalid(gridded).reshape((len(xgrid), len(ygrid))) 

>>> wradlib.vis.cartesian_plot(gridded, x=xgrid, y=ygrid, classes=range(0,70,5), unit="dBZ") 

See Also: 

Get more info about the function wradlib.comp.togrid. 

2.1.9 Adjustment by rain gage observations 

Adjustment normally refers to using rain ggage observations on the ground to correct for errors in the radar-based 

rainfall estimatin. Goudenhooftd and Delobbe [Goudenhoofdt2009] provide an excellent overview of adjustment 

procedures. A typical approach is to quantify the error of the radar-based rainfall estimate at the rain gage locations, 

assuming the rain gage observation to be accurate. The error can be assumed to be additive, multiplicative, or a mixture 

of both. Most approaches assume the error to be heterogeneous in space. Hence, the error at the rain gage locations 

will be interpolated to the radar bin (or grid) locations and then used to adjust (correct) the raw radar rainfall estimates. 

In the following example, we will use an illustrative one-dimensional example with synthetic data (just imagine radar 

rainfall estimates and rain gage observations along one radar beam). 

First, we create the synthetic “true” rainfall (truth). 


>>> radar_coords = np.arange(0,101) 

>>> truth = np.abs(1.5+np.sin(0.075*radar_coords)) + np.random.uniform(-0.1,0.1,len(radar_coords)) 

The radar rainfall estimate radar is then computed by imprinting a multiplicative error on truth and adding 

some noise. 

>>> error = 0.75 + 0.015*radar_coords 

>>> radar = error * truth + np.random.uniform(-0.1,0.1,len(radar_coords)) 

Synthetic gage observations obs are then created by selecting arbitrary “true” values. 

>>> obs_coords = np.array([5,10,15,20,30,45,65,70,77,90]) 

>>> obs = truth[obs_coords] 

Now we adjust the radar rainfall estimate by using the gage observations. First, you create an “adjustment object” 

from the approach you want to use for adjustment. After that, you can call the object with the actual data that is to be adjusted. 

Here, we use a multiplicative error model with spatially heterogenous error (see wradlib.adjust.AdjustMultiply). 

>>> adjuster = wradlib.adjust.AdjustMultiply(obs_coords, radar_coords, nnear_raws=3) 

>>> adjusted = adjuster(obs, radar) 

Let’s compare the truth, the radar rainfall estimate and the adjusted product: 


>>> pl.plot(radar_coords, truth, ’k-’, label="True rainfall", linewidth=2.) 

>>> pl.xlabel("Distance (km)") 

>>> pl.ylabel("Rainfall intensity (mm/h)") 

>>> pl.plot(radar_coords, radar, ’k-’, label="Raw radar rainfall", linewidth=2., linestyle="dashed") 

2.1. A typical workflow for radar-based rainfall estimation 11


>>> pl.plot(obs_coords, obs, ’o’, label="Gage observation", markersize=10.0, markerfacecolor="grey") 

>>> pl.plot(radar_coords, adjusted, ’-’, color="green", label="Multiplicative adjustment", linewidth= 

>>> pl.legend(prop={’size’:12}) 

>>> pl.show() 

See Also: 

Get more info in the library reference section Gage adjustment. There, you will also learn how to use the built-in 

cross-validation in order to evaluate the performance of the adjustment approach. 

2.1.10 Verification and quality control 

Typically, radar-based precipitation estimation and the effectiveness of the underlying correction and adjustment methods 

are verified by comparing the results against rain gauge observations on the ground. wradlib.verify provides procedures 

not only to extract the radar values at specific gauge locations, but also a set of error metrics which are computed 

from gage observations and the corresponding radar-based precipitation estimates (including standard metrics such 

as RMSE, mean error, Nash-Sutcliffe Efficiency). In the following, we will illustrate the usage of error metrics by 

comparing the “true” rainfall against the raw and adjusted radar rainfall estimates from the above example: 

>>> raw_error = wradlib.verify.ErrorMetrics(truth, radar) 

>>> adj_error = wradlib.verify.ErrorMetrics(truth, adjusted) 

Error metrics can be reported e.g. as follows: 

>>> raw_error.report() 

>>> adj_error.report() 

See Also: 

Get more info in the library reference section Verification. 

2.1.11 Visualisation and mapping 

In the above sections Reading the data, Clutter removal, and Gridding you already saw examples of the wradlib’s 

plotting capabilities. 

See Also: 

Get more info in the library reference section Visualisation. 

2.1.12 Data export to other applications 

Once you created a dataset which meets your requirements, you might want to export it to other applications or 

archives. wradlib does not favour or spupport a specific output format. Basically, you have all the freedom of choice 

offered by Python and its packages in order to export your data. Arrays can be stored as text or binary files by using 

numpy functions. You can use the package NetCDF4 to write NetCDF files, and the packages h5py or PyTables 

to write hdf5 files. At a later stage of development, wradlib might support a standardized data export by using the 

OPERA’s BUFR or hdf5 data model (see Supported radar data formats). Of course, you can also export data as 

images. See Visualisation for some options. 

Export your data array as a text file: 

>>> np.savetxt("mydata.txt", data) 

Or as a gzip-compressed text file: 



>>> np.savetxt("mydata.gz", data) 

Or as a NetCDF file: 

>>> import netCDF4 

>>> rootgrp = netCDF4.Dataset(’test.nc’, ’w’, format=’NETCDF4’) 

>>> sweep_xy = rootgrp.createGroup(’sweep_xy’) 

>>> dim_azimuth = sweep_xy.createDimension(’azimuth’, None) 

>>> dim_range = sweep_xy.createDimension(’range’, None) 

>>> azimuths_var = sweep_xy.createVariable(’azimuths’,’i4’,(’azimuth’,)) 

>>> ranges_var = sweep_xy.createVariable(’ranges’,’f4’,(’range’,)) 

>>> dBZ_var = sweep_xy.createVariable(’dBZ’,’f4’,(’azimuth’,’range’,)) 

>>> azimuths_var[:] = np.arange(0,360) 

>>> ranges_var[:] = np.arange(0, 128000., 1000.) 

>>> dBZ_var[:] = data 

You can easily add metadata to the NetCDF file on different group levels: 

>>> rootgrp.bandwith = "C-Band" 

>>> sweep_xy.datetime = "2012-11-02 10:15:00" 

>>> rootgrp.close() 

Note: An example for hdf5 export will follow. 

2.1.13 References 

2.2 Supported radar data formats 

The binary encoding of many radar products is a major obstacle for many potential radar users. Often, decoder software 

is not easily available. In case formats are documented, the implementation of decoders is a major programming effort. 

This tutorial provides an overview of the data formats currently supported by wradlib. We seek to continuously enhance 

the range of supported formats, so this document is only a snapshot. If you need a specific file format to be supported 

by wradlib, please raise an issue of type enhancement. You can provide support by adding documents which help to 

decode the format, e.g. format reference documents or software code in other languages for decoding the format. 

At the moment, supported format means that the radar format can be read and further processed by wradlib. Normally, 

wradlib will return an array of data values and a dictionary of metadata - if the file contains any. wradlib does not 

support encoding to any specific file formats, yet! This might change in the future, but it is not a priority. However, 

you can use Python’s netCDF4 or h5py packages to encode the results of your analysis to standard self-describing 

file formats such as netCDF or hdf5. If you have Python(x,y) installed on your machine, these packages are readily 

available to you. 

In the following, we will provide an overview of file formats which can be currently read by wradlib. Reading weather 

radar files is done via the Raw Data I/O module. There you will find a complete function reference. So normally, you 

will start by: 

import wradlib.io as io 

2.2.1 German Weather Service: DX format 

The German Weather Service uses the DX file format to encode local radar sweeps. DX data are in polar coordinates. 

The naming convention is as follows: raa00-dx_--—bin 

or raa00-dx_--—bin. Read and plot raw DWD radar 

2.2. Supported radar data formats 13


data provides an extensive introduction into working with DX data. For now, we would just like to know how to read 

the data: 

data, metadata = io.readDX("mydrive:/path/to/my/file/filename") 

Here, data is a two dimensional array of shape (number of azimuth angles, number of range gates). This means that 

the number of rows of the array corresponds to the number of azimuth angles of the radar sweep while the number of 

columns corresponds to the number of range gates per ray. 

2.2.2 German Weather Service: RADOLAN (quantitative) composit 

The quantitative composite format of the DWD (German Weather Service) was established in the course of the 

RADOLAN project. Most quantitative composite products from the DWD are distributed in this format, e.g. the 

R-series (RX, RY, RH, RW, ...), the S-series (SQ, SH, SF, ...), and the E-series (European quantitative composite, e.g. 

EZ, EH, EB). Please see the composite format description for a full reference and a full table of products (unfortunately 

only in German language). 

Currently, the RADOLAN composites have a spatial resolution of 1km x 1km, with the national composits (R- and 

S-series) being 900 x 900 grids, and the European composits 1500 x 1400 grids. The projection is polar-stereographic. 

The products can be read by the following function: 

data, metadata = io.read_RADOLAN_composite("mydrive:/path/to/my/file/filename") 

Here, data is a two dimensional integer array of shape (number of rows, number of columns). Different product 

types might need different levels of postprocessing, e.g. if the product contains rain rates or accumulations, you 

will normally have to divide data by factor 10. metadata is again a dictionary which provides metadata from the 

files header section, e.g. using the keys producttype, datetime, intervalseconds, nodataflag. Masking the NoData (or 

missing) values can be done by: 

import numpy as np 

maskeddata = np.ma.masked_equal(data, attrs["nodataflag"]) 

2.2.3 OPERA BUFR 

The Binary Universal Form for the Representation of meteorological data (BUFR) is a binary data format maintained 

by the World Meteorological Organization (WMO). The BUFR format was adopted by the OPERA program for the 

representation of weather radar data. This module provides a wrapper around the OPERA BUFR software, currently 

only for decoding BUFR files. If you intend to work with BUFR data, we recommend reading OPERA’s BUFR software 

documentation. Please note that the way the BUFR software is wrapped has to be considered very preliminary. 

Due to yet unsolved problems with the BUFR software API, wradlib simply calls the executable for BUFR deoding 

(decbufr) and read and parses corresponding the file output. This is of course inefficient from a computational perpective. 

we hope to come up with a new solution in the near future. However, the wradlib BUFR interface is plain 

simple: 

data, metadata = io.read_BUFR("mydrive:/path/to/my/file/filename") 

Basically, a BUFR file consists of a set of descriptors which contain all the relevant metadata and a data section. The 

descriptors are identified as a tuple of three integers. The meaning of these tupels is described in the BUFR tables 

which come with the software. There are generic BUFR tables provided by the WMO, but it is also possible to define 

so called local tables - which was done by the OPERA consortium for the purpose of radar data representation. 

wradlib.io.read_BUFR returns a two element tuple. The first element (data) of the return tuple is the actual 

data array. It is a multi-dimensional numpy array of which the shape depends on the descriptor specifications (mostly 

it will be 2-dimensional). The second element (metadata) is a tuple of two dictionaries (descnames, descvals). 

descnames relates the descriptor identifiers to comprehensible descriptor names. descvals relates the descriptor names 



to descriptor values. E.g. if the descriptor identifier was (0, 30, 21), the descriptor name would be ‘Number of pixels 

per row’ and the descriptor value could be an integer which actually specifies the number of rows of a grid. Just try: 

# Gives the descriptor name for each descriptor ID tuple 

print metadata[0] 

# Gives the descriptor value for each descriptor name 

print metadata[1] 

# Gives the descriptor value for a particular descriptor ID tuple, in this case (0, 30, 21) 

print metadata[1][ metadata[0][(0, 30, 21)] ] 

Gotchas: At the moment, the BUFR implementation in wradlib has the potential to give you some trouble. It has 

only been tested on Windows 7 under Python 2.6, yet. The key is that the BUFR software has to be successfully 

compiled in the course of wradlib installation (via python setup.py install). Compilation requires gcc and make. Both 

is pre-installed on most Linux machines, and can be installed on Windows using the MinGW compiler suite. If you 

are using Python(x,y), gcc and make should already be available on your machine! You can check this by opening 

a console window and typing gcc --version and mingw32-make --version. For Linux, the makefile is 

available and we hope that the installation process works. But we never tested it! Please give us your feedback how it 

works under Linux by sending an e-mail to wradlib-users@googlegroups.com or by raising an issue. 

2.2.4 OPERA HDF5 (ODIM_H5) 

HDF5 is a data model, library, and file format for storing and managing data. The OPERA 3 program developed a 

convention (or information model) on how to store and exchange radar data in hdf5 format. It is based on the work 

of COST Action 717 and is used e.g. in real-time operations in the Nordic European countries. The OPERA Data 

and Information Model (ODIM) is documented e.g. in this report and in a UML representation. Make use of these 

documents in order to understand the organization of OPERA hdf5 files! 

The hierarchical nature of HDF5 can be described as being similar to directories, files, and links on a hard-drive. 

Actual metadata are stored as so-called attributes, and these attributes are organized together in so-called groups. 

Binary data are stored as so-called datasets. As for ODIM_H5, the root (or top level) group contains three groups of 

metadata: these are called what (object, information model version, and date/time information), where (geographical 

information), and how (quality and optional/recommended metadata). For a very simple product, e.g. a CAPPI, the 

data is organized in a group called dataset1 which contains another group called data1 where the actual binary 

data are found in data. In analogy with a file system on a hard-disk, the HDF5 file containing this simple product is 

organized like this: 

/ 

/what 

/where 

/how 

/dataset1 

/dataset1/data1 

/dataset1/data1/data 

The philosophy behind the wradlib interface to OPERA’s data model is very straightforward: wradlib simply translates 

the complete file structure to one dictionary and returns this dictionary to the user. Thus, the potential complexity of 

the stored data is kept and it is left to the user how to proceeed with this data. The keys of the output dictionary are 

strings that correspond to the “directory trees” shown above. Each key ending with /data points to a Dataset (i.e. a 

numpy array of data). Each key ending with /what, /where or /how points to another dictionary of metadata. The 

entire output can be obtained by: 

fcontent = io.read_OPERA_hdf5("mydrive:/path/to/my/file/filename") 

The user should inspect the output obtained from his or her hdf5 file in order to see how access those items which 

should be further processed. In order to get a readable overview of the output dictionary, one can use the pretty printing 

module: 

2.2. Supported radar data formats 15


# which keyswords can be used to access the content? 

print fcontent.keys() 

# print the entire content including values of data and metadata 

# (numpy arrays will not be entirely printed) 

import pprint as pp 

pp.pprint(fcontent) 

Please note that in order to experiment with such datasets, you can download hdf5 sample data from the Odyssey page 

of the OPERA 3 homepage. 

2.2.5 GAMIC HDF5 

GAMIC refers to the commercial GAMIC Enigma V3 MURAN software which exports data in hdf5 format. The 

concept is quite similar to the above OPERA HDF5 (ODIM_H5) format. Such a file (typical ending: .mvol) can be 

read by: 

data, metadata = io.read_GAMIC_hdf5("mydrive:/path/to/my/file/filename") 

While metadata represents the usual dictionary of metadata, the data variable is a dictionary which might contain 

several numpy arrays with the keywords of the dictionary indicating different moments. 

2.2.6 NetCDF 

The NetCDF format also claims to be self-describing. However, as for all such formats, the developers of netCDF 

also admit that “[...] the mere use of netCDF is not sufficient to make data self-describing and meaningful to both 

humans and machines [...]”. The program that reads the data needs to know about the expected content. Different 

radar operators or data distributors will use different naming conventions and data hierarchies. Even though Python 

provides a decent netCDF library (netcdf4), wradlib will need to provide different interfaces to netCDF files offered 

by different distributors. 

NetCDF files exported by the EDGE software 

EDGE is a commercial software for radar control and data analysis provided by the Entreprise Electronics Corporation. 

It allows for netCDF data export. The resulting files can be read by: 

data, metadata = io.read_EDGE_netcdf("mydrive:/path/to/my/file/filename") 

2.3 Read and plot raw DWD radar data 

This tutorial helps you to read the raw radar data as provided by German Weather Service (DWD), to transform the 

data to dBZ values and to plot the results. 

2.3.1 Reading DX-data 

First step we often have to do for weather radar data processing is to decode the data from their binary raw format. 

The German weather service provides its radar data as so called DX-data. These have to be unpacked and transfered 

into an array of 360 (angular values in resolution of 1 degree) by 128 (range values in resolution of 1 km). 

The naming convention for dx-data is: raa00-dx_--—bin 

or raa00-dx_--—bin. For example: raa00-dx_10908- 

200608281420-fbg—bin raw data from radar station Feldberg (fbg, 10908) from 28.8.2006 14:20. 

The DX-file contains also additional information like elevation angles and azimuths. 



Raw data for one time step 

Suppose we want to read a radar-scan for a defined time step: 

import wradlib as wrl 

# set the location of your data 

datadir = ’D:/THIS/IS/MY/DATA/DIRECTORY/’ 

singular_data, attributes = wrl.io.readDX(datadir + ’raa00-dx_10908-200608281420-fbg---bin’) 

Since the readDX function returns two variables, the scan values and the elevation/azimuth information, the function 

is assigned to two variables. 

Raw data for multiple time steps 

First we should create an empty array with the shape of the desired dimensions. In this example, the dataset contains 

2 timesteps of 360 by 128 values. Since we don’t need the attribute information the function call is indexed just for 

the first variable.: 


multiple_data = np.empty((2,360,128)) 

multiple_data[0] = wrl.io.readDX(datadir + ’raa00-dx_10908-200608180225-fbg---bin’)[0] 

multiple_data[1] = wrl.io.readDX(datadir + ’raa00-dx_10908-200608180230-fbg---bin’)[0] 

2.3.2 Visualizing dBZ values 

Now we want to plot the results of the sinular scan in a polar plot. 

The quick solution: 

wrl.vis.polar_plot(singular_data) 

we see a typical stratiform precipitation: 

2.3. Read and plot raw DWD radar data 17


with two shielding effects, the foothills of the Alps and unfortunately a spike caused by a television tower nearby the 

radar antenna. 

As another image visualization: 

wrl.vis.polar_plot(multiple_data[0]) 

typical convective precipitation cells: 



We can add little adornment like a title, units and a spectral colormap for better identifiability of values: 

wrl.vis.polar_plot(multiple_data[0], title = ’Reflectivity: Radarscan Feldberg 18-08-2006 02:25’, 

unit = ’dBZ’, colormap = ’spectral’) 



Usually we talk about rain, when reflectivities exceed 20 dBZ (corresponding to a precipitation of 0.6 mm/h), thus we 

set the lower end of the colormap to an value of 20 dBZ for masking the wet noise: 


unit = ’dBZ’, colormap = ’spectral’, vmin = 20) 



And for a better comparison of the stratiform and the convective precipitation we fix the upper end of the colormap to 

the maximum value of the datasets: 

max_data = max(singular_data.max(), multiple_data[0].max()) 

wrl.vis.polar_plot(singular_data, title = ’Reflectivity: Radarscan Feldberg 28-08-2006 14:20’, 

unit = ’dBZ’, colormap = ’spectral’, vmin = 20, vmax = max_data) 


unit = ’dBZ’, colormap = ’spectral’, vmin = 20, vmax = max_data) 



All raw data is provided by DWD 

2.4 Converting reflectivities 

Reflectivity (Z) and precipitation rate (R) can be related in form of a power law R=a*Z**b. The parameters a and b 

depend on the type of precipitation (i.e. drop size distribution and water temperature). 

Because the ZR-relationship is based on reflectivities in Z and the encoded radar data is given in dBZ we have to take 

the antilogarithm of the dBZ-values after reading the DX-data (Read and plot raw DWD radar data): 




data_dBZ = wrl.io.readDX(datadir + ’raa00-dx_10908-200608180225-fbg---bin’)[0] 

data_Z = wrl.trafo.idecibel(data_dBZ) 

After taking the antilogarithm the scale of low precipitation rates appears distinctly more squeezed: 

wrl.vis.polar_plot(data_dBZ, title = ’Reflectivity: Radarscan Feldberg 18-08-2006 02:25’, 

unit = ’dBZ’, colormap = ’spectral’) 

wrl.vis.polar_plot(data_Z, title = ’Reflectivity: Radarscan Feldberg 18-08-2006 02:25’, 

unit = ’Z’, colormap = ’spectral’) 



2.4.1 Converting reflectivities to precipitation rates 

Now we convert the reflectivities to precipitation rates. As we see in the previous image the reflectivities reach values 

of about 60 dBZ. This and the structure of the precipitation cells is indicating a convective precipitation type. That’s 

why we will use the Marshall-Palmer ZR-relationship with parameters of a=200 and b=1.6. Since that are the default 

settings for the z2r-function, we don’t have to assign additional parameters: 

data_Rc_c = wrl.zr.z2r(data_Z) 

wrl.vis.polar_plot(data_Rc_c, title = ’Rain rate: Radarscan Feldberg 18-08-2006 02:25\nConvective ZRunit 

= ’mm/h’, colormap = ’spectral’) 

The structure of precipitation cells is indicating a convective precipitation type. 

2.4. Converting reflectivities 23


We try out what happens, if we convert the same reflectivity scan based on a ZR-relation with parameters for stratiform 

precipitation (below left) and look for the difference (below right) between both results: 

data_Rc_s = wrl.zr.z2r(data_Z, a = 256., b = 1.42) 

dif = data_Rc_s - data_Rc_c 

wrl.vis.polar_plot(data_Rc_s, title = ’Rain rate: Radarscan Feldberg 18-08-2006 02:25\nStratiform ZRunit 

= ’mm/h’, colormap = ’spectral’) 

wrl.vis.polar_plot(dif, title = ’’’Difference of convective rain transformed with 

convective respectively stratiform ZR-relationships’’’, unit = ’mm/h’, colormap = ’spectral’) 



At first view the results of the convective and the stratiform ZR-relationsship look very similar, but take the scalebar 

into account. That explains the differnce in the right image, where you can observe punctual overestimations up to 

160 mm/h. 

That is because the reflecting signal of a rain drop with a diameter of 5mm (heavy precipitation) is equal to about 

15000 raindrops (light precipitation) with a diameter of 1mm. At which the latter are weighing more than 100 times 

of the first one. 

Given that in flash flood forecasting an overestimation of convective rainstorms is more critical (false alarm) than an 

underestimation of light precipitation, the default is set to the convective type of rain. If we know the precipitation 

type exactly, the corresponding ZR-parameters should be applicated of course. 

Now we should examine what happens, if we convert a stratiform precipitation event with ZR-relationsships for 

stratiform respectively convective precipitation. In this case we use the same scale extends: 


data_Z = wrl.trafo.idecibel(data_dBZ) 

data_Rs_s = wrl.zr.z2r(data_Z, a = 256., b = 1.42) 

data_Rs_c = wrl.zr.z2r(data_Z) 

max_data = max(data_Rs_s.max(), data_Rs_c.max()) 

dif = data_Rs_s - data_Rs_c 

wrl.vis.polar_plot(data_Rs_s, title = ’Rain rate: Radarscan Feldberg 28-08-2006 14:20\nStratiform ZRunit 

= ’mm/h’, colormap = ’spectral’, vmax = max_data) 

wrl.vis.polar_plot(data_Rs_c, title = ’Rain rate: Radarscan Feldberg 28-08-2006 14:20\nConvective ZRunit 

= ’mm/h’, colormap = ’spectral’, vmax = max_data) 

wrl.vis.polar_plot(dif, title = ’’’Difference of convective rain transformed with 

stratiform respectively convective ZR-relationships’’’, unit = ’mm/h’, colormap = ’spectral’) 

2.4. Converting reflectivities 25


Consistently the conversion image with the wrongly supposed convective ZR-parameters (upper right) underestimates 

the supposeable more precisely conversion with stratiform ZR-parameters (upper left). But the underestimation isn’t 

exceeding values of more than 4.2 mm/h, which is quite acceptable. 




2.5 Integration of precipitation rates (Accumulation) 

2.5.1 Integrating precipitation rate of one radar scan over its corresponding time 

interval 

For many purposes in hydrology you need data of precipitation depth. For that reason we have to integrate the 

precipitation rate over the interval of the corresponding radar scan. In case of the radar stations of the German Weather 

Service the precipitation scan is repeated at intervals of 5 minutes (300 seconds): 





data_R_rate = wrl.zr.z2r(wrl.trafo.idecibel(data_dBZ)) # in mm/h!!! 

data_R_depth = wrl.trafo.r2depth(data_R_rate, 300.) # in mm!!! 

wrl.vis.polar_plot(data_R_depth, title = ’Precipitation height 18.8.2006, 00:00 - 00:05 (Radarstation 

unit = ’mm’, colormap = ’spectral’) 

2.5. Integration of precipitation rates (Accumulation) 27


2.5.2 Integrating and accumulating precipitation rates of several radar scans 

To avoid reading each radar scan seperately, we first build an array of the timesteps we need, in order to scale the 

solution for longer time intervals. Suppose we want to accumulate the precipitation between 18.8.2006 00:05 and 

18.8.2006 02:05: 

# the datetime library facilitates the work with timesteps 

import datetime as dt 


# begin and end of the accumulation interval stripped to a datetime format 

t_start = dt.datetime.strptime(’2006-08-18 00:05:00’, ’%Y-%m-%d %H:%M:%S’) 

t_end = dt.datetime.strptime(’2006-08-18 02:05:00’, ’%Y-%m-%d %H:%M:%S’) 

# empty list container for the resulting timesteps array 

times = [] 

# temporal scan resolution in seconds as increment 

t_scan_res = 300. 

incr = dt.timedelta(seconds=t_scan_res) 

curtime = t_start 

while curtime >> print times 

[2006-08-18 00:05:00 2006-08-18 00:10:00 2006-08-18 00:15:00 

2006-08-18 00:20:00 2006-08-18 00:25:00 2006-08-18 00:30:00 

2006-08-18 00:35:00 2006-08-18 00:40:00 2006-08-18 00:45:00 

2006-08-18 00:50:00 2006-08-18 00:55:00 2006-08-18 01:00:00 

2006-08-18 01:05:00 2006-08-18 01:10:00 2006-08-18 01:15:00 

2006-08-18 01:20:00 2006-08-18 01:25:00 2006-08-18 01:30:00 

2006-08-18 01:35:00 2006-08-18 01:40:00 2006-08-18 01:45:00 

2006-08-18 01:50:00 2006-08-18 01:55:00 2006-08-18 02:00:00] 

We create an empty 3-dimensional array (time, azimuth, elevation) for all the radar data: 

data_dBZ = np.repeat(np.empty(46080), len(scans)).reshape(len(scans),360,128) 

Now we can fill the empty array with radar data (Read and plot raw DWD radar data): 

for i,time in enumerate(scans): 

f = ’raa00-dx_10908-’ + time.strftime(’%Y%m%d%H%M’) + ’-fbg---bin’ 

data_dBZ[i,:,:] = wrl.io.readDX(datadir + f)[0] 

and compute 5-minute-precipitation depths (Read and plot raw DWD radar data, Converting reflectivities): 

data_R_depth = wrl.trafo.r2depth(wrl.zr.z2r(data_Z = wrl.trafo.idecibel(data_dBZ)), t_scan_res) 

Before accumulating we finally have to build an array with the accumulated timesteps (e.g. hourly): 

# list container for the array of accumulated time steps 

accum_times = [] 

# accumulation interval (3600 = 1 hour) 

accum_interval = 3600. 

incr = dt.timedelta(seconds=accum_interval) 

curtime = t_start 

while curtime


Now we have everything we need for the accumulation: 

accum_data = wrl.util.aggregate_in_time(data_R_depth, times, accum_times) 

wrl.vis.polar_plot(accum_data[0], title = ’Precipitation height 18.8.2006, 00:05-01:05 (Radarstation 

unit = ’mm’, colormap = ’spectral’, vmax = max(accum_data)) 

wrl.vis.polar_plot(accum_data[1], title = ’Precipitation height 18.8.2006, 01:05-02:05 (Radarstation 

unit = ’mm’, colormap = ’spectral’, vmax = max(accum_data)) 

.. image:: images/precip_movie.gif 


2.6 Clutter correction 

Weather radar data with clutter (static and dynamic echos, not caused by precipitation) can be disastrously if used for 

hydrological rainfall-runoff modeling or related to attenuation correction of non-coherent radar data. So in most cases 

it is indispensable to detect and remove clutter bins from your radar data. 

The wradlib function histo_cut is an histogram based clutter identification algorithm. It classifies an (preferential 

yearly based) precipitation accumulation of radar data into 50 classes and removes iteratively framing classes which 

undercut 1% of the class with the highest frequency. 

In a first step you need an radar-image with an representative accumulation timespan, so that precipitation is distributed 

evenly over the image. As for example this philipinean image, where the scale extend shows us definitely the occurance 

of clutter: 

2.6. Clutter correction 29


With the accumulation data as an input histo_cut returns an mask array with ones where clutter is detected: 


accumulation_array = np.loadtxt(’d:/Stephan/Arbeit/PROGRESS/Daten/Philipines_s-band/netcdf/addition/p 

cluttermask = wrl.clutter.histo_cut(accumulation_array) 



What happens behind the curtain is, histo_cut computes an histogram for all radar bins and the corresponding mask: 

Seen from the class with the highest frequency histo_cut searches to the left and the right of the histogram for the 

2.6. Clutter correction 31


nearest class wich underscores 1% of highest frequency class and cuts all values beyond these classes by setting them 

Nan. 

As the result you see an histogram with a more narrow span of precipitation amounts and an updated clutter mask. 

This procedure is repeated iteratively until, the changes fall below a threshold value. The result are the final histogram 

and cluttermask: 

Now the clutter bins should be substituted by some meaningful values derived by nearest neighbour or linear interpolation: 



# get the radar data which should be clutter corrected 

data, attrs = wrl.io.read_EDGE_netcdf(datadir + ’SUB-20110927-050748-01-Z.nc’, range_lim = 100000) 



# define clutter-indices on the basis of the clutter-mask 

clutter_indices = np.where(cluttermask.ravel()) 

# compute bin centroid coordinates in cartesian map projection 

r = attrs[’r’] / 1000. 

az = attrs[’az’] 

sitecoords = attrs[’sitecoords’][0:-1] 

projstr = ’+proj=utm +zone=51 +ellps=WGS84’ 

binx, biny = wrl.georef.projected_bincoords_from_radarspecs(r, az, sitecoords, projstr) 

binx = binx.ravel() 

biny = biny.ravel() 

# coordinate pairs without clutter 

good_coordinates_list = np.array([(np.delete(binx,clutter_indices)), (np.delete(biny,clutter_indices) 

# list of the entire coordinate pairs from radarcircle 

trgcoord = np.array([binx, biny]).transpose() 

# building object class for nearest neighbour interpolation either for directly requested interpolati 

# by nearest neighbours or for filling the boundary gap caused by linear interpolation 

intpol_nearest = wrl.ipol.Nearest(good_coordinates_list, trgcoord) 

# building object class for linear interpolation 

intpol_linear = wrl.ipol.Linear(good_coordinates_list, trgcoord) 

# substitute clutter by interpolation methods 

# Conversion from dBZ to rainintensity 

rain_intensity = wrl.zr.z2r(wrl.trafo.idecibel(data)).ravel() 

# Substitute Nan 

rain_intensity = np.where(np.isnan(rain_intensity), 0, rain_intensity ) 

# rain intensity data without clutter 

values_list = np.delete(rain_intensity,clutter_indices) 

# spatial interpolation of rain intensity for the whole radar scan based on the data without clutter 

filled_R = intpol_nearest(values_list).reshape(len(attrs[’az’]), len(attrs[’r’])) 

# calculating nearest neighbour interpolation if requested and filling possible boundary gaps 

filled_R_linear = intpol_linear(values_list).reshape(len(attrs[’az’]),len(attrs[’r’])) 

filled_R = np.where(np.isnan(filled_R_linear), filled_R, filled_R_linear) 

rain_intensity = rain_intensity.reshape(len(attrs[’az’]), len(attrs[’r’])) 

wrl.vis.polar_plot(rain_intensity, title = ’Rain intensity’, unit = ’mm/h’, 

R = attrs[’max_range’] / 1000., colormap = ’spectral’, vmax = 140.) 

wrl.vis.polar_plot(filled_R, title = ’Clutter corrected rain intensity’, 

unit = ’mm/h’, R = attrs[’max_range’] / 1000., colormap = ’spectral’, vmax = 140.) 

As the result you will see the original rain intensity (left) and the image with clutter correction (right) 

.. image:: images/cluttercorrection.gif 

2.7 Attenuation correction 

... to be continued ... 

2.7. Attenuation correction 33



CHAPTER 

THREE 

LIBRARY REFERENCE 

3.1 Raw Data I/O 

Please have a look at the tutorial Supported radar data formats for an introduction on how to deal with different file 

formats. 

readDX 

writePolygon2Text 

read_EDGE_netcdf 

read_BUFR 

read_OPERA_hdf5 

read_GAMIC_hdf5 

read_RADOLAN_composite 

Data reader for German Weather Service DX raw radar data files 

Writes Polygons to a Text file which can be interpreted by ESRI ArcGIS’s “Create Features from T 

Data reader for netCDF files exported by the EDGE radar software 

Main BUFR interface: Decodes BUFR file and returns metadata and values 

Reads hdf5 files according to OPERA conventions 

Data reader for hdf5 files produced by the commercial GAMIC Enigma V3 MURAN software 

Read quantitative radar composite format of the German Weather Service 

3.1.1 wradlib.io.readDX 

wradlib.io.readDX(filename) 

Data reader for German Weather Service DX raw radar data files developed by Thomas Pfaff. 

The algorith basically unpacks the zeroes and returns a regular array of 360 x 128 data values. 

Parameters filename : binary file of DX raw data 

Returns data : numpy array of image data [dBZ]; shape (360,128) 

attributes : dictionary of attributes - currently implemented keys: 

• ‘azim’ - azimuths np.array of shape (360,) 

• ‘elev’ - elevations (1 per azimuth); np.array of shape (360,) 

• ‘clutter’ - clutter mask; boolean array of same shape as data; corresponds to bit 15 set 

in each dataset. 

3.1.2 wradlib.io.writePolygon2Text 

wradlib.io.writePolygon2Text(fname, polygons) 

Writes Polygons to a Text file which can be interpreted by ESRI ArcGIS’s “Create Features from Text File 

(Samples)” tool. 

This is (yet) only a convenience function with limited functionality. E.g. interior rings are not yet supported. 

35


Parameters fname : string 

name of the file to save the vertex data to 

polygons : list of lists 

list of polygon vertices. Each vertex itself is a list of 3 coordinate values and an additional 

value. The third coordinate and the fourth value may be nan. 

Returns None : 

Notes 

As Polygons are closed shapes, the first and the last vertex of each polygon must be the same! 

Examples 

Writes two triangle Polygons to a text file 

>>> poly1 = [[0.,0.,0.,0.],[0.,1.,0.,1.],[1.,1.,0.,2.],[0.,0.,0.,0.]] 

>>> poly2 = [[0.,0.,0.,0.],[0.,1.,0.,1.],[1.,1.,0.,2.],[0.,0.,0.,0.]] 

>>> polygons = [poly1, poly2] 

>>> writePolygon2Text(’polygons.txt’, polygons) 

The resulting text file will look like this: 

Polygon 

0 0 

0 0.000000 0.000000 0.000000 0.000000 

1 0.000000 1.000000 0.000000 1.000000 

2 1.000000 1.000000 0.000000 2.000000 

3 0.000000 0.000000 0.000000 0.000000 

1 0 

0 0.000000 0.000000 0.000000 0.000000 

1 0.000000 1.000000 0.000000 1.000000 

2 1.000000 1.000000 0.000000 2.000000 

3 0.000000 0.000000 0.000000 0.000000 

END 

3.1.3 wradlib.io.read_EDGE_netcdf 

wradlib.io.read_EDGE_netcdf(filename, range_lim=200000.0) 

Data reader for netCDF files exported by the EDGE radar software 

Parameters filename : path of the netCDF file 

range_lim : range limitation [m] of the returned radar data 

(200000 per default) 

Returns output : numpy array of image data (dBZ), dictionary of attributes 

3.1.4 wradlib.io.read_BUFR 

wradlib.io.read_BUFR(buffile) 


36 Chapter 3. Library Reference


The actual function refererence is contained in wradlib.bufr.decodebufr. 

3.1.5 wradlib.io.read_OPERA_hdf5 

wradlib.io.read_OPERA_hdf5(fname) 

Reads hdf5 files according to OPERA conventions 

Please refer to the OPERA data model documentation in order to understand how an hdf5 file is organized that 

conforms to the OPERA ODIM_H5 conventions. 

In contrast to other file readers under wradlib.io, this function will not return a two item tuple with (data, 

metadata). Instead, this function returns ONE dictionary that contains all the file contents - both data and 

metadata. The keys of the output dictionary conform to the Group/Subgroup directory branches of the original 

file. If the end member of a branch (or path) is “data”, then the corresponding item of output dictionary is 

a numpy array with actual data. Any other end member (either how, where, and what) will contain the meta 

information applying to the coresponding level of the file hierarchy. 

Parameters fname : string (a hdf5 file path) 

Returns output : a dictionary that contains both data and metadata according to the 

original hdf5 file structure 

3.1.6 wradlib.io.read_GAMIC_hdf5 

wradlib.io.read_GAMIC_hdf5(filename, range_lim=100000.0, wanted_elevations=‘1.5’, 

wanted_moments=’UH’) 

Data reader for hdf5 files produced by the commercial GAMIC Enigma V3 MURAN software 

Provided by courtesy of Kai Muehlbauer (University of Bonn). 

(http://www.gamic.com/cgi-bin/info.pl?link=softwarebrowser3). 

Parameters filename : path of the gamic hdf5 file 

scan_type : string 

“PPI” (plain position indicator) or “RHI” (radial height indicator) 

range_lim : float 

range limitation (meters) of the returned radar data (100000. by default) 

See GAMIC homepage for further info 

elevation_angle : sequence of strings of elevation_angle(s) of scan (only needed for PPI) 

moments : sequence of strings of moment name(s) 

Returns data : dictionary of scan and moment data (numpy arrays) 

attrs : dictionary of attributes 

3.1.7 wradlib.io.read_RADOLAN_composite 

wradlib.io.read_RADOLAN_composite(fname) 

Read quantitative radar composite format of the German Weather Service 

The quantitative composite format of the DWD (German Weather Service) was established in the course of the 

RADOLAN project and includes several file types, e.g. RX, RO, RK, RZ, RP, 

RT, RC, RI, RG and many, many more (see format description on the project homepage, [DWD2009). 

3.1. Raw Data I/O 37


At the moment, the national RADOLAN composite is a 900 x 900 grid with 1 km resolution and in polarstereographic 

projection. 

Parameters fname : path to the composite file 

Returns output : tuple of two items (data, attrs) 

• data : numpy array of shape (number of rows, number of columns) 

• attrs : dictionary of metadata information from the file header 

References 

[DWD2009] 

3.2 Reading BUFR Files 

The Binary Universal Form for the Representation of meteorological data (BUFR) is a binary data format maintained 

by the World Meteorological Organization (WMO). The BUFR format was adopted by the OPERA program for the 

representation of weather radar data. This module provides a wrapper around the OPERA BUFR software, currently 

only for decoding BUFR files. In the future, functions for BUFR encoding might be added as well. If you intend to 

work with BUFR data, we recommend reading OPERA’s BUFR software documentation. 

decodebufr 

parse_desctable 


Parses the decriptor table and returns a dictionary of descriptors 

3.2.1 wradlib.bufr.decodebufr 

wradlib.bufr.decodebufr(buffile) 


The BUFR file format is a self-describing binary format for meteorological data. wradlib uses 

the decoding software from the OPERA 3 program. All background information is available under 

http://www.knmi.nl/opera/bufr.html. 

Basically, a BUFR file consists of a set of descriptors which contain all the relevant metadata and a data section. 

The descriptors are identified as a tuple of three integers. The meaning of these tupels is described in the so 

called BUFR tables. There are generic BUFR tables provided by the WMO, but it is also possible to define so 

called local tables - which was done by the OPERA consortium for the purpose of radar data representation. 

This decoding function returns a two element tuple. The first element of the return tuple is the actual data array. 

It is a multi-dimensional numpy array of which the shape depends on the descriptor specifications (mostly it 

will be 2-dimensional). The second element is a tuple of two dictionaries (descnames, descvals). descnames 

relates the descriptor identifiers to comprehensible descriptor names. descvals relates the descriptor names to 

descriptor values. E.g. if the descriptor identifier was (0, 30, 21), the descriptor name would be ‘Number of 

pixels per row’ and the descriptor value could be an integer which actually specifies the number of rows of a 

grid. 

Parameters buffile : Path to a BUFR file 

Returns output: a tuple with two elements (data, metadata) : 

• data : the actual data as a multidimensional numpy array 

• metadata : tuple of two elements (descnames, descvals) 



– descnames: a dictionary of descriptor names 

– descvals: dictionary of descriptor values 

Examples 

>>> import wradlib.bufr as bufr 

>>> buffile = "wradlib/examples/data/test.buf" 

>>> data, metadata = bufr.decodebufr(buffile) 

>>> metadata 

>>> data.shape 

3.2.2 wradlib.bufr.parse_desctable 

wradlib.bufr.parse_desctable(fpath) 

Parses the decriptor table and returns a dictionary of descriptors 

Parameters fpath : string representing the path to the descriptor table file 

Returns output : a tuple of two dictionaries (descnames, descvals) 

• descnames: a dictionary of descriptor names 

• descvals: dictionary of descriptor values 

3.3 Data Transformation 

Module transforms data e.g. from RVP-units to dBZ-values to Z-values and vice versa. 

rvp2dBZ 

decibel 

idecibel 

r2depth 

Calculates dBZ-values from DWD RVP6 values as given in DX-product 

Calculates the decibel representation of the input values 

Calculates the inverse of input decibel values 

Computes rainfall depth (mm) from rainfall intensity (mm/h) 

3.3.1 wradlib.trafo.rvp2dBZ 

wradlib.trafo.rvp2dBZ(x) 

Calculates dBZ-values from DWD RVP6 values as given in DX-product files. 

Parameters x : a number or an array 

3.3.2 wradlib.trafo.decibel 

wradlib.trafo.decibel(x) 

Calculates the decibel representation of the input values dBZ = 10*log10(z) 

Parameters x : a number or an array (must not be


3.3.3 wradlib.trafo.idecibel 

wradlib.trafo.idecibel(x) 

Calculates the inverse of input decibel values 10.**(x/10.) 

Parameters x : a number or an array 

3.3.4 wradlib.trafo.r2depth 

wradlib.trafo.r2depth(x, interval) 

Computes rainfall depth (mm) from rainfall intensity (mm/h) 

Parameters x : float or array of float 

rainfall intensity in mm/h 

interval : number 

time interval (s) the values of x represent 

Returns output : float or array of float 

rainfall depth (mm) 

3.4 Z-R Conversions 

Module zr takes care of transforming reflectivity into rainfall rates and vice versa 

z2r 

r2z 

z2rEnhanced 

Conversion from reflectivities to rain rates. 

Calculates reflectivity from rain rates using 

Calculates rainrates from radar reflectivities using the enhanced 

3.4.1 wradlib.zr.z2r 

wradlib.zr.z2r(z, a=200.0, b=1.6) 

Conversion from reflectivities to rain rates. 

Calculates rain rates from radar reflectivities using a power law Z/R relationship Z = a*R**b 

Parameters z : a float or an array of floats 

Corresponds to reflectivity Z in mm**6/m**3 

a, b : Parameters of the Z/R relationship 

Standard values according to Marshall-Palmer are a=200., b=1.6 The German Weather 

Service uses a=256 and b=1.42 instead of the Marshall-Palmer defaults. 

Returns output : a float or an array of floats 

rainfall intensity in mm/h 

3.4.2 wradlib.zr.r2z 

wradlib.zr.r2z(r, a=200.0, b=1.6) 

Calculates reflectivity from rain rates using a power law Z/R relationship Z = a*R**b 



Parameters r : a float or an array of floats 

Corresponds to rainfall intensity in mm/h 

a, b : Parameters of the Z/R relationship 

Standard values according to Marshall-Palmer are a=200., b=1.6 The German Weather 

Service uses a=256 and b=1.42 instead of the Marshall-Palmer defaults. 

Returns output : a float or an array of floats 

reflectivity in mm**6/m**3 

3.4.3 wradlib.zr.z2rEnhanced 

wradlib.zr.z2rEnhanced(z) 

Calculates rainrates from radar reflectivities using the enhanced three-part Z-R-relationship used by the DWD 

(as of 2009) 

To be used with polar representations so that one dimension is cyclical. i.e. z should be of shape (nazimuths, 

nbins) –> the first dimension is the cyclical one. For DWD DX-Data z’s shape is (360,128). 

Parameters z : a float or an array of floats 

Corresponds to reflectivity Z in mm**6/m**3 must be a 2-D array 

Returns r, si : r - array of shape z.shape - calculated rain rates 

si - array of shape z.shape - calculated shower index for control purposes. May be 

omitted in later versions 

3.5 Georeferencing 

polar2latlon 

polar2latlonalt 

polar2centroids 

polar2polyvert 

centroid2polyvert 

project 

create_projstr 

projected_bincoords_from_radarspecs 

Transforms polar coordinates (of a PPI) to latitude/longitude coordinates. 

Transforms polar coordinates to lat/lon/altitude coordinates. 

Computes the lat/lon centroids of the radar bins from the polar coordinates. 

Generate 2-D polygon vertices directly from polar coordinates. 

Calculates the 2-D Polygon vertices necessary to form a rectangular polygon ar 

Convert from latitude,longitude (based on WGS84) to coordinates in map proje 

Conveniently supports the construction of proj.4 projection strings 

Convenience function to compute projected bin coordinates directly from 

3.5.1 wradlib.georef.polar2latlon 

wradlib.georef.polar2latlon(r, az, sitecoords, re=6370040) 

Transforms polar coordinates (of a PPI) to latitude/longitude coordinates. 

This function assumes that the transformation from the polar radar coordinate system to the earth’s spherical 

coordinate system may be done in the same way as astronomical observations are transformed from the horizon’s 

coordinate system to the equatorial coordinate system. 

The conversion formulas used were taken from http://de.wikipedia.org/wiki/Nautisches_Dreieck [accessed 

2001-11-02] and are only valid as long as the radar’s elevation angle is small, as one main assumption of 

this method is, that the ‘zenith-star’-side of the nautic triangle can be described by the radar range divided by 

the earths radius. For lager elevation angles, this side would have to be reduced. 

3.5. Georeferencing 41


Parameters r : array 

array of ranges [m] 

az : array 

array of azimuth angles containing values between 0° and 360°. These are assumed to 

start with 0° pointing north and counted positive clockwise! 

sitecoords : a sequence of two floats 

the lat / lon coordinates of the radar location 

re : float 

earth’s radius [m] 

Returns lat, lon : tuple of arrays 

two arrays containing the spherical latitude and longitude coordinates 

Notes 

Be aware that the coordinates returned by this function are valid for a sphere. When using them in GIS make 

sure to distinguish that from the usually assumed WGS coordinate systems where the coordinates are based on 

a more complex ellipsoid. 

Examples 

A few standard directions (North, South, North, East, South, West) with different distances (amounting to 

roughly 1°) from a site located at 48°N 9°E 

>>> r = np.array([0., 0., 111., 111., 111., 111.,]) 

>>> az = np.array([0., 180., 0., 90., 180., 270.,]) 

>>> csite = (48.0, 9.0) 

>>> lat1, lon1= __pol2latlon(r, az, csite) 

>>> for x, y in zip(lat1, lon1): 

... print ’{0:6.2f}, {1:6.2f}’.format(x, y) 

48.00, 9.00 

48.00, 9.00 

49.00, 9.00 

47.99, 10.49 

47.00, 9.00 

47.99, 7.51 

The coordinates of the east and west directions won’t come to lie on the latitude of the site because doesn’t 

travel along the latitude circle but along a great circle. 

3.5.2 wradlib.georef.polar2latlonalt 

wradlib.georef.polar2latlonalt(r, az, elev, sitecoords, re=6370040.0) 

Transforms polar coordinates to lat/lon/altitude coordinates. 

Explicitely accounts for the beam’s elevation angle and for the altitude of the radar location. 

This is an alternative implementation based on VisAD code (see http://www.ssec.wisc.edu/visaddocs/javadoc/visad/bom/Radar3DCoordinateSystem.html#toReference%28float[][]%29 

and 

http://www.ssec.wisc.edu/~billh/visad.html ). 



VisAD code has been translated to Python from Java. 

Nomenclature tries to stick to VisAD code for the sake of comparibility, hwoever, names of arguments are the 

same as for polar2latlon... 


array of ranges [m] 

az : array 

array of azimuth angles containing values between 0° and 360°. These are assumed to 

start with 0° pointing north and counted positive clockwise! 

sitecoords : a sequence of three floats 

the lat / lon coordinates of the radar location and its altitude a.m.s.l. (in meters) if 

sitecoords is of length two, altitude is assumed to be zero 

re : float 

earth’s radius [m] 

Returns output : a tuple of three arrays (latitudes, longitudes, altitudes) 

3.5.3 wradlib.georef.polar2centroids 

wradlib.georef.polar2centroids(r=None, az=None, sitecoords=None, range_res=None) 

Computes the lat/lon centroids of the radar bins from the polar coordinates. 

Both azimuth and range arrays are assumed to be equidistant and to contain only unique values. The ranges are 

assumed to define the exterior boundaries of the range bins (thus they must be positive). The angles are assumed 

to describe the pointing direction fo the main beam lobe. 

For further information refer to the documentation of georef.polar2latlon. 

r [array] array of ranges [m]; r defines the exterior boundaries of the range bins! (not the centroids). Thus, 

values must be positive! 

az [array] array of azimuth angles containing values between 0° and 360°. The angles are assumed to describe 

the pointing direction fo the main beam lobe! The first angle can start at any values, but make sure the 

array is sorted continuously positively clockwise and the angles are equidistant. An angle if 0 degree is 

pointing north. 

sitecoords [a sequence of two floats] the lat / lon coordinates of the radar location 

range_res [float] range resolution of radar measurement [m] in case it cannot be derived from r (single entry in 

r-array) 

Returns output : tuple of 2 arrays which describe the bin centroids 

longitude and latitude 

Notes 

Azimuth angles of 360 deg are internally converted to 0 deg. 



3.5.4 wradlib.georef.polar2polyvert 

wradlib.georef.polar2polyvert(r, az, sitecoords) 

Generate 2-D polygon vertices directly from polar coordinates. 

This is an alternative to centroid2polyvert which does not use centroids, but generates the polygon vertices by 

simply connecting the corners of the radar bins. 

Both azimuth and range arrays are assumed to be equidistant and to contain only unique values. For further 

information refer to the documentation of polar2latlon. 


array of ranges [m]; r defines the exterior boundaries of the range bins! (not the centroids). 

Thus, values must be positive! 

az : array 

array of azimuth angles containing values between 0° and 360°. The angles are assumed 

to describe the pointing direction fo the main beam lobe! The first angle can start at 

any values, but make sure the array is sorted continuously positively clockwise and the 

angles are equidistant. An angle if 0 degree is pointing north. 

sitecoords : a sequence of two floats 

the lat / lon coordinates of the radar location 

Returns output : a 3-d array of polygon vertices in lon/lat 

with shape(num_vertices, num_vertex_nodes, 2). The last dimension carries the longitudes 

on the first position, the latitudes on the second (lon: output[:,:,0], lat: output[:,:,1] 

Examples 

>>> import numpy as pl 


>>> import matplotlib as mpl 

>>> # define the polar coordinates and the site coordinates in lat/lon 

>>> r = np.array([50., 100., 150., 200.]) 

>>> az = np.array([0., 45., 90., 135., 180., 225., 270., 315., 360.]) 

>>> sitecoords = (48.0, 9.0) 

>>> polygons = polar2polyvert(r, az, sitecoords) 

>>> # plot the resulting mesh 

>>> fig = pl.figure() 

>>> ax = fig.add_subplot(111) 

>>> polycoll = mpl.collections.PolyCollection(vertices,closed=True, facecolors=None) 

>>> ax.add_collection(polycoll, autolim=True) 

>>> pl.axis(’tight’) 

>>> pl.show() 

3.5.5 wradlib.georef.centroid2polyvert 

wradlib.georef.centroid2polyvert(centroid, delta) 

Calculates the 2-D Polygon vertices necessary to form a rectangular polygon around the centroid’s coordinates. 

The vertices order will be clockwise, as this is the convention used by ESRI’s shapefile format for a polygon. 

Parameters centroid : array_like 



list of 2-D coordinates of the center point of the rectangle 

delta : scalar or array 

symmetric distances of the vertices from the centroid in each direction. If delta is scalar, 

it is assumed to apply to both dimensions. 

Returns vertices : array 

an array with 5 vertices per centroid. 

Notes 

The function can currently only deal with 2-D data (If you come up with a higher dimensional version of 

‘clockwise’ you’re welcome to add it). The data is then assumed to be organized within the centroid array with 

the last dimension being the 2-D coordinates of each point. 

Examples 

>>> centroid2polyvert([0., 1.], [0.5, 1.5]) 

array([[-0.5, -0.5], 

[-0.5, 2.5], 

[ 0.5, 2.5], 

[ 0.5, -0.5], 

[-0.5, -0.5]]) 

>>> centroid2polyvert(np.arange(4).reshape((2,2)), 0.5) 

array([[[-0.5, 0.5], 

[-0.5, 1.5], 

[ 0.5, 1.5], 

[ 0.5, 0.5], 

[-0.5, 0.5]], 

[[ 1.5, 2.5], 

[ 1.5, 3.5], 

[ 2.5, 3.5], 

[ 2.5, 2.5], 

[ 1.5, 2.5]]]) 

3.5.6 wradlib.georef.project 

wradlib.georef.project(latc, lonc, projstr, inverse=False) 

Convert from latitude,longitude (based on WGS84) to coordinates in map projection 

This mainly serves as a convenience function to use proj.4 via pyproj. For proj.4 documentation visit 

http://proj.maptools.org. For pyproj documentation visit http://code.google.com/p/pyproj. 

See http://www.remotesensing.org/geotiff/proj_list for examples of key/value pairs defining different map projections. 

You can use wradlib.georef.create_projstr in order to create projection strings to be passed with argument projstr. 

However, the choice is still rather limited. Alternatively, you have to create or look up projection strings by 

yourself. 

See the Examples section for a quick start. 

Parameters latc : array of floats 



latitude coordinates based on WGS84 

lonc : array of floats 

longitude coordinates based on WGS84 

projstr : string 

proj.4 projection string. Can be conveniently created by using function 

wradlib.georef.create_projstr 

Returns output : a tuple of 2 arrays (x and y coordinates) 

Examples 

Gauss-Krueger Zone 2: “+proj=tmerc +lat_0=0 +lon_0=6 +k=1 +x_0=2500000 +y_0=0 +ellps=bessel 

+towgs84=598.1,73.7,418.2,0.202,0.045,-2.455,6.7 +units=m +no_defs” 

Gauss-Krueger Zone 3: “+proj=tmerc +lat_0=0 +lon_0=9 +k=1 +x_0=3500000 +y_0=0 +ellps=bessel 

+towgs84=598.1,73.7,418.2,0.202,0.045,-2.455,6.7 +units=m +no_defs” 

UTM Zone 51 on the Northern Hemishpere “+proj=utm +zone=51 +ellps=WGS84” 

UTM Zone 51 on the Southern Hemishpere “+proj=utm +zone=51 +ellps=WGS84 +south” 

>>> import wradlib.georef as georef 

>>> # This is Gauss-Krueger Zone 3 (aka DHDN 3 aka Germany Zone 3) 

>>> gk3 = create_projstr("gk", zone=3) 

>>> latc = [54.5, 55.5] 

>>> lonc = [9.5, 9.8] 

>>> gk3_x, gk3_y = georef.project(latc, lonc, gk3) 

3.5.7 wradlib.georef.create_projstr 

wradlib.georef.create_projstr(projname, **kwargs) 

Conveniently supports the construction of proj.4 projection strings 

Currently, the following projection names (argument projname) are supported: 

“aeqd”: Azimuthal Equidistant 

needs the following keyword arguments: lat_0 (latitude at projection center), lon_0 (longitude at projection 

center), x_0 (false Easting, also known as x-offset), y_0 (false Northing, also known as y-offset) 

“gk” : Gauss-Krueger (for Germany) 

only needs keyword argument zone (number of the Gauss-Krueger strip) 

“utm” : Universal Transmercator 

needs keyword arguments zone (integer) and optionally hemisphere (accepted values: “south”, “north”) see 

Wikipedia entry for UTM zones. 

“dwd-radolan” : RADOLAN Composite Coordinate System 

no additional arguments needed. 

Polar stereographic projection used by the German Weather Service (DWD) for all Radar composite products. 

See the final report on the RADOLAN project (available at http://www.dwd.de/RADOLAN) for details. 



Parameters projname : string (proj.4 projection acronym) 

kwargs : depends on projname - see above! 

Returns output : string (a proj.4 projection string) 

Examples 

>>> # Gauss-Krueger 2nd strip 

>>> print create_projstr("gk", zone=2) 

>>> # UTM zone 51 (northern hemisphere) 

>>> print create_projstr("utm", zone=51) 

>>> # UTM zone 51 (southern hemisphere) 

>>> print create_projstr("utm", zone=51, hemisphere="south") 

3.5.8 wradlib.georef.projected_bincoords_from_radarspecs 

wradlib.georef.projected_bincoords_from_radarspecs(r, az, sitecoords, projstr, 

range_res=None) 

Convenience function to compute projected bin coordinates directly from radar site coordinates and 

range/azimuth specs 


array of ranges [m]; r defines the exterior boundaries of the range bins! (not the centroids). 

Thus, values must be positive! 

az : array 

sitecoords : tuple 

array of azimuth angles containing values between 0° and 360°. The angles are assumed 

to describe the pointing direction fo the main beam lobe! The first angle can start at 

any values, but make sure the array is sorted continuously positively clockwise and the 

angles are equidistant. An angle if 0 degree is pointing north. 


proj.4 projection string 

range_res : float 

range resolution of radar measurement [m] in case it cannot be derived from r (single 

entry in r-array) 

3.6 Interpolation 

Interpolation allows to transfer data from one set of locations to another. This includes for example: 

• interpolating the data from a polar grid to a cartesian grid or irregular points 

• interpolating point observations to a grid or a set of irregular points 

• filling missing values, e.g. filling clutters 

Nearest 

Nearest-neighbour interpolation in N dimensions. 

Continued on next page 

3.6. Interpolation 47


Idw 

Linear 

interpolate 

interpolate_polar 

Table 3.6 – continued from previous page 

Inverse distance weighting interpolation in N dimensions. 

Interface to the scipy.interpolate.LinearNDInterpolator class. 

Convenience function to use the interpolation classes in an efficient way 

Convenience function to interpolate polar data 

3.6.1 wradlib.ipol.Nearest 

class wradlib.ipol.Nearest(src, trg) 

Nearest-neighbour interpolation in N dimensions. 

Parameters src : ndarray of floats, shape (npoints, ndims) 

Data point coordinates of the source points. 

trg : ndarray of floats, shape (npoints, ndims) 

Data point coordinates of the target points. 

Notes 

Uses scipy.spatial.cKDTree 

__call__(vals[, maxdist]) 

Evaluate interpolator for values given at the source points. 

wradlib.ipol.Nearest.__call__ 

Nearest.__call__(vals, maxdist=None) 


Parameters vals : ndarray of float, shape (numsourcepoints, ...) 

Values at the source points which to interpolate 

maxdist : the maximum distance up to which an interpolated values is 

assigned - if maxdist is exceeded, np.nan will be assigned If maxdist==None, values 

will be assigned everywhere 

Returns output : ndarray of float with shape (numtargetpoints,...) 

3.6.2 wradlib.ipol.Idw 

class wradlib.ipol.Idw(src, trg, nnearest=4, p=2.) 

Inverse distance weighting interpolation in N dimensions. 





nnearest : integer - max. number of neighbours to be considered 

p : float - inverse distance power used in 1/dist**p 



Notes 

Uses scipy.spatial.cKDTree 

__call__(vals) 


wradlib.ipol.Idw.__call__ 

Idw.__call__(vals) 




maxdist : the maximum distance up to which an interpolated values is 

assigned - if maxdist is exceeded, np.nan will be assigned If maxdist==None, values 

will be assigned everywhere 


3.6.3 wradlib.ipol.Linear 

class wradlib.ipol.Linear(src, trg) 

Interface to the scipy.interpolate.LinearNDInterpolator class. 

We provide this class in order to achieve a uniform interface for all Interpolator classes 





__call__(vals[, fill_value]) 


wradlib.ipol.Linear.__call__ 

Linear.__call__(vals, fill_value=nan) 




fill_value : float 

is needed if linear interpolation fails; defaults to np.nan 


3.6. Interpolation 49


3.6.4 wradlib.ipol.interpolate 

wradlib.ipol.interpolate(src, trg, vals, Interpolator, *args, **kwargs) 

Convenience function to use the interpolation classes in an efficient way 

ATTENTION: Works only for one- and two-dimensional vals arrays, yet. 

The interpolation classes in wradlib.ipol are computationally very efficient if they are applied on large multidimensional 

arrays of which the first dimension must be the locations’ dimension (1d or 2d coordinates) and the 

following dimensions can be anything (e.g. time or ensembles). This way, the weights need to be computed only 

once. However, this can only be done with success if all source values for the interpolation are valid numbers. 

If the source values contain let’s say np.nan types, the result of the interpolation will be np.nan in the vicinity 

of the corresponding points, too. Imagine that you have a time series of observations at points and in each time 

step one observation is missing. You would still like to efficiently apply the interpolation classes, but you will 

need to account for the resulting np.nan values in the interpolation output. 

In order to still allow for the efficient application, you have to take care of the remaining np.nan in your interpolation 

result. This is done by this convenience function. 

Alternatively, you have to make sure that your vals argument does not contain any np.nan values OR you have 

to post-process missing values in your interpolation result in another way. 





vals : ndarray of float, shape (numsourcepoints, ...) 


Interpolator : a class which inherits from IpolBase 

*args : arguments of Interpolator (see class documentation) 

**kwargs : keyword arguments of Interpolator (see class documentation) 

Examples 

>>> # test for 1 dimension in space and two value dimensions 

>>> src = np.arange(10)[:,None] 

>>> trg = np.linspace(0,20,40)[:,None] 

>>> vals = np.hstack((np.sin(src), 10.+np.sin(src))) 

>>> # here we introduce missing values only in the second dimension 

>>> vals[3:5,1] = np.nan 

>>> ipol_result = interpolate(src, trg, vals, Idw, nnearest=2) 

>>> # plot if you like 


>>> pl.plot(trg, ipol_result, ’b+’) 

>>> pl.plot(src, vals, ’ro’) 

>>> pl.show() 

3.6.5 wradlib.ipol.interpolate_polar 

wradlib.ipol.interpolate_polar(data, mask=None, Interpolator=) 

Convenience function to interpolate polar data 



Parameters data : 2d-array 

2 dimensional array (azimuth, ranges) of floats; 

if no mask is assigned explicitly polar data should be a masked array 

mask : array 

boolean array with pixels to be interpolated set to True; 

must have the same shape as data 

Interpolator : a class which inherits from IpolBase 

Returns filled_data : 2d-array 

array with interpolated values for the values set to True in the mask 

Examples 


>>> import wradlib as wrl 

>>> # creating a data array and mask some values 

>>> data = np.arange(12.).reshape(4,3) 

>>> masked_values = (data==2) | (data==9) 

>>> # interpolate the masked data based on ’’masked_values’’ 

>>> filled_a = wrl.ipol.interpolate_polar(data, mask = masked_values, Interpolator = wrl.ipol.Li 

>>> wrl.vis.polar_plot(filled_a) 

>>> # the same result can be achieved by using an masked array instead of an explicit mask 

>>> mdata = np.ma.array(data, mask = masked_values) 

>>> filled_b = wrl.ipol.interpolate_polar(mdata, Interpolator = wrl.ipol.Linear) 

>>> wrl.vis.polar_plot(filled_b) 

3.7 Data Quality 

This module will serve two purposes: 

1. provide routines to create simple radar data quality related fields. 

2. provide routines to decide which radar pixel to choose based on the competing information in different quality 

fields. 

Data is supposed to be stored in ‘aligned’ arrays. Aligned here means that all fields are structured such that in each 

field the data for a certain index is representative for the same physical target. 

Therefore no assumptions are made on the dimensions or shape of the input fields except that they exhibit the numpy 

ndarray interface. 

beam_height_ft 

beam_height_ft_doviak 

pulse_volume 

Calculates the height of a radar beam above the antenna according to 

Calculates the height of a radar beam above the antenna according to the 4/3 (four-thirds -> ft) effec 

Calculates the sampling volume of the radar beam per bin depending on range and aperture. 

3.7.1 wradlib.qual.beam_height_ft 

wradlib.qual.beam_height_ft(ranges, elevations, degrees=True, re=6371000) 

Calculates the height of a radar beam above the antenna according to the 4/3 (four-thirds -> ft) effective Earth 

3.7. Data Quality 51


radius model. The formula was taken from [Collier1996]. 

Parameters ranges : array 

the distances of each bin from the radar [m] 

elevations : array 

the elevation angles of each bin from the radar [degrees or radians] 

degrees : bool 

if True (the default) elevation angles are given in degrees and will be converted to radians 

before calculation. If False no transformation will be done and elevations has to be 

given in radians. 

re : float 

earth radius [m] 

Returns output : height of the beam [m] 

Notes 

The shape of elevations and ranges may differ in which case numpy’s broadcasting rules will apply and the 

shape of output will be that of the broadcast arrays. See the numpy documentation on how broadcasting works. 

References 

[Collier1996] 

3.7.2 wradlib.qual.beam_height_ft_doviak 

wradlib.qual.beam_height_ft_doviak(ranges, elevations, degrees=True, re=6371000) 

Calculates the height of a radar beam above the antenna according to the 4/3 (four-thirds -> ft) effective Earth 

radius model. The formula was taken from [Doviak1993]. 



elevations : array 

the elevation angles of each bin from the radar [degrees or radians] 

degrees : bool 

if True (the default) elevation angles are assumed to be given in degrees and will be 

converted to radians before calculation. If False no transformation will be done and 

elevations has to be given in radians. 

re : float 

earth radius [m] 

Returns output : height of the beam [m] 



Notes 

The shape of elevations and ranges may differ in which case numpy’s broadcasting rules will apply and the 

shape of output will be that of the broadcast arrays. See the numpy documentation on how broadcasting works. 

References 

[Doviak1993] 

3.7.3 wradlib.qual.pulse_volume 

wradlib.qual.pulse_volume(ranges, h, theta) 

Calculates the sampling volume of the radar beam per bin depending on range and aperture. 

We assume a cone frustum which has the volume V=(pi/3)*h*(R**2 + R*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(theta*pi/180)*range. Thus, the pulse volume simpy becomes a the volume of a cylinder with V=pi * h 

* range**2 * tan(theta*pi/180)**2 


h : float 


pulse width (which corresponds to the range resolution [m]) 

theta : float 

the aperture angle (beam width) of the radar beam [degree] 

Returns output : volume of radar bins at each range in ranges [m**3] 

3.8 Composition 

Combine data from different radar locations on one common set of locations 

extract_circle 

togrid 

compose_ko 

compose_weighted 

Extract the indices of coords which fall within a circle 

Interpolate data from a radar location to the composite grid or set of locations 

Composes grids according to quality information using quality information as a knockout criterion. 

Composes grids according to quality information using a weighted averaging approach. 

3.8.1 wradlib.comp.extract_circle 

wradlib.comp.extract_circle(center, radius, coords) 

Extract the indices of coords which fall within a circle defined by center and radius 

Parameters center : float 

radius : float 

coords : array of float with shape (numpoints,2) 

Returns output : 1-darray of integers 

3.8. Composition 53


index array referring to the coords array 

3.8.2 wradlib.comp.togrid 

wradlib.comp.togrid(src, trg, radius, center, data, interpol, *args, **kwargs) 

Interpolate data from a radar location to the composite grid or set of locations 

Parameters src : ndarray of float of shape (numpoints, ndim) 

cartesian x / y coordinates of the radar bins 

trg : ndarray of float of shape (numpoints, ndim) 

cartesian x / y coordinates of the composite 

radius : float 

the radius of the radar circle (same units as src and trg) 

center : array of float 

the location coordinates of the radar 

data : ndarray of float 

the data that should be transferred to composite 

interpol : an interpolation class name from wradlib.ipol - e.g. Nearest or 

Idw 

Returns output : ndarray of float 

data of the radar circle which is interpolated on the composite grid 

3.8.3 wradlib.comp.compose_ko 

wradlib.comp.compose_ko(radargrids, qualitygrids) 

Composes grids according to quality information using quality information as a knockout criterion. 

The value of the composed pixel is taken from the radargrid whose quality grid has the highest value. 

Parameters radargrids : list of arrays 

radar data to be composited. Each item in the list corresponds to the data of one radar 

location. All items must have the same shape. 

qualitygrids : list of arrays 

quality data to decide upon which radar site will contribute its pixel to the composite. 

Then length of this list must be the same as that of radargrids. All items must have the 

same shape and be aligned with the items in radargrids. 

Returns composite : array 

3.8.4 wradlib.comp.compose_weighted 

wradlib.comp.compose_weighted(radargrids, qualitygrids) 

Composes grids according to quality information using a weighted averaging approach. 

The value of the composed pixel is the weighted average of all radar pixels with the quality values being the 

weights. 



Parameters radargrids : list of arrays 

qualitygrids : list of arrays 

Returns composite : array 

See Also: 

compose_ko for more description about the shape of the input arrays 

3.9 Clutter Identification 

filter_gabella Clutter identification filter developed by Gabella [Gabella2002] . 

filter_gabella_a First part of the Gabella filter looking for large reflectivity 

filter_gabella_b Second part of the Gabella filter comparing area to circumference of 

histo_cut 

Histogram based clutter identification. 

3.9.1 wradlib.clutter.filter_gabella 

wradlib.clutter.filter_gabella(img, wsize=5, thrsnorain=0.0, tr1=6.0, n_p=8, tr2=1.3) 

Clutter identification filter developed by Gabella [Gabella2002] . 

This is a two-part identification algorithm using echo continuity and minimum echo area to distinguish between 

meteorological (rain) and non- meteorological echos (ground clutter etc.) 

See Also: 

Parameters img : array_like 

wsize : int 

thrsnorain : float 

tr1 : float 

n_p : int 

thr2 : float 

Returns output : array 

boolean array with pixels identified as clutter set to True. 

filter_gabella_a the first part of the filter 

filter_gabella_b the second part of the filter 

References 

[Gabella2002] 

Examples 

TODO: provide a correct example here 

3.9. Clutter Identification 55


>>> a=[1,2,3] 

>>> print [x + 3 for x in a] 

[4, 5, 6] 

>>> print "a\n\nb" 

a 

b 

3.9.2 wradlib.clutter.filter_gabella_a 

wradlib.clutter.filter_gabella_a(img, wsize, tr1) 

First part of the Gabella filter looking for large reflectivity gradients. 

This function checks for each pixel in img how many pixels surrounding it in a window of wsize are by tr1 

smaller than the central pixel. 

See Also: 


radar image to which the filter is to be applied 

wsize : int 

Size of the window surrounding the central pixel TODO check if a 5x5 window would 

have wsize=2 or wsize=5 

tr1 : float 

Threshold value 

Returns output : array_like 

an array with the same shape as img, containing the filter’s results. 

filter_gabella_b the second part of the filter 

filter_gabella the complete filter 

Examples 


>>> a=[1,2,3] 


[4, 5, 6] 


a 

b 

3.9.3 wradlib.clutter.filter_gabella_b 

wradlib.clutter.filter_gabella_b(img, thrs=0.0) 

Second part of the Gabella filter comparing area to circumference of contiguous echo regions. 


thrs : float 

Threshold below which the field values will be considered as no rain 



See Also: 

Returns output : array_like 

contains in each pixel the ratio between area and circumference of the meteorological 

echo it is assigned to or 0 for non precipitation pixels. 

filter_gabella_a the first part of the filter 

filter_gabella the complete filter 

Examples 


>>> a=[1,2,3] 


[4, 5, 6] 


a 

b 

3.9.4 wradlib.clutter.histo_cut 

wradlib.clutter.histo_cut(prec_accum) 

Histogram based clutter identification. 

This identification algorithm uses the histogram of temporal accumulated rainfall. It iteratively detects classes 

whose frequency falls below a specified percentage (1% by default) of the frequency of the class with the 

biggest frequency and remove the values from the dataset until the changes from iteration to iteration falls 

below a threshold. This algorithm is able to detect static clutter as well as shadings. It is suggested to choose 

a representative time periode for the input precipitation accumulation. The recommended time period should 

cover one year. 

Parameters prec_accum : array_like 

spatial array containing rain accumulation 

Returns output : array 

boolean array with pixels identified as clutter/shadings set to True. 

3.10 Filling Missing Values 

3.11 Vertical Profile of Reflectivity (VPR) 

UNDER DEVELOPMENT 

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), the one sweep samples from different heights. The effects of the non-uniform VPR and the differnt 

sampling heights need to be accounted for if we are interested in the precipiation near the ground or in defined heights. 

This module is intended to provide a set of tools to account for these effects. 

3.10. Filling Missing Values 57


cappi 

UNDER DEVELOPMENT: Create a CAPPI from sweep data with multiple elevation angles 

3.11.1 wradlib.vpr.cappi 

wradlib.vpr.cappi(data, sitecoords, elevs, levels, dx, dy, maxvert, maxhoriz, projstr) 

UNDER DEVELOPMENT: Create a CAPPI from sweep data with multiple elevation angles 

Parameters data : float ndarray with shape (num elevations, num azimuth angles, num range bins) 

sitecoords : sequence of three floats indicating the radar position 

(latitude in decimal degrees, longitude in decimal degrees, height a.s.l. in meters) 

elevs : sequence of elevation angles corresponding to first dimension of data 

levels : sequence of floats 

target altitudes for CAPPI (in meters) 

dx : float 

horizontal resolution of CAPPI in x direction 

dy : float 

horizontal resolution of CAPPI in y direction 

maxvert : float 

maximum vertical distance threshold - the next data bin must be closer to the target 

location than maxvert in order to assign a value 

maxhoriz : float 

maximum horizontal distance threshold - the next data bin must be closer to the target 

location than maxhoriz in order to assign a value 

projstr : proj.4 projection string 

Returns output : float ndarray of shape (number of levels, number of x coordinates, number of y 

coordinates) 

3.12 Attenuation Correction 

correctAttenuationHB 

correctAttenuationKraemer 

correctAttenuationHJ 

correctAttenuationConstrained 

constraint_dBZ 

constraint_PIA 

Gate-by-Gate attenuation correction according to Hitschfeld & Bordan 

Gate-by-Gate attenuation correction according to Stefan Kraemer 

Gate-by-Gate attenuation correction based on Stefan Kraemer 

Gate-by-Gate attenuation correction based on the iterative approach of 

Constraint callback function for correctAttenuationConstrained. 

Constraint callback function for correctAttenuationConstrained. 

3.12.1 wradlib.atten.correctAttenuationHB 

wradlib.atten.correctAttenuationHB(gateset, coefficients={‘a’: 0.000167, ‘b’: 0.7, ‘l’: 1.0}, 

mode=’‘, thrs=59.0) 

Gate-by-Gate attenuation correction according to Hitschfeld & Bordan [Hitschfeld1954] 



Parameters gateset : array 

multidimensional array. The range gates (over which iteration has to be performed) are 

supposed to vary along the last dimension so, e.g., for a set of l radar images stored 

in polar form with m azimuths and n range-bins the input array’s shape can be either 

(l,m,n) or (m,l,n) data has to be provided in decibel representation of reflectivity [dBZ] 

a : float 

b : float 

l : float 

proportionality factor of the k-Z relation ( k = a ∗ Z b ). Per default set to 1.67e-4. 

exponent of the k-Z relation ( k = a ∗ Z b ). Per default set to 0.7. 

length of a range gate [km]. Per default set to 1.0. 

mode : string 

controls how the function reacts, if the sum of signal and attenuation exceeds the threshold 

thrs Possible values: ‘warn’ : emit a warning through the module’s logger but 

continue execution ‘zero’ : set offending gates to 0.0 ‘nan’ : set offending gates to nan 

Any other mode and default setting will raise an Exception. 

thrs : float 

threshold, for the sum of attenuation and signal, which is deemed unplausible. 

Returns pia : array 

Array with the same shape as gateset containing the calculated attenuation [dB] for 

each range gate. 

Raises AttenuationOverflowError : 

Exception, if attenuation exceeds thrs and no handling mode is set. 

References 

[Hitschfeld1954] 

3.12.2 wradlib.atten.correctAttenuationKraemer 

wradlib.atten.correctAttenuationKraemer(gateset, a_max=0.000167, a_min=2.33e- 

05, b=0.7, n=30, l=1.0, mode=’zero’, 

thrs_dBZ=59.0) 

Gate-by-Gate attenuation correction according to Stefan Kraemer [Kraemer2008]. 


Multidimensional array, where the range gates (over which iteration has to be performed) 

are supposed to vary along the last dimension so, e.g., for a set of l radar 

images stored in polar form with m azimuths and n range-bins the input array’s shape 

can be either (l,m,n) or (m,l,n). 

Data has to be provided in decibel representation of reflectivity [dBZ]. 

a_max : float 

3.12. Attenuation Correction 59


initial value for linear coefficient of the k-Z relation ( k = a ∗ Z b ). Per default set to 

1.67e-4. 

a_min : float 

minimal allowed linear coefficient of the k-Z relation ( k = a ∗ Z b ) in the downwards 

iteration of a in case of signal overflow (sum of signal and attenuation exceeds the 

threshold thrs). Per default set to 2.33e-5. 

b : float 


n : integer 

l : float 

number of iterations from a_max to a_min. Per default set to 30. 


mode : string 

Controls how the function reacts in case of signal overflow (sum of signal and attenuation 

exceeds the threshold thrs). Possible values: 

‘warn’ : emit a warning through the module’s logger but continue execution 

‘zero’ : set offending gates to 0.0 

‘nan’ : set offending gates to nan 

Per default set to ‘zero’. Any other mode will raise an Exception. 

thrs_dBZ : float 

Threshold, for the attenuation corrected signal [dBZ], which is deemed unplausible. Per 

default set to 59.0 dBZ. 





Exception, if attenuation exceeds thrs even with smallest possible linear coefficient 

(a_min) and no handling mode is set. 

References 

[Kraemer2008] 

3.12.3 wradlib.atten.correctAttenuationHJ 

wradlib.atten.correctAttenuationHJ(gateset, a_max=0.000167, a_min=2.33e-05, b=0.7, n=30, 

l=1.0, mode=’zero’, thrs_dBZ=59.0, max_PIA=20.0) 

Gate-by-Gate attenuation correction based on Stefan Kraemer [Kraemer2008], expanded by Stephan Jacobi, 

Maik Heistermann and Thomas Pfaff [Jacobi2011]. 









a_max : float 


1.67e-4. 

a_min : float 




b : float 


n : integer 

l : float 



mode : string 







thrs_dBZ : float 

Threshold, for the attenuation corrected signal [dBZ], which is deemed unplausible. Per 

default set to 59.0 dBZ. 

max_PIA : float 

threshold, for the maximum path integrated attenuation [dB] which allows reasonable 

attenuation corrections. Per default set to 20.0 dB. 



each range gate. In case the input array (gateset) contains NaNs the corresponding 

beams of the output array (k) will be set as NaN, too. 


Exception, if attenuation exceeds thrs even with smallest possible linear coefficient 




References 

[Jacobi2011] 

3.12.4 wradlib.atten.correctAttenuationConstrained 

wradlib.atten.correctAttenuationConstrained(gateset, a_max=0.000167, a_min=2.33e-05, 

b_max=0.7, b_min=0.2, na=30, nb=5, 

l=1.0, mode=’error’, constraints=None, 

constr_args=None, diagnostics={}) 

Gate-by-Gate attenuation correction based on the iterative approach of Stefan Kraemer [Kraemer2008] with a 

generalized and arbitrary number of constraints. 







a_max : float 


1.67e-4. 

a_min : float 




b : float 


n : integer 

l : float 



mode : string 







constraints : list 

list of constraint functions. The signature of these functions has to be constraint_function(gateset, 

k, *‘constr_args‘). Their return value must be a boolean array 

of shape gateset.shape[:-1] set to True for beams, which do not fulfill the constraint. 



constr_args : list 

list of lists, which are to be passed to the individual constraint functions using the *args 

mechanism (len(constr_args) == len(constraints)) 

diagnostics : dictionary 

dictionary of variables, which are usually not returned by the function but may be of 

interest for research or during testing. Defaults to {}, in which case no diagnostics are 

generated. If a dictionary with certain keys is passed to the function, the respective 

diagnostics are generated. Currently implemented diagnostics: 

• ‘a’ - returns the values of the a coefficient of the k-Z relation, which was used to 

calculate the attenuation for the respective beam as a np.array. The shape of the 

returned array will be gateset.shape[:-1]. 

Returns k : array 




Exception, if not all constraints are satisfied even with the smallest possible linear coefficient 


Examples 

>>> # Implementing the original Hitschfeld & Bordan (1954) algorithm with 

>>> # otherwise default parameters 

>>> k = correctAttenuationConstrained(gateset, n=1, mode=’nan’) 

>>> # Implementing the basic Kraemer algorithm 

>>> k = correctAttenuationConstrained(gateset, 

... mode=’nan’, 

... constraints=[constraint_dBZ], 

... constr_args=[[59.0]]) 

>>> # Implementing the PIA algorithm by Jacobi et al. 

>>> k = correctAttenuationConstrained(gateset, 

... mode=’nan’, 

... constraints=[constraint_dBZ, 

... constraint_PIA], 

... constr_args=[[59.0], 

... [20.0]]) 

3.12.5 wradlib.atten.constraint_dBZ 

wradlib.atten.constraint_dBZ(gateset, k, thrs_dBZ) 

Constraint callback function for correctAttenuationConstrained. Selects beams, in which at least one pixel 

exceeds thrs_dBZ [dBZ]. 

3.12.6 wradlib.atten.constraint_PIA 

wradlib.atten.constraint_PIA(gateset, k, thrs_PIA) 

Constraint callback function for correctAttenuationConstrained. Selects beams, in which the path integrated 

attenuation exceeds thrs_PIA. 



3.13 Gage adjustment 

3.13.1 Concept 

The objective of this module is the adjustment of radar-based rainfall estimates by rain gage observations. However, 

this module could also be applied to adjust satellite rainfall by rain gage observations, remotely sensed soil moisture 

patterns by ground truthing moisture sensors, or any dense spatial point pattern which could be adjusted by sparse 

point measurements (ground truth). 

Basically, we only need two data sources: 

• point observations (e.g. rain gage observations) 

• set of (potentially irregular) unadjusted point values (e.g. remotely sensed rainfall) 

[GoudenhooftdandDelobbe2009] provide an excellent overview of adjustment procedures. The general idea is that 

we quantify the error of the remotely sensed rainfall at the rain gage locations, assuming the rain gage observation 

to be accurate. The error can be assumed to be purely additive (AdjustAdd), purely multiplicative (AdjustMultiply, 

AdjustMFB) or a mixture of both (AdjustMixed). If the error is assumed to heterogeneous in space (AdjustAdd, 

AdjustMultiply, AdjustMixed), the error at the rain gage locations is interpolated to the radar bin locations and then 

used to adjust (correct) the raw radar rainfall estimates. In case of the AdjustMFB approach, though, the multiplicative 

error is assumed to be homogenoues in space. 

3.13.2 Quick start 

The basic procedure consists of creating an adjustment object from the class you want to use for adjustment. After 

that, you can call the object with the actual data that is to be adjusted. The following example is using the additive 

error model with default settings. obs_coords and raw_coords represent arrays with coordinate pairs for the 

gage observations and the radar bins, respectively. obs and raw are arrays containing the actual data. 

>>> adjuster = AdjustAdd(obs_coords, raw_coords) 

>>> adjusted = adjuster(obs, raw) 

The user can specify the approach that should be used to interpolate the error in space, as well as the keyword arguments 

which control the behaviour of the interpolation approach. For this purpose, all interpolation classes from the 

wradlib.ipol module are available and can be passed by using the Ipclass argument. The default interpolation class 

is Inverse Distance Weighting (wradlib.ipol.Idw). If you want to use e.g. linear barycentric interpolation: 

>>> import wradlib.ipol as ipol 

>>> adjuster = AdjustAdd(obs_coords, raw_coords, Ipclass=ipol.Linear) 

>>> adjusted = adjuster(obs, raw) 

3.13.3 Cross validation 

Another helpful feature is an easy-to-use method for leave-one-out cross-validation. Cross validation is a standard 

procedure for verifying rain gage adjustment or interpolation procedures. You can start the cross validation in the 

same way as you start the actual adjustment, however, you call the xvalidate method instead. The result of the 

cross validation are pairs of observation and the corresponding adjustment result at the observation location. Using 

the wradlib.verify module, you can compute error metrics for the cross validation results. 

>>> adjuster = AdjustAdd(obs_coords, raw_coords) 

>>> observed, estimated = adjuster.xvalidate(obs, raw) 

>>> from wradlib.verify import ErrorMetrics 

>>> metrics = ErrorMetrics(observed, estimated) 

>>> metrics.report() 



AdjustBase 

AdjustMFB 

AdjustMultiply 

AdjustAdd 

AdjustMixed 

Raw_at_obs 

The basic adjustment class that inherits to all other classes 

Multiplicative gage adjustment using one correction factor for the entire domain 

Gage adjustment using a multiplicative error model 

Gage adjustment using an additive error model. 

Gage adjustment using a mixed error model (additive and multiplicative). 

Get the raw values in the neighbourhood of the observation points 

wradlib.adjust.AdjustBase 

class wradlib.adjust.AdjustBase(obs_coords, raw_coords, nnear_raws=9, stat=’median’, mingages=5, 

minval=0.0, Ipclass=, **ipargs) 

The basic adjustment class that inherits to all other classes 

All methods except the __call__ method are inherited to the following adjustment classes. 

Parameters obs_coords : array of float 

coordinate pairs of observations points 

raw_coords : array of float 

coordinate pairs of raw (unadjusted) field 

nnear_raws : integer 

defaults to 9 

stat : string 

defaults to ‘median’ 

mingages : integer 

minimum number of gages which are required for an adjustment 

minval : float 

If the gage or radar observation is below this threshold, the location will not be used for 

adjustment. For additive adjustment, this value should be set to zero (default value). 

Ipclass : an interpolation class from wradib.ipol 

Default value is wradlib.ipol.Idw (Inverse Distance Weighting) 

ipargs : keyword arguments to create an instance of Ipclass 

For wradlib.ipol.Idw, these keywird arguments woudl e.g. be nnear or p 

Methods 

xvalidate(obs, raw) 

Leave-One-Out Cross Validation, applicable to all gage adjustment classes. 

wradlib.adjust.AdjustBase.xvalidate 

AdjustBase.xvalidate(obs, raw) 


This method will be inherited to other Adjust classes. 

It should thus be applicable to all adjustment 

3.13. Gage adjustment 65


procedures without any modification. This way, the actual adjustment procedure has only to be defined 

once in the __call__ method. 

The output of this method can be evaluated by using the verify.ErrorMetrics class. 

Parameters obs : array of floats 

raw : array of floats 

Returns obs : array of floats 

valid observations at those locations which have a valid radar observation 

estatobs : array of floats 

estimated values at the valid observation locations 

__call__(obs, raw[, targets]) 


Empty prototype 


wradlib.adjust.AdjustBase.__call__ 

AdjustBase.__call__(obs, raw, targets=None) 

Empty prototype 

wradlib.adjust.AdjustBase.xvalidate 

AdjustBase.xvalidate(obs, raw) 


This method will be inherited to other Adjust classes. It should thus be applicable to all adjustment procedures 

without any modification. This way, the actual adjustment procedure has only to be defined once in the __call__ 

method. 








wradlib.adjust.AdjustMFB 

class wradlib.adjust.AdjustMFB(obs_coords, raw_coords, nnear_raws=9, stat=’median’, mingages=5, 


Multiplicative gage adjustment using one correction factor for the entire domain 

This method is also known as the Mean Field Bias correction 








defaults to 9 

stat : string 











Returns output : array of adjusted radar values 

Notes 

Inherits from AdjustBase 

Examples 

>>> import wradlib.adjust as adjust 



>>> # 1-d example including all available adjustment methods 

>>> # -------------------------------------------------------------------------- 

>>> # gage and radar coordinates 



>>> # true rainfall 

>>> truth = np.abs(np.sin(0.1*radar_coords)) 

>>> # radar error 

>>> erroradd = np.random.uniform(0,0.5,len(radar_coords)) 

>>> errormult= 1.1 

>>> # radar observation 

>>> radar = errormult*truth + erroradd 

>>> # gage observations are assumed to be perfect 


>>> # add a missing value to observations (just for testing) 

>>> obs[1] = np.nan 

>>> # adjust the radar observation by additive model 

>>> add_adjuster = adjust.AdjustAdd(obs_coords, radar_coords, nnear_raws=1) 

>>> add_adjusted = add_adjuster(obs, radar) 

>>> # adjust the radar observation by multiplicative model 

>>> mult_adjuster = adjust.AdjustMultiply(obs_coords, radar_coords, nnear_raws=1) 



>>> mult_adjusted = mult_adjuster(obs, radar,0.) 

>>> # adjust the radar observation by MFB 

>>> mfb_adjuster = adjust.AdjustMFB(obs_coords, radar_coords, nnear_raws=1) 

>>> mfb_adjusted = mfb_adjuster(obs, radar,0.) 

>>> # adjust the radar observation by AdjustMixed 

>>> mixed_adjuster = adjust.AdjustMixed(obs_coords, radar_coords, nnear_raws=1) 

>>> mixed_adjusted = mixed_adjuster(obs, radar) 

>>> line1 = pl.plot(radar_coords, radar, ’k-’, label="raw radar") 

>>> line2 = pl.plot(obs_coords, obs, ’ro’, label="gage obs") 

>>> line3 = pl.plot(radar_coords, add_adjusted, ’-’, color="red", label="adjusted by AdjustAdd") 

>>> line4 = pl.plot(radar_coords, mult_adjusted, ’-’, color="green", label="adjusted by AdjustMu 

>>> line5 = pl.plot(radar_coords, mfb_adjusted, ’-’, color="orange", label="adjusted by AdjustMF 

>>> line6 = pl.plot(radar_coords, mixed_adjusted, ’-’, color="blue", label="adjusted by AdjustMi 


>>> pl.show() 

Methods 



wradlib.adjust.AdjustMFB.xvalidate 

AdjustMFB.xvalidate(obs, raw) 


This method will be inherited to other Adjust classes. It should thus be applicable to all adjustment 










__call__(obs, raw[, targets, rawatobs, ix]) 


Return the field of raw values adjusted by obs. 


wradlib.adjust.AdjustMFB.__call__ 

AdjustMFB.__call__(obs, raw, targets=None, rawatobs=None, ix=None) 



Gage observations 




Raw unadjusted radar rainfall 

targets : (INTERNAL) array of floats 

Coordinate pairs for locations on which the final adjustment product is interpolated Defaults 

to None. In this case, the output locations will be identical to the radar coordinates 

rawatobs : (INTERNAL) array of floats 

For internal use from AdjustBase.xvalidate only (defaults to None) 

ix : (INTERNAL) array of integers 


wradlib.adjust.AdjustMFB.xvalidate 

AdjustMFB.xvalidate(obs, raw) 




method. 








wradlib.adjust.AdjustMultiply 

class wradlib.adjust.AdjustMultiply(obs_coords, raw_coords, nnear_raws=9, stat=’median’, 

mingages=5, minval=0.0, Ipclass=, **ipargs) 

Gage adjustment using a multiplicative error model 

First, an instance of AdjustMultiply has to be created. Calling this instance then does the actual adjustment. 

The motivation behind this performance. In case the observation points are always the same for different time 

steps, the computation of neighbours and invserse distance weights only needs to be performed once during 

initialisation. 

AdjustMultiply automatically takes care of invalid gage or radar observations (e.g. NaN, Inf or other typical 

missing data flags such as -9999. However, in case e.g. the observation data contain missing values, the computation 

of the inverse distance weights needs to be repeated in __call__ which is at the expense of performance. 








defaults to 9 

stat : string 












Notes 


Examples 





>>> # -------------------------------------------------------------------------- 




































>>> pl.show() 

Methods 



wradlib.adjust.AdjustMultiply.xvalidate 

AdjustMultiply.xvalidate(obs, raw) 
















wradlib.adjust.AdjustMultiply.__call__ 

AdjustMultiply.__call__(obs, raw, targets=None, rawatobs=None, ix=None) 















wradlib.adjust.AdjustMultiply.xvalidate 

AdjustMultiply.xvalidate(obs, raw) 




method. 








wradlib.adjust.AdjustAdd 

class wradlib.adjust.AdjustAdd(obs_coords, raw_coords, nnear_raws=9, stat=’median’, mingages=5, 


Gage adjustment using an additive error model. 

First, an instance of AdjustAdd has to be created. Calling this instance then does the actual adjustment. The 

motivation behind this performance. In case the observation points are always the same for different time steps, 

the computation of neighbours and invserse distance weights only needs to be performed once. 

AdjustAdd automatically takes care of invalid gage or radar observations (e.g. NaN, Inf or other typical missing 

data flags such as -9999. However, in case e.g. the observation data contain missing values, the computation of 

the inverse distance weights needs to be repeated in __call__ which is at the expense of performance. 






defaults to 9 

stat : string 














Notes 


Examples 





>>> # -------------------------------------------------------------------------- 




































>>> pl.show() 

Methods 



wradlib.adjust.AdjustAdd.xvalidate 

AdjustAdd.xvalidate(obs, raw) 
















wradlib.adjust.AdjustAdd.__call__ 

AdjustAdd.__call__(obs, raw, targets=None, rawatobs=None, ix=None) 















wradlib.adjust.AdjustAdd.xvalidate 

AdjustAdd.xvalidate(obs, raw) 




method. 








wradlib.adjust.AdjustMixed 

class wradlib.adjust.AdjustMixed(obs_coords, raw_coords, nnear_raws=9, stat=’median’, mingages=5, 


Gage adjustment using a mixed error model (additive and multiplicative). 

The mixed error model assumes that you have both a multiplicative and an additive error term. The intention 

is to overcome the drawbacks of the purely additive and multiplicative approaches (see AdjustAdd and Adjust- 

Multiply). The formal reprentation of the error model according to [Pfaff2010] is: 

R(gage) = R(radar) * (1+delta) + epsilon 

delta and epsilon have to be assumed to be independent and normally distributed. The present implementation is 

based on a Least Squares estimation of delta and epsilon for each rain gage location. delta and epsilon are then 

interpolated and used to correct the radar rainfall field. The least squares implementation uses the equation for 

the error model plus the condition to minimize (delta**2 + epsilon**2) for each gage location. The idea behind 

this is that epsilon dominates the adjustment for small deviations between radar and gage while delta dominates 

in case of large deviations. 

Usage: First, an instance of AdjustMMixed has to be created. Calling this instance then does the actual adjustment. 

The motivation behind this is performance. In case the observation points are always the same for 

different time steps, the computation of neighbours and invserse distance weights only needs to be performed 

once during initialisation. 

AdjustMixed automatically takes care of invalid gage or radar observations (e.g. NaN, Inf or other typical missing 

data flags such as -9999. However, in case e.g. the observation data contain missing values, the computation 

of the inverse distance weights needs to be repeated in __call__ which is at the expense of performance. 








defaults to 9 

stat : string 












Notes 


References 

[Pfaff2010] 

Examples 





>>> # -------------------------------------------------------------------------- 




































>>> pl.show() 

Methods 



wradlib.adjust.AdjustMixed.xvalidate 

AdjustMixed.xvalidate(obs, raw) 


















wradlib.adjust.AdjustMixed.__call__ 

AdjustMixed.__call__(obs, raw, targets=None, rawatobs=None, ix=None) 













wradlib.adjust.AdjustMixed.xvalidate 

AdjustMixed.xvalidate(obs, raw) 




method. 








wradlib.adjust.Raw_at_obs 

class wradlib.adjust.Raw_at_obs(obs_coords, raw_coords, nnear=9, stat=’median’) 

Get the raw values in the neighbourhood of the observation points 





nnear: integer : 



number of neighbours which should be considered in the vicinity of each point in obs 

stat: string : 

function name 

__call__(raw[, obs]) 

Returns the values of raw at the observation locations 

wradlib.adjust.Raw_at_obs.__call__ 

Raw_at_obs.__call__(raw, obs=None) 

Returns the values of raw at the observation locations 

Parameters raw : array of float 

raw values 

3.13.4 References 

3.14 Verification 

Verification mainly refers to the comparison of radar-based precipitation estimates to ground truth. 

ErrorMetrics 

PolarNeighbours 

Compute quality metrics from a set of observations (obs) and estimates (est). 

For a set of projected point coordinates, extract the neighbouring bin values from a data set in polar coordina 

3.14.1 wradlib.verify.ErrorMetrics 

class wradlib.verify.ErrorMetrics(obs, est, minval=None) 

Compute quality metrics from a set of observations (obs) and estimates (est). 

First create an instance of the class using the set of observations and estimates. Then compute quality metrics 

using the class methods. A dictionary of all available quality metrics is returned using the all method. Method 

report pretty prints all these metrics over a scatter plot. 

Parameters obs: array of floats : 

observations (e.g. rain gage observations) 

est: array of floats : 

estimates (e.g. radar, adjusted radar, ...) 


threshold value in order to compute metrics only for values larger than minval 

Examples 

>>> obs = np.random.uniform(0,10,100) 

>>> est = np.random.uniform(0,10,100) 

>>> metrics = ErrorMetrics(obs,est) 

>>> metrics.all() 

>>> metrics.pprint() 

3.14. Verification 79


>>> metrics.plot() 

>>> metrics.report() 

Methods 

all() 

corr() 

mas() 

meanerr() 

mse() 

nash() 

plot([ax, unit, maxval]) 

pprint() 

r2() 

ratio() 

report([metrics, ax, unit, maxval]) 

rmse() 

spearman() 

sse() 

Returns a dictionary of all error metrics 

Correlation coefficient 

Mean Absolute Error 

Mean Error 

Mean Squared Error 

Nash-Sutcliffe Efficiency 

Scatter plot of estimates vs observations 

Pretty prints a summary of error metrics 

Coefficient of determination 

Mean ratio between observed and estimated 

Pretty prints selected error metrics over a scatter plot 

Root Mean Squared Error 

Spearman rank correlation coefficient 

Sum of Squared Errors 

wradlib.verify.ErrorMetrics.all 

ErrorMetrics.all() 


wradlib.verify.ErrorMetrics.corr 

ErrorMetrics.corr() 


wradlib.verify.ErrorMetrics.mas 

ErrorMetrics.mas() 


wradlib.verify.ErrorMetrics.meanerr 

ErrorMetrics.meanerr() 

Mean Error 

wradlib.verify.ErrorMetrics.mse 

ErrorMetrics.mse() 




wradlib.verify.ErrorMetrics.nash 

ErrorMetrics.nash() 


wradlib.verify.ErrorMetrics.plot 

ErrorMetrics.plot(ax=None, unit=’‘, maxval=None) 


Parameters ax : a matplotlib axes object to plot on 

if None, a new axes object will be created 

unit : string 

measurement unit of the observations / estimates 

wradlib.verify.ErrorMetrics.pprint 

ErrorMetrics.pprint() 


wradlib.verify.ErrorMetrics.r2 

ErrorMetrics.r2() 


wradlib.verify.ErrorMetrics.ratio 

ErrorMetrics.ratio() 


wradlib.verify.ErrorMetrics.report 

ErrorMetrics.report(metrics=[’rmse’, ‘nash’, ‘meanerr’], ax=None, unit=’‘, maxval=None) 


Parameters metrics : sequence of strings 

names of the metrics which should be included in the report defaults to 

[”rmse”,”r2”,”meanerr”] 

ax : a matplotlib axes object to plot on 


unit : string 


wradlib.verify.ErrorMetrics.rmse 

ErrorMetrics.rmse() 




wradlib.verify.ErrorMetrics.spearman 

ErrorMetrics.spearman() 


wradlib.verify.ErrorMetrics.sse 

ErrorMetrics.sse() 


all() 

corr() 

mas() 

meanerr() 

mse() 

nash() 

plot([ax, unit, maxval]) 

pprint() 

r2() 

ratio() 

report([metrics, ax, unit, maxval]) 

rmse() 

spearman() 

sse() 




Mean Error 











wradlib.verify.ErrorMetrics.all 

ErrorMetrics.all() 


wradlib.verify.ErrorMetrics.corr 

ErrorMetrics.corr() 


wradlib.verify.ErrorMetrics.mas 

ErrorMetrics.mas() 


wradlib.verify.ErrorMetrics.meanerr 

ErrorMetrics.meanerr() 

Mean Error 

wradlib.verify.ErrorMetrics.mse 

ErrorMetrics.mse() 




wradlib.verify.ErrorMetrics.nash 

ErrorMetrics.nash() 


wradlib.verify.ErrorMetrics.plot 

ErrorMetrics.plot(ax=None, unit=’‘, maxval=None) 


Parameters ax : a matplotlib axes object to plot on 


unit : string 


wradlib.verify.ErrorMetrics.pprint 

ErrorMetrics.pprint() 


wradlib.verify.ErrorMetrics.r2 

ErrorMetrics.r2() 


wradlib.verify.ErrorMetrics.ratio 

ErrorMetrics.ratio() 


wradlib.verify.ErrorMetrics.report 

ErrorMetrics.report(metrics=[’rmse’, ‘nash’, ‘meanerr’], ax=None, unit=’‘, maxval=None) 


Parameters metrics : sequence of strings 

names of the metrics which should be included in the report defaults to 

[”rmse”,”r2”,”meanerr”] 

ax : a matplotlib axes object to plot on 


unit : string 


wradlib.verify.ErrorMetrics.rmse 

ErrorMetrics.rmse() 




wradlib.verify.ErrorMetrics.spearman 

ErrorMetrics.spearman() 


wradlib.verify.ErrorMetrics.sse 

ErrorMetrics.sse() 


3.14.2 wradlib.verify.PolarNeighbours 

class wradlib.verify.PolarNeighbours(r, az, sitecoords, projstr, x, y, nnear=9) 

For a set of projected point coordinates, extract the neighbouring bin values from a data set in polar coordinates. 

Use as follows: 

First, create an instance of PolarNeighbours by passing all the information needed to georeference the polar 

radar data to the points of interest (see parameters) 

Second, use the method extract in order to extract the values from a data array which corresponds to the polar 

coordinates 

Parameters r : array of floats 

(see georef for documentation) 

az : array of floats 


sitecoords : sequence of floats 




x : array of floats 

x coordinates of the points in map projection corresponding to projstr 

y : array of floats 

y coordinates of the points in map projection corresponding to projstr 

nnear : int 

number of neighbouring radar bins you would like to find 

Methods 

extract(vals) 

get_bincoords() 

get_bincoords_at_points() 

Extracts the values from an array of shape (azimuth angles, range gages) 

Returns all bin coordinates in map projection 

Returns bin coordinates only in the neighbourshood of points 



wradlib.verify.PolarNeighbours.extract 

PolarNeighbours.extract(vals) 

Extracts the values from an array of shape (azimuth angles, range gages) which correspond to the indices 

computed during initialisation 

Parameters vals : array of shape (..., number of azimuth, number of range gates) 

Returns output : array of shape (..., number of points, nnear) 

wradlib.verify.PolarNeighbours.get_bincoords 

PolarNeighbours.get_bincoords() 


Returns output : array of x coordinates, array of y coordinates 

wradlib.verify.PolarNeighbours.get_bincoords_at_points 

PolarNeighbours.get_bincoords_at_points() 



extract(vals) 

get_bincoords() 

get_bincoords_at_points() 

Extracts the values from an array of shape (azimuth angles, range gages) 



wradlib.verify.PolarNeighbours.extract 

PolarNeighbours.extract(vals) 

Extracts the values from an array of shape (azimuth angles, range gages) which correspond to the indices computed 

during initialisation 

Parameters vals : array of shape (..., number of azimuth, number of range gates) 

Returns output : array of shape (..., number of points, nnear) 

wradlib.verify.PolarNeighbours.get_bincoords 

PolarNeighbours.get_bincoords() 



wradlib.verify.PolarNeighbours.get_bincoords_at_points 

PolarNeighbours.get_bincoords_at_points() 





3.15 Visualisation 

Standard plotting and mapping procedures 

polar_plot 

rhi_plot 

Grid2Basemap 

Plots data from a polar grid. 

Returns figure and pylab object of plotted data from a polar grid as an RHI (Range Height Indicator). 

Plot gridded data on a background map 

3.15.1 wradlib.vis.polar_plot 

wradlib.vis.polar_plot(data, title=’‘, unit=’‘, saveto=’‘, fig=None, axpos=111, R=1.0, theta0=0, 

colormap=’jet’, classes=None, extend=’neither’, **kwargs) 

Plots data from a polar grid. 

The data must be an array of shape (number of azimuth angles, number of range bins). The azimuth angle of 

zero corresponds to the north, the angles are counted clock-wise forward. 

additional kwargs will be passed to the pcolormesh routine displaying the data. 

Parameters data : 2-d array 

polar grid data to be plotted 1st dimension must be azimuth angles, 2nd must be ranges! 

title : string 

a title of the plot 

unit : string 

the unit of the data which is plotted 

saveto : string - path of the file in which the figure should be saved 

if string is empty, no figure will be saved and the plot will be sent to screen 

fig : matplotlib axis object 

if None, a new matplotlib figure will be created, otherwise we plot on ax 

axpos : an integer or a string 

R : float 

correponds to the positional argument of matplotlib.figure.add_subplot 

maximum range 

theta0 : integer 

azimuth angle which corresponds to the first slice of the dataset (normally corresponds 

to 0) 

colormap : string 

choose between the colormaps “jet” (per default) and “spectral” 

classes : sequence of numerical values 

class boundaries for plotting 

extend : string 



determines the behaviour of the colorbar: default value ‘neither’ produces a standard 

colorbar, ‘min’ and ‘max’ produces an arrow at the minimum or maximum end, respectively, 

and ‘both’ produces an arrow at both ends. If you use class boundaries for 

plotting, you should typically use ‘both’. 

3.15.2 wradlib.vis.rhi_plot 

wradlib.vis.rhi_plot(data, **kwargs) 

Returns figure and pylab object of plotted data from a polar grid as an RHI (Range Height Indicator). 

Plotting need to be done outside wradlib 

The data must be an array of shape (number of azimuth angles, number of range bins). The azimuth angle of 

0 degrees corresponds to y-axis = 0 (east direction) The azimuth angle of 90 degrees corresponds to y-axis = 0 

(north direction) The azimuth the angles are counted counter-clock-wise forward. 

Additional myargs are extracted from kwargs, processed and/or passed to the create_curvilinear_axes routine 

Additional remaining kwargs will be passed to the pcolormesh routine displaying the data. Be careful! 

Parameters data : 2-d array 

polar grid data to be plotted 1st dimension must be azimuth angles, 2nd must be ranges! 

Keyword arguments: : 

R : tuple of array of float and unit string 

[display min range, display max range, data max range}, unit string defaults to [0, 

data.shape range, data.shape range], empty string 

H : array of array float and unit string 

[display min height, display max height], unit string defaults to [0,data.shape range ], 

empty string 

theta_range: float array : 

theta range (min, max) used to display data 

rad_range: float array : 

radial range (min, max) used to display data 

r_res : float array of range (x) tick resolution (empty, single value, multiple values) 

h_res : float array of height (y) tick resolution (empty, single value, multiple values) 

a_res : float 

sets # of angle gridlines and labels, defaults to 8, wich means 10 deg resolution 

title : string 

a title of the plot, defaults to ‘Range Height Indicator’ 

xtitle : string 

x-axis label defaults to ‘Range’ or ‘Range (km)’ if R is given (mostly km) 

ytitle : string 

y-axis label defaults to ‘Height’ or ‘Height (km)’ if H is given (mostly km) 

atitle : string 

3.15. Visualisation 87


angle-axis label, not used at the moment, due to inconvenient placing defaults to ‘$Angle$’)# 

($^{circ}$)’ 

saveto : string - path of the file in which the figure should be saved 

if string is empty, no figure will be saved and the plot will be sent to screen 

fig : matplotlib axis object 

if None, a new matplotlib figure will be created, otherwise we plot on given figure 

figsize : width , hight tuple in inches 

defaults to (10,6) 

axpos : an integer or a string 

correponds to the positional argument of mpl_toolkits.axisartist.SubplotHost defaults to 

‘111’ TODO: if multiple plots are used, position and size of labels have to be corrected 

in source code 

colormap : string 

choose the colormap (“Paired” per default) 

classes : sequence of numerical values 

class boundaries for plotting 

unit : string 

the unit of the data which is plotted 

extend : string 

determines the behaviour of the colorbar: default value ‘neither’ produces a standard 

colorbar, ‘min’ and ‘max’ produces an arrow at the minimum or maximum end, respectively, 

and ‘both’ produces an arrow at both ends. If you use class boundaries for 

plotting, you should typically use ‘both’. 

Returns fig : figure object, just for testing and in the case of multiplot 

pl : pylab object, just for testing and in the case of multiplot 

3.15.3 wradlib.vis.Grid2Basemap 

class wradlib.vis.Grid2Basemap(bbox, classes, unit=’‘, points={}, 

cmap=, shpfiles=[], **kwargs) 

Plot gridded data on a background map 

STILL UNDER DEVELOPMENT!!! 

This class allows to plot gridded data (e.g. PPIs, CAPPIs, composites) on a background. The background map 

(Basemap) can include country borders, coastlines, meridians as well as user-defined shapefiles. The plot will 

appear as filled contours. 

In order to plot user defined backgroud data such as points or shapefiles, these have to be provided in “geographical 

projection”, i.e. in lat/lon coordinates based on WGS84. You can use any GIS for this task. Shapefiles are 

then passed to the constructor by providing a list of file paths in the argument shpfiles (see Parameters). 

Using Grid2Basemap(...), the background map is plotted. The actual data is plotted by using the plot method. 

This procedure allows to repeatedly plot data on a map (e.g. a time series) without each time plotting the 



background again. This will save a huge amount of processing time if a large number of images is plotted over 

the same background. 

Parameters bbox : dictionary 

the bounding box of the entire map in lat/lon 

classes : list of floats 

classes of the plotting variable for which colors should be homogenoeous 

unit : string 

points : dictionary 

shpfiles : list of strings 

paths to shapefiles which will be plotted as map background 

cmap : name of the default colormap in case no colormap is provided in the config file 

Methods 

plot(lon, lat, data[, title, saveto]) 

Plot the data on the map background 

wradlib.vis.Grid2Basemap.plot 

Grid2Basemap.plot(lon, lat, data, title=’‘, saveto=None) 


Parameters lon : array of longitudes 

lat : array of latitudes 

data : data array of shape (number of longitudes, number of latitudes) 

title : figure title 

saveto : string to a directory where figures should be stored 

plot(lon, lat, data[, title, saveto]) 


wradlib.vis.Grid2Basemap.plot 

Grid2Basemap.plot(lon, lat, data, title=’‘, saveto=None) 


Parameters lon : array of longitudes 

lat : array of latitudes 

data : data array of shape (number of longitudes, number of latitudes) 

title : figure title 

saveto : string to a directory where figures should be stored 

3.15. Visualisation 89


3.16 Utility functions 

Module util provides a set of useful helpers which are currently not attributable to the other modules 

aggregate_in_time 

from_to 

Aggregate time series data to a coarser temporal resolution. 

Return a list of timesteps from to of length 

3.16.1 wradlib.util.aggregate_in_time 

wradlib.util.aggregate_in_time(src, dt_src, dt_trg, taxis=0, func=’sum’) 

Aggregate time series data to a coarser temporal resolution. 

Parameters src : array of shape (..., original number of time steps,...) 

This is the time series data which should be aggregated. The position of the time dimension 

is indicated by the taxis argument. The number of time steps corresponds to 

the length of the time dimension. 

taxis : integer 

This is the position of the time dimension in array src. 

dt_src : array of datetime objects 

Must be of length original number of time steps + 1 because dt_src defines the limits of 

the intervals corresponding to the time steps. This means: dt_src[0] is the lower limit of 

time step 1, dt_src[1] is the upper limit of time step 1 and the lower limit of time step 2 

and so on. 

dt_trg : array of datetime objects 

Must be of length number of output time steps + 1 analogously to dt_src. This means: 

dt_trg[0] is the lower limit of output time step 1, dt_trg[1] is the upper limit of output 

time step 1 and the lower limit of output time step 2 and so on. 

func : numpy function name, e.g. ‘sum’, ‘mean’ 

Defines the way the data should be aggregated. The string must correspond to a valid 

numpy function, e.g. ‘sum’, ‘mean’, ‘min’, ‘max’. 

Returns output : array of shape (..., len(dt_trg) - 1, ...) 

The length of the time dimension of the output array depends on the array dt_trg which 

defines the limits of the output time step intervals. 

Examples 

>>> src = np.arange(8*4).reshape( (8,4) ) 

>>> print ’source time series:’ 

>>> print src 

>>> dt_src = [dt.datetime.strptime(’2008-06-02’, ’%Y-%m-%d’ ) + dt.timedelta(hours=i) for i in r 

>>> print ’source time interval limits:’ 

>>> for tim in dt_src: print tim 

>>> print ’target time interval limits:’ 

>>> dt_trg = [dt.datetime.strptime(’2008-06-02’, ’%Y-%m-%d’ ) + dt.timedelta(seconds=i*3600*4) f 

>>> for tim in dt_trg: print tim 

>>> print ’target time series’ 

>>> print aggregate_in_time(src, dt_src, dt_trg, axis=0, func=’sum’) 



3.16.2 wradlib.util.from_to 

wradlib.util.from_to(tstart, tend, tdelta) 

Return a list of timesteps from to of length 

Parameters tstart : datetime isostring (%Y%m%d %H:%M:%S), e.g. 2000-01-01 15:34:12 

tend : datetime isostring (%Y%m%d %H:%M:%S), e.g. 2000-01-01 15:34:12 

tdelta : integer representing time interval in SECONDS 

Returns output : list of datetime.datetime objects 

3.16. Utility functions 91



CHAPTER 

FOUR 

DEVELOPMENT SETUP 

In the future, each release of wradlib will be guaranteed to work with a certain version of python(x,y) under MS 

Windows. The current version is 2.7.2.3. On other operating systems, the library should work, if similar versions of 

the required packages are installed. 

However, at the moment you will need to install the following packages beyond python(x,y): 

• pyproj: Performs cartographic transformations and geodetic computations. Visit 

http://code.google.com/p/pyproj/ and download the package installer. 

• basemap: The matplotlib basemap toolkit is a library for plotting 2D data on maps. Find documentation on 

http://matplotlib.org/basemap and download the latest basemap installer. 

4.1 Documentation Setup 

There are a few things that need to be done in order for the documentation to be built properly. 

The documentation tool is Sphinx. We oriented ourselves at the Numpy/Scipy documentation concerning docstrings. 

This implies using numpydoc to enable Sphinx to understand the formatting of those docstrings. If you installed 

Python(x,y) Enthought Python, Sphinx is already installed. In order to install numpydoc, simply open a console 

window and type easy_install numpydoc. 

Now you can open a console window in the folder wradlib/doc and execute make html. This will give you the latest 

documentation under the wradlib/doc/build/html directory. Simply open the index.html file to view the documentation. 

93


94 Chapter 4. Development Setup

CHAPTER 

FIVE 

TEAM 

5.1 Developers 

wradlib is under continuous development. This is the current team of developers (in alphabetical order): 

Maik Heistermann (based at the University of Potsdam) 

Stephan Jacobi (based at the University of Potsdam) 

Thomas Pfaff (based at the University of Stuttgart) 

5.2 Contributers 

Do you want to help in enhancing the capabilities of wradlib? You can join the team of developers! But you can also 

contribute code (in any programming language) or documentations of specific algorithms you consider useful so that 

we can include these in wradlib. 

5.3 Users 

By using wradlib you can also contribute to its development by reporting bugs or by proposing new developments. 

We need your continuous feedback to improve wradlib. For this purpose, use the issues tab of wradlib’s Bitbucket 

repository site in order to raise an issue. 

We also encourage you to register to the mailing list wradlib-users. Using this mailing list or forum, you can ask other 

users and developers for help and help others, and we can notify you about the latest updates and developments. 

Selection of institutions using wradlib (in alphabetical order): 

• Helmholtz-Centre for Environmental Research (UFZ), Germany 

• National Institute of Geological Sciences, Philippines 

• Tohoku University, Graduate School of Science, Japan 

• University of Bonn, Institute of Meteorology, Germany 

• University of Potsdam, Institute of Earth and Environmental Sciences, Germany 

• University of Stuttgart, Institut fuer Wasser- und Umweltsystemmodellierung, Germany 

95


96 Chapter 5. Team

CHAPTER 

SIX 

INDICES AND TABLES 

• genindex 

• modindex 

• search 

97


98 Chapter 6. Indices and tables

BIBLIOGRAPHY 

[Gabella2002] Gabella, M. & Notarpietro, R., 2002. Ground clutter characterization and elimination 

in mountainous terrain. In Proceedings of ERAD. Delft: Copernicus GmbH, pp. 305-311. URL: 

http://www.copernicus.org/erad/online/erad-305.pdf [Accessed Oct 25, 2012]. 

[Goudenhoofdt2009] Goudenhoofdt, E., and L. Delobbe, 2009. Evaluation of radar-gauge merging methods for quantitative 

precipitation estimates. HESS, 13, 195-203. URL: http://www.hydrol-earth-syst-sci.net/13/195/2009/hess- 

13-195-2009.pdf 

[Hitschfeld1954] Hitschfeld, W. & Bordan, J., 1954. Errors Inherent in the Radar Measurement of Rainfall 

at Attenuating Wavelengths. Journal of the Atmospheric Sciences, 11(1), p.58-67. DOI: 10.1175/1520- 

0469(1954)0112.0.CO;2 

[Kraemer2008] Kraemer, S., H. R. Verworn, 2008: Improved C-band radar data processing for real time control of 

urban drainage systems. 11th International Conference on Urban Drainage, Edinburgh, Scotland, UK, 2008. URL: 

http://web.sbe.hw.ac.uk/staffprofiles/bdgsa/11th_International_Conference_on_Urban_Drainage_CD/ICUD08/pdfs/105.pdf 

[Accessed Oct 25, 2012]. 

[DWD2009] Germany Weather Service (DWD), 2009: RADLOAN/RADVO-OP - Beschreibung des Kompositformats, 

Version 2.2.1. Offenbach, Germany, URL: http://dwd.de/radolan (in German) 

[Collier1996] Collier, C.G., 1996. Applications of weather radar systems: A guide to uses of radar data in meteorology 

and hydrology 2nd edition, New York: John Wiley and Sons. 

[Doviak1993] Doviak, R.J. & Zrnic, D.S., 1993. Doppler radar and weather observations 2nd ed., San Diego: Academic 

Press. 

[Gabella2002] Gabella, M. & Notarpietro, R., 2002. Ground clutter characterization and elimination in 

mountainous terrain. In Proceedings of ERAD. Delft: Copernicus GmbH, pp. 305-311. Available at: 

http://www.copernicus.org/erad/online/erad-305.pdf [Accessed Oct 27, 2010]. 

[Hitschfeld1954] Hitschfeld, W. & Bordan, J., 1954. Errors Inherent in the Radar Measurement of Rainfall 

at Attenuating Wavelengths. Journal of the Atmospheric Sciences, 11(1), p.58-67. DOI: 10.1175/1520- 

0469(1954)0112.0.CO;2 

[Kraemer2008] Krämer, Stefan 2008: Quantitative Radardatenaufbereitung für die Niederschlagsvorhersage und die 

Siedlungsentwässerung, Mitteilungen Institut für Wasserwirtschaft, Hydrologie und Landwirtschaftlichen Wasserbau 

Gottfried Wilhelm Leibniz Universität Hannover, Heft 92, ISSN 0343-8090. 

[Jacobi2011] Jacobi, S., Heistermann, M., Pfaff, T. 2011: Evaluation and improvement of C-band radar attenuation 

correction for operational flash flood forecasting. Proceedings of the Weather Radar and Hydrology symposium, 

Exeter, UK, April 2011, IAHS Publ. 3XX, 2011, in review. 

[Pfaff2010] Pfaff, T., 2010. Radargestuetzte Schaetzung von Niederschlagsensembles (in 

German). In: Bronstert et al. (Eds.). Operationelle Abfluss- und Hochwasservorher- 

99


sage in Quellgebieten. Final Project Report, pp. 113-118. URL: http://www.rimaxhochwasser.de/fileadmin/user_uploads/RIMAX_PUB_22_0015_Abschlussbericht%20OPAQUE_final.pdf. 

[GoudenhooftdandDelobbe2009] Goudenhoofdt, E., and L. Delobbe, 2009. Evaluation of radar-gauge merging 

methods for quantitative precipitation estimates. HESS, 13, 195-203. URL: http://www.hydrol-earth-systsci.net/13/195/2009/hess-13-195-2009.pdf 

100 Bibliography

PYTHON MODULE INDEX 

w 

wradlib.adjust, 63 

wradlib.atten, 58 

wradlib.bufr, 38 

wradlib.clutter, 55 

wradlib.comp, 53 

wradlib.fill, 57 

wradlib.georef, 41 

wradlib.io, 35 

wradlib.ipol, 47 

wradlib.qual, 51 

wradlib.trafo, 39 

wradlib.util, 89 

wradlib.verify, 79 

wradlib.vis, 85 

wradlib.vpr, 57 

wradlib.zr, 40 

101


102 Python Module Index

PYTHON MODULE INDEX 

w 

wradlib.adjust, 63 

wradlib.atten, 58 

wradlib.bufr, 38 

wradlib.clutter, 55 

wradlib.comp, 53 

wradlib.fill, 57 

wradlib.georef, 41 

wradlib.io, 35 

wradlib.ipol, 47 

wradlib.qual, 51 

wradlib.trafo, 39 

wradlib.util, 89 

wradlib.verify, 79 

wradlib.vis, 85 

wradlib.vpr, 57 

wradlib.zr, 40 

103

wradlib Documentation - Bitbucket

Create successful ePaper yourself

Delete template?

Save as template?