Internals#

This page is dedicated for internal usage of the software package. There you find some development plans, coding style guide and conventions.

Conventions#

There are some conventions, e.g. naming conventions. The internals of this processing software are based on these conventions. Follow these conventions if you want to contribute to this software.

Coding Conventions#

  • PEP8

  • Numpy docstring

  • Maximum line length: 80

  • At least one test per object

  • Pass all tests before pull request

  • Check and update requirements and environment.yml

Testing Conventions#

  • Try to test every line of code

  • Every function and object should have a docstring describing what happens within the call.

  • The test-driven development paradigm is desirable

Naming Conventions#

It is possible to set the DataArray name to the radar naming conventions, which are used in this package. The conventions are based on OPERA, NCAR, CF Conventions. We try to follow the product standard defined by [Lammert et al., 2018]. At the moment, following different variables are implemented:

  • ‘dbz’ (\(\mathrm{dBZ}\)): reflectivity in decibel (standard_name: equivalent_reflectivity_factor, short_name: dBZ)

  • ‘z’ (\(\mathrm{mm^6\,m^{-3}}\)): linear reflectivity (standard_name: linear_equivalent_reflectivity_factor, short_name: Z)

  • ‘rr’ (\(\mathrm{mm\,h^{-1}}\)): linear rain rate (standard_name: rainfall_rate, short_name: RR)

  • ‘dbrr’ (\(\mathrm{dBR}\)): rain rate in decibel (standard_name: decibel_rainfall_rate, short_name: dBR)

  • ‘pia’ (\(\mathrm{dB}\)): path integrated attenuation (long_name: path integrated attenuation, short_name: PIA)

  • ‘time’ (): time (standard_name: time)

  • ‘azimuth’ (\(^\circ{}\)): azimuth angle (standard_name: sensor_azimuth_angle)

  • ‘azimuth_offset’ (\(^\circ{}\)): offset of azimuth angle (long_name: offset sensor azimuth angle)

  • ‘range’ (\(\mathrm{m}\)): range (long_name: distance from sensor to center of each range gates along the line of sight)

  • ‘lat’ (\(^\circ{}\,\mathrm{N}\)): latitude (standard_name: latitude)

  • ‘lat_center’ (\(^\circ{}\,\mathrm{N}\)): latitude of instrument location (standard_name: latitude)

  • ‘lon’ (\(^\circ{}\,\mathrm{E}\)): longitude (standard_name: longitude)

  • ‘lon_center’ (\(^\circ{}\,\mathrm{E}\)): longitude of instrument location (standard_name: longitude)

  • ‘latitude’ (\(^\circ{}\,\mathrm{N}\)): latitude (standard_name: latitude)

  • ‘longitude’ (\(^\circ{}\,\mathrm{E}\)): longitude (standard_name: longitude)

  • ‘y’ (\(\mathrm{m}\)): Cartesian y-coordinate (long_name: y-coordinate in Cartesian system)

  • ‘x’ (\(\mathrm{m}\)): Cartesian x-coordinate (long_name: x-coordinate in Cartesian system)

  • ‘zsl’ (\(\mathrm{m}\)): altitude / height above mean sea level (standard_name: altitude)

  • ‘zsl_center’ (\(\mathrm{m}\)): altitude of instrument above mean sea level (standard_name: altitude)

  • ‘ele’ (\(^\circ{}\)): beam elevation angle (long_name: ‘sensor elevation angle’)

  • ‘noise_level’ (\(\mathrm{mm^6\,m^{-3}\,m^{-2}}\)): noise level (long_name: ‘noise_level’)

The variable can be set with: array.lawr.set_variable(var_name), where var_name is the name of the variable. If this method is used, then the name, short name, long name and unit will be set as defined above.

If the data is read with a DataHandler, then all variables will be set automatically as defined the conventions.

How can I add a new radar variable?#

The naming conventions with short name, long name, unit and standard name are defined within pylawr/utilities/conventions as OrderedDict with the variable name naming_convention. There you can add a new variable, which needs to have the same structure as the other variables.

Additionally, you need to add a way how your variable can be converted to linear reflectivity. For this you need to add your standard variable name as key to the from_dict within pylawr/field.py. The value need to be a valid way how your variable can be converted to linear reflectivity.

There exist within the field class an utility method _convert_field which takes a conversion function and a target variable name as arguments. Also, you can use the func_compose function within pylawr/utilities/utilities.py, which allows you to compose different functions together.

The easiest way to add the route from and to linear reflectivity would be to add an additional method to the Field accessor with an additional inverse keyword, an example for this is the zr_convert method within the Field accessor. It is recommended to add tests to tests/unit_tests/test_field.py to check if your conversion implementation is valid.