wradlib 2.0 migration#

Introduction#

For \(\omega radlib\) 2.0 there have been quite some deprecations and additions. Most of the changes have been announced over the latest wradlib 1 versions. Nevertheless, to make a clean cut it was neccessary to change and remove code and functionality which was not yet being officially deprecated.

The function signatures have been revisited with regard to PEP570. Please look out for changes in the parameter-list, there might be changes on parameters being positional only, positional and keyword or keyword-only.

The georeferencing submodule has undergone an alignment process for function parameters. For Coordinate Reference Systems (CRS) crs-kwarg is used for geographic CRS as well as projected CRS. If the function needs source and/or target, then src_crs and trg_crs is used respectively. At the same time the site/sitecoords have been aligned to site.

The early experiments with xarray reading capabilities (deprecated) have been removed, the more mature xarray backend code has been ported to xradar-package from where \(\omega radlib\) is importing it.

There have also been quite some changes to the visualization code. For several years now, the plot_ppi/plot_rhi-functions have converted the provided arguments to an xarray.DataArray under the hood. To lessen that code burden these functions are also removed. The user now has to convert the data to xarray.DataArray, if not already reading via xradar. Finally, the unified wradlib.vis.plot-function manages all plotting.

To bring \(\omega radlib\)’s integration with xarray to a new level, many functions have already been bound to either xarray.DataArray or xarray.Dataset by Accessors as laid out in Extending xarray using accessors. To remain backwards compatible with users numpy-based workflows the functions have been overloaded using functools.singledispatch-decorator. Within the overloaded functions the numpy-functions are called via xarray.apply_ufunc or the functionality was implemented directly based on xarray. Usage of Dask, and with that lazy-processing, is currently only available on those functions which are already capable. The adaption or rewrite of code can now be done using a unified calling convention for numpy- as well as xarray-based functions.

In the next sections the additions and deprecations (including breaking changes) are announced on a per module basis.

adjust - Submodule#

No deprecations or additions.

atten - Submodule#

Additions#

Implemented Xarray Accessor wrl.atten ({py:class}`wradlib.atten.AttenMethods) with:

classify - Submodule#

Merged with code from clutter-module.

Additions#

Implemented Xarray Accessor wrl.classify (wradlib.classify.ClassifyMethods) with:

classify_echo_fuzzy returns probability of meteorological echo instead of boolean clutter mask, use np.where(prob < thresh, True, False) to retrieve boolean clutter mask.

clutter - Submodule#

Deprecations#

Functions have been merged with wradlib.classify-submodule (see above). Module has been removed.

comp - Submodule#

Additions#

Implemented Xarray Accessor wrl.comp (wradlib.comp.CompMethods) with:

dp - Submodule#

Additions#

Implemented Xarray Accessor wrl.dp (wradlib.dp.DpMethods) with:

Deprecations#

georef-submodule#

Additions#

Implemented Xarray Accessor wrl.georef (wradlib.georef.GeorefMethods) with:

Deprecations#

io - Submodule#

Deprecations#

The xarray based radar readers for polar data have been moved to xradar-package

  • wradlib.io.ODIMH5

  • wradlibio.CfRadial

  • wradlibio.XRadVol

  • wradlibio.open_odim

  • wradlibio.XRadSweep

  • wradlibio.XRadMoment

  • wradlibio.XRadTimeSeries

  • wradlibio.XRadVolume

  • wradlibio.RadarVolume

  • wradlibio.open_radar_dataset

  • wradlibio.open_radar_mfdataset

  • wradlibio.to_netcdf

  • wradlibio.open_rainbow_dataset

  • wradlibio.open_rainbow_mfdataset

  • wradlibio.open_cfradial1_dataset

  • wradlibio.open_cdradial1_mfdataset

  • wradlibio.open_cfradial2_dataset

  • wradlibio.open_cdradial2_mfdataset

  • wradlibio.open_iris_dataset

  • wradlibio.open_iris_mfdataset

  • wradlibio.open_odim_dataset

  • wradlibio.open_odim_mfdataset

  • wradlibio.open_gamic_dataset

  • wradlibio.open_gamic_mfdataset

  • wradlibio.open_furuno_dataset

  • wradlibio.open_furuno_mfdataset

  • wradlibio.CfRadial1BackendEntrypoint

  • wradlibio.CfRadial2BackendEntrypoint

  • wradlibio.FurunoBackendEntrypoint

  • wradlibio.GamicBackendEntrypoint

  • wradlibio.OdimBackendEntrypoint

  • wradlibio.RainbowBackendEntrypoint

  • wradlibio.IrisBackendEntrypoint

  • wradlib.io.radolan_to_xarray - wradlib.io.radolan.open_radolan_dataset or xarray.open_dataset with engine="radolan"

  • wradlib.io.create_xarray_dataarray -> wradlib.georef.xarray.create_xarray_dataarray

How can I read my data now?#

Single sweep#

swp = xarray.open_dataset(filename, engine=engine, group=group)

engine would be one BackendName defined in xradar, where currently available are:

group would be a string like sweep_0 for first sweep, sweep_1 for second sweep and so forth.

The above command will return an xarray.Dataset which is aligned with the CfRadial2/FM301 standard. Please refer to the XRadar Data Model.

Please also refer to xarray.open_dataset documentation.

Timeseries of sweeps#

ts = xarray.open_mfdataset(
    filelist, concat_dim=time2, engine=engine, group=group, preprocess=preprocess
)

preprocess is here a function which is applied to each of the retrieved datasets to align them for stacking along the new dimension (time2). One use-case would be Angle Reindexing.

Please also refer to xarray.open_mfdataset documentation.

Single metadata group#

The same way different metadata groups can be retrieved. Just require the wanted group with group-kwarg.

Single Volume#

\(\omega radlib\)’s RadarVolume is replaced by datatree.DataTree.

vol = xradar.io.open_cfradial1_datatree(filename)

Here, as well as above, each backend has its own loading function:

Multiple Volumes#

This is not yet available out of the box as dedicated functions (like xarray.open_mfdataset) but this is worked on at How to Read in Multiple Volume Scans Into a Single Object and Visualize.

ipol - Submodule#

Additions#

Implemented Xarray Accessor wrl.ipol (wradlib.ipol.IpolMethods) with:

qual - Submodule#

Additions#

Implemented Xarray Accessor wrl.qual (wradlib.qual.QualMethods) with:

trafo - Submodule#

Additions#

Implemented Xarray Accessor wrl.trafo (wradlib.trafo.TrafoMethods) with:

util - Submodule#

Additions#

Implemented Xarray Accessor wrl.util (wradlib.util.UtilMethods) with:

verify - Submodule#

No deprecations or additions.

vis - Submodule#

Additions#

Implemented Xarray Accessor wrl.vis (wradlib.vis.VisMethods) with:

  • plot

  • pcolormesh

  • contour

  • contourf

Deprecations#

vpr - Submodule#

No deprecations or additions.

xarray - Submodule#

Additions#

New module containing WradlibXarrayAccessor implementation.

zonalstats - Submodule#

Deprecations#

  • wradlib.zonalstats.DataSource -> (py:class}wradlib.io.vector.VectorSource

zr - Submodule#

Additions#

Implemented Xarray Accessor wrl.zr (wradlib.zr.ZRMethods) with: