NEXRAD Level 2#

[1]:
import cmweather  # noqa
import xarray as xr
from open_radar_data import DATASETS

import xradar as xd

Download#

Fetching NEXRAD Level2 radar data file from open-radar-data repository.

[2]:
filename = DATASETS.fetch("KATX20130717_195021_V06")
Downloading file 'KATX20130717_195021_V06' from 'https://github.com/openradar/open-radar-data/raw/main/data/KATX20130717_195021_V06' to '/home/docs/.cache/open-radar-data'.

xr.open_dataset#

Making use of the xarray nexradlevel2 backend. We also need to provide the group. Note, that we are using CfRadial2 group access pattern.

[3]:
ds = xr.open_dataset(filename, group="sweep_0", engine="nexradlevel2")
display(ds)
<xarray.Dataset> Size: 42MB
Dimensions:            (azimuth: 720, range: 1832)
Coordinates:
    elevation          (azimuth) float64 6kB ...
    time               (azimuth) datetime64[ns] 6kB ...
  * range              (range) float32 7kB 2.125e+03 2.375e+03 ... 4.599e+05
    longitude          float64 8B ...
    latitude           float64 8B ...
    altitude           int64 8B ...
  * azimuth            (azimuth) float64 6kB 0.2582 0.7526 1.272 ... 359.3 359.8
Data variables:
    DBZH               (azimuth, range) float64 11MB ...
    ZDR                (azimuth, range) float64 11MB ...
    PHIDP              (azimuth, range) float64 11MB ...
    RHOHV              (azimuth, range) float64 11MB ...
    sweep_mode         <U20 80B ...
    sweep_number       int64 8B ...
    prt_mode           <U7 28B ...
    follow_mode        <U7 28B ...
    sweep_fixed_angle  float64 8B ...
Attributes:
    instrument_name:  KATX
    scan_name:        VCP-11
[4]:
ds
[4]:
<xarray.Dataset> Size: 42MB
Dimensions:            (azimuth: 720, range: 1832)
Coordinates:
    elevation          (azimuth) float64 6kB ...
    time               (azimuth) datetime64[ns] 6kB ...
  * range              (range) float32 7kB 2.125e+03 2.375e+03 ... 4.599e+05
    longitude          float64 8B ...
    latitude           float64 8B ...
    altitude           int64 8B ...
  * azimuth            (azimuth) float64 6kB 0.2582 0.7526 1.272 ... 359.3 359.8
Data variables:
    DBZH               (azimuth, range) float64 11MB ...
    ZDR                (azimuth, range) float64 11MB ...
    PHIDP              (azimuth, range) float64 11MB ...
    RHOHV              (azimuth, range) float64 11MB ...
    sweep_mode         <U20 80B ...
    sweep_number       int64 8B ...
    prt_mode           <U7 28B ...
    follow_mode        <U7 28B ...
    sweep_fixed_angle  float64 8B ...
Attributes:
    instrument_name:  KATX
    scan_name:        VCP-11
[5]:
import numpy as np

np.testing.assert_almost_equal(ds.sweep_fixed_angle.values, 0.4833984)

Plot Time vs. Azimuth#

[6]:
ds.azimuth.plot()
[6]:
[<matplotlib.lines.Line2D at 0x7f8a64007110>]
../_images/notebooks_NexradLevel2_9_1.png

Plot Range vs. Time#

We need to sort by time and specify the y-coordinate.

[7]:
ds.DBZH.sortby("time").plot(y="time", cmap="HomeyerRainbow")
[7]:
<matplotlib.collections.QuadMesh at 0x7f8a63e85220>
../_images/notebooks_NexradLevel2_11_1.png

Plot Range vs. Azimuth#

[8]:
ds.DBZH.plot(cmap="HomeyerRainbow")
[8]:
<matplotlib.collections.QuadMesh at 0x7f8a6414bec0>
../_images/notebooks_NexradLevel2_13_1.png

backend_kwargs#

Beside first_dim there are several additional backend_kwargs for the nexradlevel2 backend, which handle different aspects of angle alignment. This comes into play, when azimuth and/or elevation arrays are not evenly spacend and other issues.

[9]:
help(xd.io.NexradLevel2BackendEntrypoint)
Help on class NexradLevel2BackendEntrypoint in module xradar.io.backends.nexrad_level2:

class NexradLevel2BackendEntrypoint(xarray.backends.common.BackendEntrypoint)
 |  Xarray BackendEntrypoint for NEXRAD Level2 Data
 |
 |  Method resolution order:
 |      NexradLevel2BackendEntrypoint
 |      xarray.backends.common.BackendEntrypoint
 |      builtins.object
 |
 |  Methods defined here:
 |
 |  open_dataset(self, filename_or_obj, *, mask_and_scale=True, decode_times=True, concat_characters=True, decode_coords=True, drop_variables=None, use_cftime=None, decode_timedelta=None, group=None, lock=None, first_dim='auto', reindex_angle=False, fix_second_angle=False, site_coords=True, optional=True)
 |      Backend open_dataset method used by Xarray in :py:func:`~xarray.open_dataset`.
 |
 |  ----------------------------------------------------------------------
 |  Data and other attributes defined here:
 |
 |  __annotations__ = {}
 |
 |  description = 'Open NEXRAD Level2 files in Xarray'
 |
 |  open_dataset_parameters = ('filename_or_obj', 'mask_and_scale', 'decod...
 |
 |  url = 'tbd'
 |
 |  ----------------------------------------------------------------------
 |  Methods inherited from xarray.backends.common.BackendEntrypoint:
 |
 |  __repr__(self) -> 'str'
 |      Return repr(self).
 |
 |  guess_can_open(self, filename_or_obj: 'str | os.PathLike[Any] | ReadBuffer | AbstractDataStore') -> 'bool'
 |      Backend open_dataset method used by Xarray in :py:func:`~xarray.open_dataset`.
 |
 |  open_datatree(self, filename_or_obj: 'str | os.PathLike[Any] | ReadBuffer | AbstractDataStore', *, drop_variables: 'str | Iterable[str] | None' = None) -> 'DataTree'
 |      Backend open_datatree method used by Xarray in :py:func:`~xarray.open_datatree`.
 |
 |  open_groups_as_dict(self, filename_or_obj: 'str | os.PathLike[Any] | ReadBuffer | AbstractDataStore', *, drop_variables: 'str | Iterable[str] | None' = None) -> 'dict[str, Dataset]'
 |      Opens a dictionary mapping from group names to Datasets.
 |
 |      Called by :py:func:`~xarray.open_groups`.
 |      This function exists to provide a universal way to open all groups in a file,
 |      before applying any additional consistency checks or requirements necessary
 |      to create a `DataTree` object (typically done using :py:meth:`~xarray.DataTree.from_dict`).
 |
 |  ----------------------------------------------------------------------
 |  Data descriptors inherited from xarray.backends.common.BackendEntrypoint:
 |
 |  __dict__
 |      dictionary for instance variables
 |
 |  __weakref__
 |      list of weak references to the object

[10]:
ds = xr.open_dataset(filename, group="sweep_0", engine="nexradlevel2", first_dim="time")
display(ds)
<xarray.Dataset> Size: 42MB
Dimensions:            (time: 720, range: 1832)
Coordinates:
    elevation          (time) float64 6kB ...
  * time               (time) datetime64[ns] 6kB 2013-07-17T19:50:21.652000 ....
  * range              (range) float32 7kB 2.125e+03 2.375e+03 ... 4.599e+05
    longitude          float64 8B ...
    latitude           float64 8B ...
    altitude           int64 8B ...
    azimuth            (time) float64 6kB ...
Data variables:
    DBZH               (time, range) float64 11MB ...
    ZDR                (time, range) float64 11MB ...
    PHIDP              (time, range) float64 11MB ...
    RHOHV              (time, range) float64 11MB ...
    sweep_mode         <U20 80B ...
    sweep_number       int64 8B ...
    prt_mode           <U7 28B ...
    follow_mode        <U7 28B ...
    sweep_fixed_angle  float64 8B ...
Attributes:
    instrument_name:  KATX
    scan_name:        VCP-11

open_nexradlevel2_datatree#

The same works analoguous with the datatree loader. But additionally we can provide a sweep string, number or list.

[11]:
help(xd.io.open_nexradlevel2_datatree)
Help on function open_nexradlevel2_datatree in module xradar.io.backends.nexrad_level2:

open_nexradlevel2_datatree(filename_or_obj, mask_and_scale=True, decode_times=True, concat_characters=True, decode_coords=True, drop_variables=None, use_cftime=None, decode_timedelta=None, sweep=None, first_dim='auto', reindex_angle=False, fix_second_angle=False, site_coords=True, optional=True, lock=None, **kwargs)
    Open a NEXRAD Level2 dataset as an `xarray.DataTree`.

    This function loads NEXRAD Level2 radar data into a DataTree structure, which
    organizes radar sweeps as separate nodes. Provides options for decoding time
    and applying various transformations to the data.

    Parameters
    ----------
    filename_or_obj : str, Path, file-like, or DataStore
        The path or file-like object representing the radar file.
        Path-like objects are interpreted as local or remote paths.

    mask_and_scale : bool, optional
        If True, replaces values in the dataset that match `_FillValue` with NaN
        and applies scale and offset adjustments. Default is True.

    decode_times : bool, optional
        If True, decodes time variables according to CF conventions. Default is True.

    concat_characters : bool, optional
        If True, concatenates character arrays along the last dimension, forming
        string arrays. Default is True.

    decode_coords : bool, optional
        If True, decodes the "coordinates" attribute to identify coordinates in the
        resulting dataset. Default is True.

    drop_variables : str or list of str, optional
        Specifies variables to exclude from the dataset. Useful for removing problematic
        or inconsistent variables. Default is None.

    use_cftime : bool, optional
        If True, uses cftime objects to represent time variables; if False, uses
        `np.datetime64` objects. If None, chooses the best format automatically.
        Default is None.

    decode_timedelta : bool, optional
        If True, decodes variables with units of time (e.g., seconds, minutes) into
        timedelta objects. If False, leaves them as numeric values. Default is None.

    sweep : int or list of int, optional
        Sweep numbers to extract from the dataset. If None, extracts all sweeps into
        a list. Default is the first sweep.

    first_dim : {"time", "auto"}, optional
        Defines the first dimension for each sweep. If "time," uses time as the
        first dimension. If "auto," determines the first dimension based on the sweep
        type (azimuth or elevation). Default is "auto."

    reindex_angle : bool or dict, optional
        Controls angle reindexing. If True or a dictionary, applies reindexing with
        specified settings (if given). Only used if `decode_coords=True`. Default is False.

    fix_second_angle : bool, optional
        If True, corrects errors in the second angle data, such as misaligned
        elevation or azimuth values. Default is False.

    site_coords : bool, optional
        Attaches radar site coordinates to the dataset if True. Default is True.

    optional : bool, optional
        If True, suppresses errors for optional dataset attributes, making them
        optional instead of required. Default is True.

    kwargs : dict
        Additional keyword arguments passed to `xarray.open_dataset`.

    Returns
    -------
    dtree : xarray.DataTree
        An `xarray.DataTree` representing the radar data organized by sweeps.

[12]:
dtree = xd.io.open_nexradlevel2_datatree(filename, sweep=4)
display(dtree)
<xarray.DatasetView> Size: 232B
Dimensions:              ()
Data variables:
    volume_number        int64 8B 0
    platform_type        <U5 20B 'fixed'
    instrument_type      <U5 20B 'radar'
    time_coverage_start  <U20 80B '2013-07-17T19:51:38Z'
    time_coverage_end    <U20 80B '2013-07-17T19:52:00Z'
    longitude            float64 8B -122.5
    altitude             int64 8B 195
    latitude             float64 8B 48.19
Attributes:
    Conventions:      None
    instrument_name:  KATX
    version:          None
    title:            None
    institution:      None
    references:       None
    source:           None
    history:          None
    comment:          im/exported using xradar
    scan_name:        VCP-11

Plot Sweep Range vs. Time#

[13]:
dtree["sweep_4"].ds.DBZH.sortby("time").plot(y="time", cmap="HomeyerRainbow")
[13]:
<matplotlib.collections.QuadMesh at 0x7f8a5aca7cb0>
../_images/notebooks_NexradLevel2_21_1.png

Plot Sweep Range vs. Azimuth#

[14]:
dtree["sweep_4"].ds.DBZH.plot(cmap="HomeyerRainbow")
[14]:
<matplotlib.collections.QuadMesh at 0x7f8a47d81970>
../_images/notebooks_NexradLevel2_23_1.png
[15]:
dtree = xd.io.open_nexradlevel2_datatree(filename, sweep="sweep_8")
display(dtree)
<xarray.DatasetView> Size: 232B
Dimensions:              ()
Data variables:
    volume_number        int64 8B 0
    platform_type        <U5 20B 'fixed'
    instrument_type      <U5 20B 'radar'
    time_coverage_start  <U20 80B '2013-07-17T19:53:05Z'
    time_coverage_end    <U20 80B '2013-07-17T19:53:25Z'
    longitude            float64 8B -122.5
    altitude             int64 8B 195
    latitude             float64 8B 48.19
Attributes:
    Conventions:      None
    instrument_name:  KATX
    version:          None
    title:            None
    institution:      None
    references:       None
    source:           None
    history:          None
    comment:          im/exported using xradar
    scan_name:        VCP-11
[16]:
dtree = xd.io.open_nexradlevel2_datatree(filename, sweep=[0, 1, 8])
display(dtree)
<xarray.DatasetView> Size: 232B
Dimensions:              ()
Data variables:
    volume_number        int64 8B 0
    platform_type        <U5 20B 'fixed'
    instrument_type      <U5 20B 'radar'
    time_coverage_start  <U20 80B '2013-07-17T19:50:21Z'
    time_coverage_end    <U20 80B '2013-07-17T19:53:25Z'
    longitude            float64 8B -122.5
    altitude             int64 8B 195
    latitude             float64 8B 48.19
Attributes:
    Conventions:      None
    instrument_name:  KATX
    version:          None
    title:            None
    institution:      None
    references:       None
    source:           None
    history:          None
    comment:          im/exported using xradar
    scan_name:        VCP-11
[17]:
dtree["sweep_0"]["sweep_fixed_angle"].values
[17]:
array(0.48339844)
[18]:
dtree["sweep_8"]["sweep_fixed_angle"].values
[18]:
array(6.19628906)
[19]:
dtree = xd.io.open_nexradlevel2_datatree(
    filename,
)
display(dtree)
<xarray.DatasetView> Size: 232B
Dimensions:              ()
Data variables:
    volume_number        int64 8B 0
    platform_type        <U5 20B 'fixed'
    instrument_type      <U5 20B 'radar'
    time_coverage_start  <U20 80B '2013-07-17T19:50:21Z'
    time_coverage_end    <U20 80B '2013-07-17T19:55:11Z'
    longitude            float64 8B -122.5
    altitude             int64 8B 195
    latitude             float64 8B 48.19
Attributes:
    Conventions:      None
    instrument_name:  KATX
    version:          None
    title:            None
    institution:      None
    references:       None
    source:           None
    history:          None
    comment:          im/exported using xradar
    scan_name:        VCP-11
[20]:
dtree["sweep_1"]
[20]:
<xarray.DatasetView> Size: 21MB
Dimensions:            (azimuth: 720, range: 1192)
Coordinates:
    elevation          (azimuth) float64 6kB ...
    time               (azimuth) datetime64[ns] 6kB ...
  * range              (range) float32 5kB 2.125e+03 2.375e+03 ... 2.999e+05
    longitude          float64 8B -122.5
    latitude           float64 8B 48.19
    altitude           int64 8B 195
  * azimuth            (azimuth) float64 6kB 0.2499 0.7938 1.252 ... 359.2 359.8
Data variables:
    DBZH               (azimuth, range) float64 7MB ...
    VRADH              (azimuth, range) float64 7MB ...
    WRADH              (azimuth, range) float64 7MB ...
    sweep_mode         <U20 80B 'azimuth_surveillance'
    sweep_number       int64 8B ...
    prt_mode           <U7 28B ...
    follow_mode        <U7 28B ...
    sweep_fixed_angle  float64 8B ...
[ ]: