pyodim 0.4__tar.gz

pyodim-0.4/.gitignore

@@ -0,0 +1,130 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+.vscode/settings.json

pyodim-0.4/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 Valentin Louf
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pyodim-0.4/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.1
+Name: pyodim
+Version: 0.4
+Summary: An ODIM hdf5 file reader.
+Home-page: https://github.com/vlouf/pyodim
+Author: Valentin Louf
+Author-email: valentin.louf@bom.gov.au
+Project-URL: Bug Reports, https://github.com/vlouf/pyodim/issues
+Project-URL: Source, https://github.com/vlouf/pyodim/
+Keywords: odim h5 file reader
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+
+# PYODIM
+
+A simple ODIM H5 (Opera Data Information Model - Hierarchical Data Format 
+version 5) radar reader in Python. It outputs the radar date in an xarray 
+Dataset. The goal is to be as barebone as possible while providing an xarray, 
+so that it can easily scale up (production) or just a very lean reader for 
+quicklooks into the data.
+
+## Example
+
+```python
+
+import pyodim
+
+filename = "/path/to/radar/file.h5"
+rset = pyodim.read_odim(filename, lazy_load=True)  # Lazy load does not load the data in memory to save time if you are interested in only a specific sweep
+radar = rset[0].compute()  # All sweeps are in a list (elevation ascending), so the 1st item of the list is the bottom sweep.
+print(radar)
+```
+
+This code will output the radar data for the first sweep (lowest elevation 
+scan) in the radar file as an xarray Dataset, for example:
+
+```python
+<xarray.Dataset>
+Dimensions:     (azimuth: 360, range: 1283, elevation: 1, time: 360)
+Coordinates:
+  * range       (range) float32 125.0 375.0 625.0 ... 3.204e+05 3.206e+05
+  * azimuth     (azimuth) float32 0.01111 1.011 2.011 ... 357.0 358.0 359.0
+  * elevation   (elevation) float32 0.5
+  * time        (time) datetime64[ns] 2024-01-16T02:49:29.337047353 ... 2024-...
+Data variables: (12/17)
+    DBZH        (azimuth, range) float64 nan nan nan nan nan ... nan nan nan nan
+    SNRH        (azimuth, range) float64 nan nan nan nan nan ... nan nan nan nan    
+    VRADH       (azimuth, range) float64 nan nan nan nan nan ... nan nan nan nan
+    WRADH       (azimuth, range) float64 nan nan nan nan nan ... nan nan nan nan
+    KDP         (azimuth, range) float64 nan nan nan nan nan ... nan nan nan nan
+    ...          ...
+    x           (azimuth, range) float32 0.02424 0.07271 ... -5.595e+03
+    y           (azimuth, range) float32 125.0 375.0 ... 3.203e+05 3.206e+05
+    z           (azimuth, range) float32 45.09 47.27 ... 2.84e+03 2.842e+03
+    longitude   (azimuth, range) float32 144.8 144.8 144.8 ... 144.7 144.7 144.7
+    latitude    (azimuth, range) float32 -37.85 -37.85 -37.85 ... -34.97 -34.96
+Attributes: (12/15)
+    Conventions:  ODIM_H5/V2_4
+    latitude:     -37.85200119018555
+    longitude:    144.75199890136722
+    height:       44.0
+    date:         2024-01-16T02:45:21
+    object:       PVOL
+    ...           ...
+    beamwV:       1.0
+    wavelength:   10.489999771118164
+    NI:           36.5052
+    highprf:      696.0
+    start_time:   20240116_024928
+    end_time:     20240116_024958
+```
+
+PYODIM reads the ODIM radar data and metadata. It also provides some quality of 
+life feature like automatically creating the x, y, z and latitude/longitude 
+coordinates for all radar gates (using the azimuthal equidistant - `aeqd` - projection). By 
+default it uses `dask.delayed` to *lazily* load the data, meaning that it will 
+not actually load all the sweeps in memory, as for many applications we often 
+don't need all the radar sweeps. Instead, by calling the `.compute()` method 
+like in the example above, PYODIM will only read and load in memory the sweep 
+that you want, saving time. If you want to read all the sweeps at once in a 
+list, then just set `lazy_load=False`.
+
+## Dependencies
+
+Mandatory:
+- [numpy][1]
+- [xarray][2]
+- [pyproj][3]
+- [dask][4]
+
+And optionally (it will automatically populate the fields metadata using pyart 
+if available): 
+- [Py-ART][5] 
+
+[1]: http://www.scipy.org/
+[2]: http://numba.pydata.org
+[3]: https://pypi.org/project/pyproj/
+[4]: https://www.dask.org/
+[5]: https://github.com/ARM-DOE/pyart

pyodim-0.4/README.md

@@ -0,0 +1,86 @@
+# PYODIM
+
+A simple ODIM H5 (Opera Data Information Model - Hierarchical Data Format 
+version 5) radar reader in Python. It outputs the radar date in an xarray 
+Dataset. The goal is to be as barebone as possible while providing an xarray, 
+so that it can easily scale up (production) or just a very lean reader for 
+quicklooks into the data.
+
+## Example
+
+```python
+
+import pyodim
+
+filename = "/path/to/radar/file.h5"
+rset = pyodim.read_odim(filename, lazy_load=True)  # Lazy load does not load the data in memory to save time if you are interested in only a specific sweep
+radar = rset[0].compute()  # All sweeps are in a list (elevation ascending), so the 1st item of the list is the bottom sweep.
+print(radar)
+```
+
+This code will output the radar data for the first sweep (lowest elevation 
+scan) in the radar file as an xarray Dataset, for example:
+
+```python
+<xarray.Dataset>
+Dimensions:     (azimuth: 360, range: 1283, elevation: 1, time: 360)
+Coordinates:
+  * range       (range) float32 125.0 375.0 625.0 ... 3.204e+05 3.206e+05
+  * azimuth     (azimuth) float32 0.01111 1.011 2.011 ... 357.0 358.0 359.0
+  * elevation   (elevation) float32 0.5
+  * time        (time) datetime64[ns] 2024-01-16T02:49:29.337047353 ... 2024-...
+Data variables: (12/17)
+    DBZH        (azimuth, range) float64 nan nan nan nan nan ... nan nan nan nan
+    SNRH        (azimuth, range) float64 nan nan nan nan nan ... nan nan nan nan    
+    VRADH       (azimuth, range) float64 nan nan nan nan nan ... nan nan nan nan
+    WRADH       (azimuth, range) float64 nan nan nan nan nan ... nan nan nan nan
+    KDP         (azimuth, range) float64 nan nan nan nan nan ... nan nan nan nan
+    ...          ...
+    x           (azimuth, range) float32 0.02424 0.07271 ... -5.595e+03
+    y           (azimuth, range) float32 125.0 375.0 ... 3.203e+05 3.206e+05
+    z           (azimuth, range) float32 45.09 47.27 ... 2.84e+03 2.842e+03
+    longitude   (azimuth, range) float32 144.8 144.8 144.8 ... 144.7 144.7 144.7
+    latitude    (azimuth, range) float32 -37.85 -37.85 -37.85 ... -34.97 -34.96
+Attributes: (12/15)
+    Conventions:  ODIM_H5/V2_4
+    latitude:     -37.85200119018555
+    longitude:    144.75199890136722
+    height:       44.0
+    date:         2024-01-16T02:45:21
+    object:       PVOL
+    ...           ...
+    beamwV:       1.0
+    wavelength:   10.489999771118164
+    NI:           36.5052
+    highprf:      696.0
+    start_time:   20240116_024928
+    end_time:     20240116_024958
+```
+
+PYODIM reads the ODIM radar data and metadata. It also provides some quality of 
+life feature like automatically creating the x, y, z and latitude/longitude 
+coordinates for all radar gates (using the azimuthal equidistant - `aeqd` - projection). By 
+default it uses `dask.delayed` to *lazily* load the data, meaning that it will 
+not actually load all the sweeps in memory, as for many applications we often 
+don't need all the radar sweeps. Instead, by calling the `.compute()` method 
+like in the example above, PYODIM will only read and load in memory the sweep 
+that you want, saving time. If you want to read all the sweeps at once in a 
+list, then just set `lazy_load=False`.
+
+## Dependencies
+
+Mandatory:
+- [numpy][1]
+- [xarray][2]
+- [pyproj][3]
+- [dask][4]
+
+And optionally (it will automatically populate the fields metadata using pyart 
+if available): 
+- [Py-ART][5] 
+
+[1]: http://www.scipy.org/
+[2]: http://numba.pydata.org
+[3]: https://pypi.org/project/pyproj/
+[4]: https://www.dask.org/
+[5]: https://github.com/ARM-DOE/pyart

pyodim-0.4/pyodim/__init__.py

@@ -0,0 +1 @@
+from .pyodim import read_odim

pyodim-0.4/pyodim/__version__.py

@@ -0,0 +1 @@
+__version__ = '0.3'

pyodim-0.4/pyodim/pyodim.py

@@ -0,0 +1,511 @@
+"""
+Natively reading ODIM H5 radar files in Python.
+
+@title: pyodim
+@author: Valentin Louf <valentin.louf@bom.gov.au>
+@institutions: Bureau of Meteorology and Monash University.
+@creation: 21/01/2020
+@date: 19/02/2021
+
+.. autosummary::
+    :toctree: generated/
+
+    _to_str
+    buffer
+    cartesian_to_geographic
+    check_nyquist
+    coord_from_metadata
+    field_metadata
+    generate_timestamp
+    get_dataset_metadata
+    get_root_metadata
+    radar_coordinates_to_xyz
+    read_odim_slice
+    read_odim
+"""
+import datetime
+import traceback
+from typing import Dict, List, Tuple
+
+import dask
+import h5py
+import pyproj
+import pandas as pd
+import numpy as np
+import xarray as xr
+
+
+def _to_str(t: bytes) -> str:
+    """
+    Transform binary into string.
+    """
+    return t.decode("utf-8")
+
+
+def buffer(func):
+    """
+    Decorator to catch and kill error message. Almost want to name the function
+    dont_fail.
+    """
+
+    def wrapper(*args, **kwargs):
+        try:
+            rslt = func(*args, **kwargs)
+        except Exception:
+            traceback.print_exc()
+            rslt = None
+        return rslt
+
+    return wrapper
+
+
+def cartesian_to_geographic(x: np.ndarray, y: np.ndarray, lon0: float, lat0: float) -> Tuple[np.ndarray, np.ndarray]:
+    """
+    Transform cartesian coordinates to lat/lon using the Azimuth Equidistant
+    projection.
+
+    Parameters:
+    ===========
+    x: ndarray
+        x-axis cartesian coordinates.
+    y: ndarray
+        y-axis cartesian coordinates. Same dimension as x
+    lon0: float
+        Radar site longitude.
+    lat0: float
+        Radar site latitude.
+
+    Returns:
+    lon: ndarray
+        Longitude of each gate.
+    lat: ndarray
+        Latitude of each gate.
+    """
+    georef = pyproj.Proj(f"+proj=aeqd +lon_0={lon0} +lat_0={lat0} +ellps=WGS84")
+    lon, lat = georef(x, y, inverse=True)
+    lon = lon.astype(np.float32)
+    lat = lat.astype(np.float32)
+    return lon, lat
+
+
+@buffer
+def check_nyquist(dset: xr.Dataset) -> None:
+    """
+    Check if the dataset Nyquist velocity corresponds to the PRF information.
+    """
+    wavelength = dset.attrs["wavelength"]
+    prf = dset.attrs["highprf"]
+    nyquist = dset.attrs["NI"]
+    ny_int = 1e-2 * prf * wavelength / 4
+
+    assert np.abs(nyquist - ny_int) < 0.5, "Nyquist not consistent with PRF"
+
+
+def coord_from_metadata(metadata: Dict) -> Tuple[np.ndarray, np.ndarray, np.ndarray]:
+    """
+    Create the radar coordinates from the ODIM H5 metadata specification.
+
+    Parameter:
+    ==========
+    metadata: dict()
+        Metadata dictionnary containing the specific ODIM H5 keys: astart,
+        nrays, nbins, rstart, rscale, elangle.
+
+    Returns:
+    ========
+    r: ndarray<nbins>
+        Sweep range
+    azimuth: ndarray<nrays>
+        Sweep azimuth
+    elev: float
+        Sweep elevation
+    """
+    da = 360 / metadata["nrays"]
+    azimuth = np.linspace(metadata["astart"] + da / 2, 360 - da, metadata["nrays"], dtype=np.float32)
+
+    # rstart is in KM !!! STUPID.
+    rstart_center = 1e3 * metadata["rstart"] + metadata["rscale"] / 2
+    r = np.arange(
+        rstart_center, rstart_center + metadata["nbins"] * metadata["rscale"], metadata["rscale"], dtype=np.float32
+    )
+
+    elev = np.array([metadata["elangle"]], dtype=np.float32)
+    return r, azimuth, elev
+
+
+def field_metadata(quantity_name: str) -> Dict:
+    """
+    Populate metadata for common fields using Py-ART get_metadata() function.
+    (Optionnal).
+
+    Parameter:
+    ==========
+    quantity_name: str
+        ODIM H5 quantity attribute name.
+
+    Returns:
+    ========
+    attrs: dict()
+        Metadata dictionnary.
+    """
+    try:
+        from pyart.config import get_metadata
+    except Exception:
+        return {}
+    ODIM_H5_FIELD_NAMES = {
+        "TH": "total_power",  # uncorrected reflectivity, horizontal
+        "TV": "total_power",  # uncorrected reflectivity, vertical
+        "DBZH": "reflectivity",  # corrected reflectivity, horizontal
+        "DBZH_CLEAN": "reflectivity",  # corrected reflectivity, horizontal
+        "DBZV": "reflectivity",  # corrected reflectivity, vertical
+        "CLASS": "hydrometeor_classification",
+        "ZDR": "differential_reflectivity",  # differential reflectivity
+        "RHOHV": "cross_correlation_ratio",
+        "LDR": "linear_polarization_ratio",
+        "PHIDP": "differential_phase",
+        "KDP": "specific_differential_phase",
+        "SQI": "normalized_coherent_power",
+        "SNR": "signal_to_noise_ratio",
+        "SNRH": "signal_to_noise_ratio",
+        "VRAD": "velocity",  # radial velocity, marked for deprecation in ODIM HDF5 2.2
+        "VRADH": "velocity",  # radial velocity, horizontal polarisation
+        "VRADDH": "corrected_velocity",  # radial velocity, horizontal polarisation
+        "VRADV": "velocity",  # radial velocity, vertical polarisation
+        "WRAD": "spectrum_width",
+        "QIND": "quality_index",
+    }
+
+    try:
+        fname = ODIM_H5_FIELD_NAMES[quantity_name]
+        attrs = get_metadata(fname)
+        attrs.pop("coordinates")
+    except KeyError:
+        return {}
+
+    return attrs
+
+
+def generate_timestamp(stime: str, etime: str, nrays: int, a1gate: int) -> np.ndarray:
+    """
+    Generate timestamp for each ray.
+
+    Parameters:
+    ===========
+    stime: str
+        Sweep starting time.
+    etime:
+        Sweep ending time.
+    nrays: int
+        Number of rays in sweep.
+    a1gate: int
+        Azimuth of the ray measured first by the radar.
+
+    Returns:
+    ========
+    trange: Timestamp<nrays>
+        Timestamp for each ray.
+    """
+    sdtime = datetime.datetime.strptime(stime, "%Y%m%d_%H%M%S")
+    edtime = datetime.datetime.strptime(etime, "%Y%m%d_%H%M%S")
+    trange = pd.date_range(sdtime, edtime, nrays)
+
+    return np.roll(trange, a1gate)
+
+
+def get_dataset_metadata(hfile, dataset: str = "dataset1") -> Tuple[Dict, Dict]:
+    """
+    Get the dataset metadata of the ODIM H5 file.
+
+    Parameters:
+    ===========
+    hfile: h5py.File
+        H5 file identifier.
+    dataset: str
+        Key of the dataset for which to extract the metadata
+
+    Returns:
+    ========
+    metadata: dict
+        General metadata of the dataset.
+    coordinates_metadata: dict
+        Coordinates-specific metadata.
+    """
+    metadata = dict()
+    coordinates_metadata = dict()
+    # General metadata
+    for k in ["NI", "highprf", "product"]:
+        try:
+            metadata[k] = hfile[f"/{dataset}/how"].attrs[k]
+        except Exception:
+            pass
+
+    sdate = _to_str(hfile[f"/{dataset}/what"].attrs["startdate"])
+    stime = _to_str(hfile[f"/{dataset}/what"].attrs["starttime"])
+    try:
+        edate = _to_str(hfile[f"/{dataset}/what"].attrs["enddate"])
+        etime = _to_str(hfile[f"/{dataset}/what"].attrs["endtime"])
+    except Exception:
+        edate = sdate
+        etime = stime
+    metadata["start_time"] = f"{sdate}_{stime}"
+    metadata["end_time"] = f"{edate}_{etime}"
+
+    # Coordinates:
+    try:
+        coordinates_metadata["astart"] = hfile[f"/{dataset}/how"].attrs["astart"]
+    except KeyError:
+        # Optional coordinates (!).
+        coordinates_metadata["astart"] = 0
+    coordinates_metadata["a1gate"] = hfile[f"/{dataset}/where"].attrs["a1gate"]
+    coordinates_metadata["nrays"] = hfile[f"/{dataset}/where"].attrs["nrays"]
+
+    coordinates_metadata["rstart"] = hfile[f"/{dataset}/where"].attrs["rstart"]
+    coordinates_metadata["rscale"] = hfile[f"/{dataset}/where"].attrs["rscale"]
+    coordinates_metadata["nbins"] = hfile[f"/{dataset}/where"].attrs["nbins"]
+
+    coordinates_metadata["elangle"] = hfile[f"/{dataset}/where"].attrs["elangle"]
+
+    return metadata, coordinates_metadata
+
+
+def get_root_metadata(hfile) -> Dict:
+    """
+    Get the metadata at the root of the ODIM H5 file.
+
+    Parameters:
+    ===========
+    hfile: h5py.File
+        H5 file identifier.
+
+    Returns:
+    ========
+    rootmetadata: dict
+        Metadata at the root of the ODIM H5 file.
+    """
+    rootmetadata = {}
+    # Root
+    try:
+        rootmetadata["Conventions"] = _to_str(hfile.attrs["Conventions"])
+    except KeyError:
+        rootmetadata["Conventions"] = None
+
+    # Where
+    rootmetadata["latitude"] = hfile["/where"].attrs["lat"]
+    rootmetadata["longitude"] = hfile["/where"].attrs["lon"]
+    rootmetadata["height"] = hfile["/where"].attrs["height"]
+
+    # What
+    try:
+        sdate = _to_str(hfile["/what"].attrs["date"])
+        stime = _to_str(hfile["/what"].attrs["time"])
+        rootmetadata["date"] = datetime.datetime.strptime(sdate + stime, "%Y%m%d%H%M%S").isoformat()
+    except KeyError:
+        rootmetadata["date"] = None
+    for k in ["object", "source", "version"]:
+        try:
+            rootmetadata[k] = _to_str(hfile["/what"].attrs[k])
+        except KeyError:
+            pass
+
+    # How
+    for k in ["beamwH", "beamwV", "rpm", "wavelength"]:
+        try:
+            rootmetadata[k] = hfile["/how"].attrs[k]
+        except KeyError:
+            pass
+
+    try:
+        rootmetadata["copyright"] = _to_str(hfile["/how"].attrs["copyright"])
+    except KeyError:
+        pass
+
+    return rootmetadata
+
+
+def radar_coordinates_to_xyz(
+    r: np.ndarray, azimuth: np.ndarray, elevation: np.ndarray
+) -> Tuple[np.ndarray, np.ndarray, np.ndarray]:
+    """
+    Transform radar coordinates to cartesian coordinates.
+
+    Parameters:
+    ===========
+    r: ndarray<nbins>
+        Sweep range.
+    azimuth: ndarray<nrays>
+        Sweep azimuth.
+    elevation: float
+        Sweep elevation.
+
+    Returns:
+    ========
+    x, y, z: ndarray<nrays, nbins>
+        XYZ cartesian coordinates.
+    """
+    # To proper spherical coordinates.
+    theta = np.deg2rad(90 - elevation)
+    phi = 450 - azimuth
+    phi[phi >= 360] -= 360
+    phi = np.deg2rad(phi)
+
+    R, PHI = np.meshgrid(r, phi)
+    R = R.astype(np.float32)
+    PHI = PHI.astype(np.float32)
+
+    x = R * np.sin(theta) * np.cos(PHI)
+    y = R * np.sin(theta) * np.sin(PHI)
+    z = R * np.cos(theta)
+
+    return x, y, z
+
+
+def read_odim_slice(
+    odim_file: str, nslice: int = 0, include_fields: List = [], exclude_fields: List = [], check_NI: bool = False
+) -> xr.Dataset:
+    """
+    Read into an xarray dataset one sweep of the ODIM file.
+
+    Parameters:
+    ===========
+    odim_file: str
+        ODIM H5 filename.
+    nslice: int
+        Slice number we want to extract (start indexing at 0).
+    include_fields: list
+        Specific fields to be exclusively read.
+    exclude_fields: list
+        Specific fields to be excluded from reading.
+    check_NI: bool
+        Check NI parameter in ODIM file and compare it to the PRF.
+
+    Returns:
+    ========
+    dataset: xarray.Dataset
+        xarray dataset of one sweep of the ODIM file.
+    """
+    # if nslice == 0:
+    #     raise ValueError('Slice numbering start at 1.')
+    if type(include_fields) is not list:
+        raise TypeError("Argument `include_fields` should be a list")
+
+    with h5py.File(odim_file, "r") as hfile:
+        # Number of sweep in dataset
+        nsweep = len([k for k in hfile["/"].keys() if k.startswith("dataset")])
+        assert nslice <= nsweep, f"Wrong slice number asked. Only {nsweep} available."
+
+        # Order datasets by increasing elevations.
+        sweeps = dict()
+        for key in hfile["/"].keys():
+            if key.startswith("dataset"):
+                sweeps[key] = hfile[f"/{key}/where"].attrs["elangle"]
+
+        sorted_keys = sorted(sweeps, key=lambda k: sweeps[k])
+        rootkey = sorted_keys[nslice]
+
+        # Retrieve dataset metadata and coordinates metadata.
+        metadata, coordinates_metadata = get_dataset_metadata(hfile, rootkey)
+
+        dataset = xr.Dataset()
+        dataset.attrs = get_root_metadata(hfile)
+        dataset.attrs.update(metadata)
+        if check_NI:
+            try:
+                check_nyquist(dataset)
+            except AssertionError:
+                print("Nyquist not consistent with PRF")
+                pass
+
+        for datakey in hfile[f"/{rootkey}"].keys():
+            if not datakey.startswith("data"):
+                continue
+
+            try:
+                gain = hfile[f"/{rootkey}/{datakey}/what"].attrs["gain"]
+            except KeyError:
+                gain = 1
+            try:
+                nodata = hfile[f"/{rootkey}/{datakey}/what"].attrs["nodata"]
+            except KeyError:
+                nodata = np.NaN
+            try:
+                offset = hfile[f"/{rootkey}/{datakey}/what"].attrs["offset"]
+            except KeyError:
+                offset = 0
+            name = _to_str(hfile[f"/{rootkey}/{datakey}/what"].attrs["quantity"])
+            # Check if field should be read.
+            if len(include_fields) > 0:
+                if name not in include_fields:
+                    continue
+            if name in exclude_fields:
+                continue
+
+            dtype = hfile[f"/{rootkey}/{datakey}/data"][:].dtype
+            data_value = hfile[f"/{rootkey}/{datakey}/data"][:].astype(float).copy()
+            data_value[np.abs(data_value - nodata) <= 0.1] = np.NaN
+            data_value = gain * data_value + offset
+            data_value[np.abs(data_value - nodata * gain) <= 0.1] = np.NaN
+            dataset = dataset.merge({name: (("azimuth", "range"), data_value)})
+            dataset[name].attrs = field_metadata(name)
+            dataset[name].attrs["gain"] = np.float32(gain)
+            dataset[name].attrs["nodata"] = nodata
+            dataset[name].attrs["offset"] = offset
+            dataset[name].attrs["dtype"] = dtype
+
+    time = generate_timestamp(
+        metadata["start_time"], metadata["end_time"], coordinates_metadata["nrays"], coordinates_metadata["a1gate"]
+    )
+    r, azi, elev = coord_from_metadata(coordinates_metadata)
+    x, y, z = radar_coordinates_to_xyz(r, azi, elev)
+    longitude, latitude = cartesian_to_geographic(x, y, dataset.attrs["longitude"], dataset.attrs["latitude"])
+
+    dataset = dataset.merge(
+        {
+            "range": (("range"), r),
+            "azimuth": (("azimuth"), azi),
+            "elevation": (("elevation"), elev),
+            "time": (("time"), time),
+            "x": (("azimuth", "range"), x),
+            "y": (("azimuth", "range"), y),
+            "z": (("azimuth", "range"), z + dataset.attrs["height"]),
+            "longitude": (("azimuth", "range"), longitude),
+            "latitude": (("azimuth", "range"), latitude),
+        }
+    )
+
+    return dataset
+
+
+def read_odim(odim_file: str, lazy_load: bool = True, **kwargs) -> List:
+    """
+    Read an ODIM H5 file.
+
+    Parameters:
+    ===========
+    odim_file: str
+        ODIM H5 filename.
+    lazy_load: bool
+        Lazily load the data if true, read and load in memory the entire dataset
+        if false.
+    include_fields: list
+        Specific fields to be exclusively read.
+    exclude_fields: list
+        Specific fields to be excluded from reading.
+
+    Returns:
+    ========
+    radar: list
+        List of xarray datasets, each item in a the list is one sweep of the
+        radar data (ordered from lowest elevation scan to highest).
+    """
+    with h5py.File(odim_file, "r") as hfile:
+        nsweep = len([k for k in hfile["/"].keys() if k.startswith("dataset")])
+
+    radar = []
+    for sweep in range(0, nsweep):
+        c = dask.delayed(read_odim_slice)(odim_file, sweep, **kwargs)
+        radar.append(c)
+
+    if not lazy_load:
+        radar = [r.compute() for r in radar]
+
+    return radar

pyodim-0.4/pyodim.egg-info/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.1
+Name: pyodim
+Version: 0.4
+Summary: An ODIM hdf5 file reader.
+Home-page: https://github.com/vlouf/pyodim
+Author: Valentin Louf
+Author-email: valentin.louf@bom.gov.au
+Project-URL: Bug Reports, https://github.com/vlouf/pyodim/issues
+Project-URL: Source, https://github.com/vlouf/pyodim/
+Keywords: odim h5 file reader
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+
+# PYODIM
+
+A simple ODIM H5 (Opera Data Information Model - Hierarchical Data Format 
+version 5) radar reader in Python. It outputs the radar date in an xarray 
+Dataset. The goal is to be as barebone as possible while providing an xarray, 
+so that it can easily scale up (production) or just a very lean reader for 
+quicklooks into the data.
+
+## Example
+
+```python
+
+import pyodim
+
+filename = "/path/to/radar/file.h5"
+rset = pyodim.read_odim(filename, lazy_load=True)  # Lazy load does not load the data in memory to save time if you are interested in only a specific sweep
+radar = rset[0].compute()  # All sweeps are in a list (elevation ascending), so the 1st item of the list is the bottom sweep.
+print(radar)
+```
+
+This code will output the radar data for the first sweep (lowest elevation 
+scan) in the radar file as an xarray Dataset, for example:
+
+```python
+<xarray.Dataset>
+Dimensions:     (azimuth: 360, range: 1283, elevation: 1, time: 360)
+Coordinates:
+  * range       (range) float32 125.0 375.0 625.0 ... 3.204e+05 3.206e+05
+  * azimuth     (azimuth) float32 0.01111 1.011 2.011 ... 357.0 358.0 359.0
+  * elevation   (elevation) float32 0.5
+  * time        (time) datetime64[ns] 2024-01-16T02:49:29.337047353 ... 2024-...
+Data variables: (12/17)
+    DBZH        (azimuth, range) float64 nan nan nan nan nan ... nan nan nan nan
+    SNRH        (azimuth, range) float64 nan nan nan nan nan ... nan nan nan nan    
+    VRADH       (azimuth, range) float64 nan nan nan nan nan ... nan nan nan nan
+    WRADH       (azimuth, range) float64 nan nan nan nan nan ... nan nan nan nan
+    KDP         (azimuth, range) float64 nan nan nan nan nan ... nan nan nan nan
+    ...          ...
+    x           (azimuth, range) float32 0.02424 0.07271 ... -5.595e+03
+    y           (azimuth, range) float32 125.0 375.0 ... 3.203e+05 3.206e+05
+    z           (azimuth, range) float32 45.09 47.27 ... 2.84e+03 2.842e+03
+    longitude   (azimuth, range) float32 144.8 144.8 144.8 ... 144.7 144.7 144.7
+    latitude    (azimuth, range) float32 -37.85 -37.85 -37.85 ... -34.97 -34.96
+Attributes: (12/15)
+    Conventions:  ODIM_H5/V2_4
+    latitude:     -37.85200119018555
+    longitude:    144.75199890136722
+    height:       44.0
+    date:         2024-01-16T02:45:21
+    object:       PVOL
+    ...           ...
+    beamwV:       1.0
+    wavelength:   10.489999771118164
+    NI:           36.5052
+    highprf:      696.0
+    start_time:   20240116_024928
+    end_time:     20240116_024958
+```
+
+PYODIM reads the ODIM radar data and metadata. It also provides some quality of 
+life feature like automatically creating the x, y, z and latitude/longitude 
+coordinates for all radar gates (using the azimuthal equidistant - `aeqd` - projection). By 
+default it uses `dask.delayed` to *lazily* load the data, meaning that it will 
+not actually load all the sweeps in memory, as for many applications we often 
+don't need all the radar sweeps. Instead, by calling the `.compute()` method 
+like in the example above, PYODIM will only read and load in memory the sweep 
+that you want, saving time. If you want to read all the sweeps at once in a 
+list, then just set `lazy_load=False`.
+
+## Dependencies
+
+Mandatory:
+- [numpy][1]
+- [xarray][2]
+- [pyproj][3]
+- [dask][4]
+
+And optionally (it will automatically populate the fields metadata using pyart 
+if available): 
+- [Py-ART][5] 
+
+[1]: http://www.scipy.org/
+[2]: http://numba.pydata.org
+[3]: https://pypi.org/project/pyproj/
+[4]: https://www.dask.org/
+[5]: https://github.com/ARM-DOE/pyart

pyodim-0.4/pyodim.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+.gitignore
+LICENSE
+README.md
+setup.py
+pyodim/__init__.py
+pyodim/__version__.py
+pyodim/pyodim.py
+pyodim.egg-info/PKG-INFO
+pyodim.egg-info/SOURCES.txt
+pyodim.egg-info/dependency_links.txt
+pyodim.egg-info/requires.txt
+pyodim.egg-info/top_level.txt

pyodim-0.4/pyodim.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

pyodim-0.4/pyodim.egg-info/requires.txt

@@ -0,0 +1,5 @@
+numpy
+dask
+xarray
+h5py
+pyproj

pyodim-0.4/pyodim.egg-info/top_level.txt

@@ -0,0 +1 @@
+pyodim

pyodim-0.4/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pyodim-0.4/setup.py

@@ -0,0 +1,41 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+from os import path
+from setuptools import find_packages, setup
+
+
+here = path.abspath(path.dirname(__file__))
+# Get the long description from the README file
+with open(path.join(here, "README.md"), encoding="utf-8") as f:
+    long_description = f.read()
+
+
+setup(
+    name="pyodim",
+    version="0.4",
+    description="An ODIM hdf5 file reader.",
+    long_description=long_description,
+    long_description_content_type="text/markdown",
+    url="https://github.com/vlouf/pyodim",
+    author="Valentin Louf",
+    author_email="valentin.louf@bom.gov.au",
+    classifiers=[
+        "Development Status :: 4 - Beta",
+        "Intended Audience :: Science/Research",
+        "Topic :: Scientific/Engineering :: Atmospheric Science",
+        "License :: OSI Approved :: MIT License",
+        "Programming Language :: Python :: 3.7",
+        "Programming Language :: Python :: 3.8",
+        "Programming Language :: Python :: 3.9",
+        "Programming Language :: Python :: 3.10",
+        "Programming Language :: Python :: 3.11",
+    ],
+    keywords="odim h5 file reader",  # Optional
+    packages=find_packages(exclude=["contrib", "docs", "tests"]),
+    install_requires= ["numpy", "dask", "xarray", "h5py", "pyproj"],
+    project_urls={
+        "Bug Reports": "https://github.com/vlouf/pyodim/issues",
+        "Source": "https://github.com/vlouf/pyodim/",
+    },
+)