Merge branch 'main' into zdr_bias

doc/environment.yml

@@ -41,3 +41,4 @@ dependencies:
       - pooch
       - versioneer
       - ablog
+      - -e ..

doc/source/conf.py

@@ -97,7 +97,7 @@
 
 # General information about the project.
 project = "Py-ART"
-copyright = "2013-2022, Py-ART developers"
+copyright = "2013-2024, Py-ART developers"
 author = "Py-ART developers"
 
 # The version info for the project you're documenting, acts as replacement for
@@ -106,19 +106,16 @@
 #
 import pyart
 
-# The short X.Y version (including the .devXXXX suffix if present)
-version = re.sub(r"^(\d+\.\d+)\.\d+(.*)", r"\1\2", pyart.__version__)
-if "dev" in version:
-    # retain the .dev suffix, but clean it up
-    version = re.sub(r"(\.dev\d*).*?$", r"\1", version)
-else:
-    # strip all other suffixes
-    version = re.sub(r"^(\d+\.\d+).*?$", r"\1", version)
+verinfo = pyart.__version__
+parsed_version = re.search(r"(?P<full>(?P<base>\d+\.\d+)\.?\w*)", verinfo).groupdict()
+
+# The short X.Y version.
+version = parsed_version["base"]
+if "+" in verinfo:
+    version += "dev"
 # The full version, including alpha/beta/rc tags.
-release = pyart.__version__
-# full Py-ART version in CI built docs
-if "CI" in os.environ and os.environ["CI"] == "true":
-    version = release
+release = parsed_version["full"]
+
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
 #
@@ -151,6 +148,9 @@
 # documentation.
 #
 html_theme_options = {
+    "external_links": [
+        {"name": "Release Notes", "url": "https://github.com/ARM-DOE/pyart/releases"},
+    ],
     "analytics": {"google_analytics_id": "G-JJEG3CV376"},
     "github_url": "https://github.com/ARM-DOE/pyart",
     "twitter_url": "https://twitter.com/Py_ART",

doc/source/index.rst

@@ -30,13 +30,6 @@ The Python ARM Radar Toolkit - Py-ART
 
    dev/index.rst
 
-.. toctree::
-   :maxdepth: 2
-   :hidden:
-   :caption: Notebook Gallery
-
-   notebook-gallery.rst
-
 .. toctree::
    :maxdepth: 1
    :hidden:
@@ -45,11 +38,11 @@ The Python ARM Radar Toolkit - Py-ART
    blog.md
 
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 2
    :hidden:
-   :caption: Changelog
+   :caption: Notebook Gallery
 
-   changelog.md
+   notebook-gallery.rst
 
 .. grid:: 1 2 2 2
     :gutter: 2

doc/source/userguide/index.rst

@@ -9,6 +9,7 @@ We also have a collection of installation, and contribution instructions listed
 .. toctree::
    :maxdepth: 1
 
+   pyart_2_0
    INSTALL
    setting_up_an_environment
    contributors_guide

doc/source/userguide/pyart_2_0.rst

@@ -0,0 +1,60 @@
+==========
+Py-ART 2.0
+==========
+
+In preparation for version 2.0.0 of Py-ART, codes were standardized for consistency purposes as further defined in the `Contributor's Guide <https://arm-doe.github.io/pyart/userguide/CONTRIBUTING.html>`_.  These changes will break some users code as the API has changed.  This guide will detail the changes for each module.
+
+How to Try Py-ART 2.0
+=====================
+
+The Py-ART 2.0 release candidate can be installed directly from github - this is still a work in progress, feedback is welcome!::
+
+    pip install git+https://github.com/ARM-DOE/pyart@release/2.0
+
+Input/Output (IO)
+=================
+We now offer the option to use xradar for IO, with the following interface (a typical gridding workflow is shown below):
+
+.. code-block:: python
+
+    import xradar as xd
+    import pyart
+
+    # Access sample cfradial1 data from Py-ART and read using xradar
+    filename = get_test_data("swx_20120520_0641.nc")
+    tree = xd.io.open_cfradial1_datatree(filename)
+
+    # Add the associated pyart methods - ensuring compatibility with Py-ART functionality
+    radar = tree.pyart.to_radar()
+
+    # Grid using 11 vertical levels, and 101 horizontal grid cells at a resolution on 1 km
+    grid = pyart.map.grid_from_radars(
+        (radar,),
+        grid_shape=(11, 101, 101),
+        grid_limits=(
+            (0.0, 10_000),
+            (-50_000.0, 50_000.0),
+            (-50_000, 50_000.0),
+        ),
+    )
+
+Correct
+=======
+The `dealias_fourdd <https://arm-doe.github.io/pyart/API/generated/pyart.correct.dealias_fourdd.html>`_ algorithm has been removed given the now unsupported RSL library.
+
+It is recommended that users move to the `region-based dealiasing algorithm <https://arm-doe.github.io/pyart/API/generated/pyart.correct.dealias_region_based.html>`_.
+
+Graph
+=====
+Colormaps have been moved to a dedicated package outside Py-ART, `cmweather <https://cmweather.readthedocs.io/>`_.
+
+For example, visualizing our grid mentioned previously, it is recommended to install/import cmweather and change the colormap name from `pyart_ChaseSpectral` to `ChaseSpectral`
+
+.. code-block:: python
+
+    import cmweather
+
+    display = pyart.graph.GridMapDisplay(grid)
+    display.plot_grid(
+        "reflectivity_horizontal", level=0, vmin=-20, vmax=60, cmap="ChaseSpectral"
+    )

examples/correct/plot_cloud_mask.py

@@ -0,0 +1,66 @@
+"""
+=====================================
+Calculating and Plotting a Cloud Mask
+=====================================
+
+This example shows how to correct and plot reflectivity from an ARM
+KAZR using a noise floor cloud mask.
+
+"""
+print(__doc__)
+
+# Author: Adam Theisen and Zach Sherman
+# License: BSD 3 clause
+
+import matplotlib.pyplot as plt
+import numpy as np
+from open_radar_data import DATASETS
+
+import pyart
+
+############################
+# **Read and plot raw data**
+#
+# First let's read and plot our dataset without any mask.
+
+# Fetch and read in the ARM KAZR file.
+filename = DATASETS.fetch("sgpkazrgeC1.a1.20190529.000002.cdf")
+radar = pyart.aux_io.read_kazr(filename)
+
+# Let's now take a look at reflectivity data prior to any corrections.
+display = pyart.graph.RadarDisplay(radar)
+display.plot("reflectivity_copol")
+display.set_limits(xlim=(0, 55))
+plt.show()
+
+#################################################
+# **Calculate cloud mask and plot corrected data**
+#
+# Now lets apply a mask by using the calc_cloud_mask function
+# that will use a noise floor calculation from range and more
+# to calculate the mask.
+
+# First lets correct the data by calculating the mask.
+cloud_mask_radar = pyart.correct.calc_cloud_mask(radar, "reflectivity_copol", "range")
+
+# In this new radar object we should now have a new cloud mask field.
+print(cloud_mask_radar.fields["cloud_mask_2"])
+
+# Next we'll create a copy of the reflectivity field so we are not
+# overwriting the original data.
+cloud_mask_radar.add_field_like(
+    "reflectivity_copol",
+    "reflectivity_cloud_mask",
+    cloud_mask_radar.fields["reflectivity_copol"]["data"].copy(),
+)
+
+# Now let's apply the mask to the copied reflectivity data.
+cloud_mask_radar.fields["reflectivity_cloud_mask"]["data"][
+    cloud_mask_radar.fields["cloud_mask_2"]["data"] == 0
+] = np.nan
+
+# And now we can plot the masked reflectivity field.
+display = pyart.graph.RadarDisplay(cloud_mask_radar)
+display.plot("reflectivity_copol")
+display.set_limits(xlim=(0, 55))
+plt.show()

examples/plotting/plot_max_cappi.py

@@ -0,0 +1,111 @@
+"""
+=============
+Plot Max-CAPPI
+=============
+
+This is an example of how to plot a Max-CAPPI
+within a Py-ART grid display object.
+
+"""
+
+print(__doc__)
+
+# Author: Hamid Ali Syed ([email protected])
+# License: BSD 3 clause
+
+import matplotlib.pyplot as plt
+import numpy as np
+
+import pyart
+from pyart.testing import get_test_data
+
+#########################################
+# ** MAX-CAPPI Display
+#
+
+# Define and Read in the test data
+grid_file = get_test_data("20110520100000_nexrad_grid.nc")
+grid = pyart.io.read_grid(grid_file)
+
+
+# Create a grid display
+gdisplay = pyart.graph.GridMapDisplay(grid)
+gdisplay.plot_maxcappi(field="REF", range_rings=True, add_slogan=True)
+
+
+#########################################
+# ** Second Example
+#
+# Let's read in a cfradial file and create a grid.
+
+
+import logging
+from datetime import datetime
+
+import fsspec
+import pytz
+
+
+def download_nexrad(timezone, date, site, local_date=False):
+    """Download NEXRAD radar data from an S3 bucket."""
+    try:
+        utc_date = (
+            pytz.timezone(timezone).localize(date).astimezone(pytz.utc)
+            if local_date
+            else date
+        )
+        logging.info(f"Time: {utc_date}")
+
+        fs = fsspec.filesystem("s3", anon=True)
+        nexrad_path = utc_date.strftime(
+            f"s3://noaa-nexrad-level2/%Y/%m/%d/{site}/{site}%Y%m%d_%H*"
+        )
+        files = sorted(fs.glob(nexrad_path))
+
+        return [file for file in files if not file.endswith("_MDM")]
+    except Exception as e:
+        logging.error("Error in processing: %s", e)
+        return []
+
+
+# Load NEXRAD data from S3 Bucket
+site = "PHWA"
+timezone = "UTC"
+date = datetime(2024, 8, 25, 8, 29)
+
+# Correctly passing the site and timezone
+file = download_nexrad(timezone, date, site, local_date=False)[0]
+
+
+# Read the data using nexrad_archive reader
+radar = pyart.io.read_nexrad_archive("s3://" + file)
+
+# Create a 3D grid
+# Mask out last 10 gates of each ray, this removes the "ring" around the radar.
+radar.fields["reflectivity"]["data"][:, -10:] = np.ma.masked
+
+# Exclude masked gates from the gridding
+gatefilter = pyart.filters.GateFilter(radar)
+gatefilter.exclude_transition()
+gatefilter.exclude_masked("reflectivity")
+gatefilter.exclude_outside("reflectivity", 10, 80)
+
+# Perform Cartesian mapping, limit to the reflectivity field.
+max_range = np.ceil(radar.range["data"].max())
+if max_range / 1e3 > 250:
+    max_range = 250 * 1e3
+
+grid = pyart.map.grid_from_radars(
+    (radar,),
+    gatefilters=(gatefilter,),
+    grid_shape=(30, 441, 441),
+    grid_limits=((0, 10000), (-max_range, max_range), (-max_range, max_range)),
+    fields=["reflectivity"],
+)
+
+# Create a grid display
+gdisplay = pyart.graph.GridMapDisplay(grid)
+with plt.style.context("dark_background"):
+    gdisplay.plot_maxcappi(
+        field="reflectivity", cmap="pyart_HomeyerRainbow", add_slogan=True
+    )