- Naming things: Use RADOLAN_CDC instead of RADOLAN_GRID

- Update api.rst re. RADAR data acquisition

docs/pages/api.rst

@@ -249,16 +249,9 @@ Other variants::
 RADAR
 *****
 
-To use ``DWDRadarRequest``, you have to provide a time resolution (either hourly or daily)
-and ``date_times`` (list of datetimes or strings) or a start date and end date. Datetimes
-are rounded to HH:50min as the data is packaged for this minute step. Additionally,
-you can provide a folder to store/restore RADOLAN data to/from the local filesystem.
-
-This is a short snippet which should give you an idea
-how to use ``DWDRadarRequest`` together with ``wradlib``.
-For a more thorough example, please have a look at `example/radolan.py`_.
-
-The subsystem implements access to various radar data like:
+To use ``DWDRadarRequest``, you have to provide a ``RadarParameter``,
+which designates the type of radar data you want to obtain. There is
+radar data available at different locations within the DWD data repository:
 
 - https://opendata.dwd.de/climate_environment/CDC/grids_germany/5_minutes/radolan/
 - https://opendata.dwd.de/climate_environment/CDC/grids_germany/daily/radolan/
@@ -267,13 +260,29 @@ The subsystem implements access to various radar data like:
 - https://opendata.dwd.de/weather/radar/composit/
 - https://opendata.dwd.de/weather/radar/sites/
 
+For ``RADOLAN_CDC``-data, the time resolution parameter (either hourly or daily)
+must be specified.
+
+The ``date_times`` (list of datetimes or strings) or a ``start_date``
+and ``end_date`` parameters can optionally be specified to obtain data
+from specific points in time.
+
+For ``RADOLAN_CDC``-data, datetimes are rounded to ``HH:50min``, as the
+data is packaged for this minute step. Additionally, you can provide a
+folder to store/restore RADOLAN data to/from the local filesystem.
+
+This is an example on how to acquire ``RADOLAN_CDC`` data using
+``wetterdienst`` and process it using ``wradlib``.
+For a more thorough example, please have a look at `example/radar_radolan_cdc.py`_.
+
 .. code-block:: python
 
-    from wetterdienst import DWDRadarRequest, TimeResolution
+    from wetterdienst import DWDRadarRequest, RadarParameter, TimeResolution
     import wradlib as wrl
 
     radar = DWDRadarRequest(
-        TimeResolution.DAILY,
+        radar_parameter=RadarParameter.RADOLAN_CDC,
+        time_resolution=TimeResolution.DAILY,
         start_date="2020-09-04T12:00:00",
         end_date="2020-09-04T12:00:00"
     )
@@ -290,7 +299,7 @@ The subsystem implements access to various radar data like:
 
 
 .. _wradlib: https://wradlib.org/
-.. _example/radolan.py: https://github.com/earthobservations/wetterdienst/blob/master/example/radolan.py
+.. _example/radolan.py: https://github.com/earthobservations/wetterdienst/blob/master/example/radar/radar_radolan_cdc.py
 
 .. _SQLite: https://www.sqlite.org/
 .. _DuckDB: https://duckdb.org/docs/sql/introduction

example/radar/radar_radolan_grid.py → example/radar/radar_radolan_cdc.py

@@ -124,9 +124,9 @@ def label_by_producttype(producttype: str) -> str:
 
 def radolan_grid_example():
 
-    log.info("Acquiring RADOLAN_GRID data")
+    log.info("Acquiring RADOLAN_CDC data")
     radolan = DWDRadarRequest(
-        radar_parameter=RadarParameter.RADOLAN_GRID,
+        radar_parameter=RadarParameter.RADOLAN_CDC,
         time_resolution=TimeResolution.DAILY,
         start_date="2020-09-04T12:00:00",
         end_date="2020-09-04T12:00:00",
@@ -140,7 +140,7 @@ def radolan_grid_example():
         timestamp, buffer = item
 
         # Decode data using wradlib.
-        log.info("Parsing RADOLAN_GRID composite data for %s", timestamp)
+        log.info("Parsing RADOLAN_CDC composite data for %s", timestamp)
         data, attributes = wrl.io.read_radolan_composite(buffer)
 
         # Compute label matching RW/SF product.

tests/dwd/radar/test_api_historic.py

@@ -16,7 +16,7 @@ def test_radar_request_radolan_grid_wrong_parameters():
 
     with pytest.raises(ValueError):
         DWDRadarRequest(
-            radar_parameter=RadarParameter.RADOLAN_GRID,
+            radar_parameter=RadarParameter.RADOLAN_CDC,
             time_resolution=TimeResolution.MINUTE_1,
             date_times=["2019-08-08 00:50:00"],
         )
@@ -25,17 +25,17 @@ def test_radar_request_radolan_grid_wrong_parameters():
 @pytest.mark.remote
 def test_radar_request_radolan_grid_hourly():
     """
-    Example for testing RADOLAN_GRID.
+    Example for testing RADOLAN_CDC.
     """
 
     request = DWDRadarRequest(
-        radar_parameter=RadarParameter.RADOLAN_GRID,
+        radar_parameter=RadarParameter.RADOLAN_CDC,
         time_resolution=TimeResolution.HOURLY,
         date_times=["2019-08-08 00:50:00"],
     )
 
     assert request == DWDRadarRequest(
-        radar_parameter=RadarParameter.RADOLAN_GRID,
+        radar_parameter=RadarParameter.RADOLAN_CDC,
         time_resolution=TimeResolution.HOURLY,
         date_times=[datetime(year=2019, month=8, day=8, hour=0, minute=50, second=0)],
     )

tests/dwd/radar/test_api_latest.py

@@ -43,10 +43,10 @@ def test_radar_request_rw_reflectivity_latest():
 
     header = (
         b"RW......100000920BY16201..VS 3SW   2.28.1PR E-01INT  60GP 900x 900MF 00000001MS "  # noqa:E501,B950
-        b"..<asb,boo,ros,hnr,umd,pro,ess,fld,drs,neu,(nhb,)?oft,eis,tur,fbg,mem>"
+        b"..<asb,boo,ros,hnr,umd,pro,ess,fld,drs,neu,(nhb,)?oft,eis,tur,(isn,)?fbg,mem>"
     )
 
-    assert re.match(header, payload), payload[:150]
+    assert re.match(header, payload[:150])
 
 
 @pytest.mark.remote

tests/dwd/radar/test_index.py

@@ -145,7 +145,7 @@ def test_radar_fileindex_sites_sweep_hdf5():
 def test_radar_fileindex_grid_daily_recent():
 
     file_index = create_fileindex_radar(
-        parameter=RadarParameter.RADOLAN_GRID,
+        parameter=RadarParameter.RADOLAN_CDC,
         time_resolution=TimeResolution.DAILY,
         period_type=PeriodType.RECENT,
     )
@@ -163,7 +163,7 @@ def test_radar_fileindex_grid_daily_recent():
 def test_radar_fileindex_grid_daily_historical():
 
     file_index = create_fileindex_radar(
-        parameter=RadarParameter.RADOLAN_GRID,
+        parameter=RadarParameter.RADOLAN_CDC,
         time_resolution=TimeResolution.DAILY,
         period_type=PeriodType.HISTORICAL,
     )
@@ -181,7 +181,7 @@ def test_radar_fileindex_grid_daily_historical():
 def test_radar_fileindex_grid_hourly_recent():
 
     file_index = create_fileindex_radar(
-        parameter=RadarParameter.RADOLAN_GRID,
+        parameter=RadarParameter.RADOLAN_CDC,
         time_resolution=TimeResolution.HOURLY,
         period_type=PeriodType.RECENT,
     )
@@ -199,7 +199,7 @@ def test_radar_fileindex_grid_hourly_recent():
 def test_radar_fileindex_grid_hourly_historical():
 
     file_index = create_fileindex_radar(
-        parameter=RadarParameter.RADOLAN_GRID,
+        parameter=RadarParameter.RADOLAN_CDC,
         time_resolution=TimeResolution.HOURLY,
         period_type=PeriodType.HISTORICAL,
     )
@@ -217,7 +217,7 @@ def test_radar_fileindex_grid_hourly_historical():
 def test_radar_fileindex_grid_5minutes():
 
     file_index = create_fileindex_radar(
-        parameter=RadarParameter.RADOLAN_GRID,
+        parameter=RadarParameter.RADOLAN_CDC,
         time_resolution=TimeResolution.MINUTE_5,
     )
 

wetterdienst/__init__.py

@@ -12,6 +12,7 @@
     get_nearby_stations_by_distance,
 )
 from wetterdienst.dwd.radar.api import DWDRadarRequest
+from wetterdienst.dwd.radar.metadata import RadarParameter
 
 # Single-sourcing the package version
 # https://cjolowicz.github.io/posts/hypermodern-python-06-ci-cd/

wetterdienst/dwd/radar/access.py

@@ -59,7 +59,7 @@ def collect_radar_data(
         list of tuples of a datetime and the corresponding file in bytes
     """
 
-    if parameter == RadarParameter.RADOLAN_GRID:
+    if parameter == RadarParameter.RADOLAN_CDC:
 
         if time_resolution not in (
             TimeResolution.HOURLY,
@@ -95,9 +95,6 @@ def _collect_generic_radar_data(
     """
     Collect raw radar data for COMPOSITE and SITES.
 
-    Remark: As of now, only the LATEST file (like "raa00-dx_10132-latest-boo---bin")
-            will be acquired.
-
     Args:
         parameter: What type of radar data should be collected
         date_times: list of datetime objects for which RADOLAN shall be acquired
@@ -181,7 +178,7 @@ def _collect_radolan_grid_data(
     folder: Union[str, Path] = DWD_FOLDER_MAIN,
 ) -> List[Tuple[datetime, BytesIO]]:
     """
-    Collect RADOLAN_GRID data for given datetimes and time resolution.
+    Collect RADOLAN_CDC data for given datetimes and time resolution.
     Additionally, the file can be written to a local folder and read from there as well.
 
     Args:
@@ -202,7 +199,7 @@ def _collect_radolan_grid_data(
                     (
                         date_time,
                         restore_radar_data(
-                            RadarParameter.RADOLAN_GRID,
+                            RadarParameter.RADOLAN_CDC,
                             date_time,
                             time_resolution,
                             folder,
@@ -232,7 +229,7 @@ def _collect_radolan_grid_data(
 
         if write_file:
             store_radar_data(
-                RadarParameter.RADOLAN_GRID, date_time_and_file, time_resolution, folder
+                RadarParameter.RADOLAN_CDC, date_time_and_file, time_resolution, folder
             )
 
     return data

wetterdienst/dwd/radar/api.py

@@ -52,9 +52,9 @@ def __init__(
                                 giving a start and end date
         :param time_resolution: Time resolution enumeration,
                                 either daily or hourly 5 minutes.
-                                Only required for radar_parameter == RADOLAN_GRID.
+                                Only required for radar_parameter == RADOLAN_CDC.
         :param period_type:     period type of PeriodType enumeration
-                                Only required for radar_parameter == RADOLAN_GRID.
+                                Only required for radar_parameter == RADOLAN_CDC.
         :param prefer_local:    Radar data should rather be loaded from disk, for
                                 processing purposes
         :param write_file:      File should be stored on drive
@@ -71,7 +71,7 @@ def __init__(
 
         # Sanity checks.
         if (
-            self.radar_parameter == RadarParameter.RADOLAN_GRID
+            self.radar_parameter == RadarParameter.RADOLAN_CDC
             and time_resolution
             not in (
                 TimeResolution.HOURLY,
@@ -90,10 +90,10 @@ def __init__(
                 time_resolution, TimeResolution
             )
 
-        # Run on of two indexing variants, either for RADOLAN_GRID or generic RADOLAN.
+        # Run on of two indexing variants, either for RADOLAN_CDC or generic RADOLAN.
         # TODO: File index will be made twice,
         #  consider sharing it with ``collect_data``.
-        if self.radar_parameter == RadarParameter.RADOLAN_GRID:
+        if self.radar_parameter == RadarParameter.RADOLAN_CDC:
             file_index = create_fileindex_radolan_grid(self.time_resolution)
         else:
             file_index = create_fileindex_radar(
@@ -107,7 +107,7 @@ def __init__(
 
         self.__build_date_times(file_index, date_times, start_date, end_date)
 
-        if self.radar_parameter == RadarParameter.RADOLAN_GRID:
+        if self.radar_parameter == RadarParameter.RADOLAN_CDC:
             self.date_times = self.date_times.dt.floor(freq="H") + pd.Timedelta(
                 minutes=50
             )
@@ -165,7 +165,7 @@ def __build_date_times(
         if date_times == RadarDate.LATEST.value:
 
             # Try to get latest file by using datetime column.
-            # TODO: This is only implemented for RADOLAN_GRID for now.
+            # TODO: This is only implemented for RADOLAN_CDC for now.
             try:
                 self.date_times = pd.Series(
                     file_index[DWDMetaColumns.DATETIME.value][-1:]

wetterdienst/dwd/radar/index.py

@@ -127,7 +127,7 @@ def create_fileindex_radolan_grid(time_resolution: TimeResolution) -> pd.DataFra
     file_index = pd.concat(
         [
             create_fileindex_radar(
-                parameter=RadarParameter.RADOLAN_GRID,
+                parameter=RadarParameter.RADOLAN_CDC,
                 time_resolution=time_resolution,
                 period_type=period_type,
             )
@@ -190,7 +190,7 @@ def build_path_to_parameter(
     Returns:
         indexing file path relative to climate observations path
     """
-    if parameter == RadarParameter.RADOLAN_GRID:
+    if parameter == RadarParameter.RADOLAN_CDC:
         if time_resolution == TimeResolution.MINUTE_5:
             # See also page 4 on
             # https://opendata.dwd.de/climate_environment/CDC/help/RADOLAN/Unterstuetzungsdokumente/Unterstuetzungsdokumente-Verwendung_von_RADOLAN-Produkten_im_ASCII-GIS-Rasterformat_in_GIS.pdf  # noqa:E501,B950

wetterdienst/dwd/radar/metadata.py

@@ -57,7 +57,7 @@ class RadarParameter(Enum):
     # https://opendata.dwd.de/climate_environment/CDC/grids_germany/daily/radolan/
     # https://opendata.dwd.de/climate_environment/CDC/grids_germany/hourly/radolan/
     # https://opendata.dwd.de/climate_environment/CDC/grids_germany/5_minutes/radolan/
-    RADOLAN_GRID = "radolan_grid"
+    RADOLAN_CDC = "radolan_grid"
 
 
 RADAR_PARAMETERS_COMPOSITES = [