wrfrun 0.1.7__py3-none-any.whl → 0.1.9__py3-none-any.whl

wrfrun/extension/goos_sst/__init__.py

@@ -0,0 +1,67 @@
+"""
+wrfrun.extension.goos_sst
+#########################
+
+This extension can help you create a GRIB file from ERA5 skin temperature (SKT) data and NEAR-GOOS sea surface temperature (SST) data.
+
+============================================= =============================================
+:doc:`core </api/extension.goos_sst.core>`    Core functionality submodule.
+:doc:`res </api/extension.goos_sst.res>`      Resource files provided by this extension.
+:doc:`utils </api/extension.goos_sst.utils>`  Utility submodule used by the core submodule.
+============================================= =============================================
+
+Important Note
+**************
+
+This extension relies on ``cfgrib`` package to create GRIB file.
+While GRIB write support is experimental in ``cfgrib``,
+this extension may **FAIL TO CREATE GRIB FILE**.
+
+How This Extension Works
+************************
+
+This extension provides a method which merges ERA5 reanalysis skin temperature (SKT) data and NEAR-GOOS SST data,
+and write new data to a GRIB file.
+
+How To Use This Extension
+*************************
+
+Prerequisite
+============
+
+You need to have the following packages installed, because they are not included in ``wrfrun``'s dependency:
+
+* cfgrib: Provide the method to create GRIB file.
+* seafog: Provide the method to download and read NEAR-GOOS SST data.
+
+And you also have downloaded an ERA5 reanalysis data (GRIB format) which contains SKT data.
+
+How To Use
+==========
+
+The code snap below shows you how to use this extension.
+
+.. code-block:: Python
+    :caption: main.py
+
+    from wrfrun.extension.goos_sst import merge_era5_goos_sst_grib
+
+
+    if __name__ == '__main__':
+        era5_data_path = "data/ear5-reanalysis-data.grib"
+        merge_era5_goos_sst_grib(era5_data_path, "data/near-goos-data.grib")
+        
+Please check :func:`core.merge_era5_goos_sst_grib` for more information.
+
+.. toctree::
+    :maxdepth: 1
+    :hidden:
+
+    core <extension.goos_sst.core>
+    res <extension.goos_sst.res>
+    utils <extension.goos_sst.utils>
+"""
+
+from .core import *
+from .res import *
+from .utils import *

wrfrun/extension/goos_sst/core.py

@@ -0,0 +1,111 @@
+"""
+wrfrun.extension.goos_sst.core
+##############################
+
+Implementation of ``extension.goos_sst``'s core functionality.
+
+
+.. autosummary::
+    :toctree: generated/
+    
+    merge_era5_goos_sst_grib
+"""
+
+from os.path import dirname
+
+import cfgrib as cf
+import numpy as np
+from pandas import to_datetime
+from xarray import DataArray
+
+from .utils import create_sst_grib
+from wrfrun.utils import logger
+
+
+def merge_era5_goos_sst_grib(surface_grib_path: str, save_path: str, sst_data_save_path: str | None = None, resolution="low"):
+    """
+    This function reads ERA5 skin temperature (SKT) data from the GRIB file,
+    interpolates it to the same grib of NEAR-GOOS sea surface temperature (SST) data,
+    merges them and creates a new GRIB file with the new data.
+
+    :param surface_grib_path: GRIB file which contains SKT data.
+    :type surface_grib_path: str
+    :param save_path: Save path of the new GRIB file.
+    :type save_path: str
+    :param sst_data_save_path: Save path of downloaded NEAR-GOOS SST data.
+                               If None, save data to the parent directory of ``save_path``.
+    :type sst_data_save_path: str | None
+    :param resolution: Resolution of downloaded NEAR-GOO SST data.
+                       Please check ``seafog.goos_sst_find_data`` for more information.
+    :type resolution: str
+    """
+    # lazy import seafog to fix libcurl error in readthedocs
+    # T^T
+    from seafog import goos_sst_find_data, goos_sst_parser
+
+    dataset_list = cf.open_datasets(surface_grib_path)
+
+    dataset = None
+    for _ds in dataset_list:
+        if "skt" in _ds:
+            dataset = _ds
+            break
+
+    if dataset is None:
+        logger.error(f"'skt' data not found in {surface_grib_path}")
+        raise ValueError
+
+    skt: DataArray = dataset["skt"]     # type: ignore
+
+    longitude_start, longitude_end = skt["longitude"][0].data, skt["longitude"][-1].data    # type: ignore
+    latitude_start, latitude_end = skt["latitude"][-1].data, skt["latitude"][0].data    # type: ignore
+
+    data_time = skt["time"].to_numpy()  # type: ignore
+    data_time = to_datetime(data_time).strftime("%Y-%m-%d %H:%M")
+
+    if sst_data_save_path is None:
+        sst_data_save_path = dirname(save_path)
+
+    # read the first time data, so we can interpolate skt data to the same resolution as sst data.
+    _data = goos_sst_find_data(data_time[0], sst_data_save_path, resolution=resolution, show_progress=False)
+    _data = goos_sst_parser(_data, resolution=resolution)
+    _data = _data.loc[latitude_start:latitude_end, longitude_start:longitude_end]
+
+    skt = skt.interp({"longitude": _data["longitude"], "latitude": _data["latitude"]})
+    sst = np.zeros_like(skt)
+    temp_data = np.zeros_like(skt[0])
+
+    temp_data[:] = skt.to_numpy()[0]
+    index = ~np.isnan(_data.to_numpy())
+    temp_data[index] = _data.to_numpy()[index]
+    sst[0] = temp_data
+
+    # loop other time.
+    for time_index, _data_time in enumerate(data_time[1:], start=1):
+        _data = goos_sst_find_data(_data_time, sst_data_save_path, resolution=resolution, show_progress=False)
+        _data = goos_sst_parser(_data, resolution=resolution)
+        _data = _data.loc[latitude_start:latitude_end, longitude_start:longitude_end]
+
+        temp_data[:] = skt.to_numpy()[time_index]
+        index = ~np.isnan(_data.to_numpy())
+        temp_data[index] = _data.to_numpy()[index]
+        sst[time_index] = temp_data
+
+    sst = DataArray(
+        name="sst",
+        data=sst,
+        dims=["time", "latitude", "longitude"],
+        coords={
+            "time": skt["time"],
+            "latitude": skt["latitude"],
+            "longitude": skt["longitude"]
+        }, attrs={
+            "units": "K",
+            "long_name": "Sea surface temperature"
+        }
+    )
+
+    create_sst_grib(sst, save_path=save_path)
+
+
+__all__ = ["merge_era5_goos_sst_grib"]

wrfrun/extension/goos_sst/res/Vtable.ERA_GOOS_SST

@@ -0,0 +1,7 @@
+GRIB | Level| Level| Level| metgrid  |  metgrid | metgrid                                  |
+Code | Code |   1  |   2  | Name     |  Units   | Description                              |
+-----+------+------+------+----------+----------+------------------------------------------+
+  34 |  1   |   0  |      | SST      | K        | Sea-Surface Temperature                  |
+-----+------+------+------+----------+----------+------------------------------------------+
+
+# Vtable setting for GRIB file created by wrfrun.extension.goos_sst

wrfrun/extension/goos_sst/res/__init__.py

@@ -0,0 +1,26 @@
+"""
+wrfrun.extension.goos_sst.res
+#############################
+
+Resource files provided by :doc:`/api/extension.goos_sst`.
+
+VTABLE_ERA_GOOS_SST
+*******************
+
+.. py:data:: VTABLE_ERA_GOOS_SST
+    :type: str
+    :value: Absolute file path.
+
+    Vtable file used to input the GRIB data created by :doc:`/api/extension.goos_sst` to WRF.
+
+"""
+
+from os.path import abspath, dirname
+
+
+_PATH = abspath(dirname(__file__))
+
+VTABLE_ERA_GOOS_SST = f"{_PATH}/Vtable.ERA_GOOS_SST"
+
+
+__all__ = ["VTABLE_ERA_GOOS_SST"]

wrfrun/extension/goos_sst/utils.py

@@ -0,0 +1,97 @@
+"""
+wrfrun.extension.goos_sst.utils
+###############################
+
+Functions that are used by :doc:`/api/extension.goos_sst`.
+
+.. autosummary::
+    :toctree: generated/
+    
+    create_sst_grib
+"""
+
+from cfgrib.xarray_to_grib import to_grib
+from numpy.dtypes import DateTime64DType
+from pandas import to_datetime
+from xarray import DataArray, Dataset
+
+from wrfrun.utils import logger
+
+
+def create_sst_grib(data: DataArray, save_path: str):
+    """
+    Write SST data to a GRIB file.
+    
+    This function creates GRIB file using ``cfgrib`` package.
+    While GRIB write support is experimental in ``cfgrib``,
+    this function may **FAIL TO CREATE GRIB FILE**.
+
+    :param data: ``xarray.DataArray``, which at least has three dimensions: ``["time", "latitude", "longitude"]``.
+    :type data: DataArray
+    :param save_path: Output GRIB file path.
+    :type save_path: str
+    """
+    # check the data's dimensions.
+    for _dim in ["time", "longitude", "latitude"]:
+        if _dim not in data.dims:
+            logger.error(f"Essential dimension '{_dim}' not found in data")
+            raise KeyError
+
+    if not isinstance(data["time"].dtype, DateTime64DType):     # type: ignore
+        data = data.assign_coords(time=to_datetime(data["time"].data))
+
+    data = data.sortby(data["latitude"], ascending=False)
+
+    longitude_start, longitude_stop = data["longitude"][0].data, data["longitude"][-1].data
+    latitude_start, latitude_stop = data["latitude"][0].data, data["latitude"][-1].data
+    delta_longitude = data["longitude"][1].data - data["longitude"][0].data
+    delta_latitude = data["latitude"][0].data - data["latitude"][1].data
+    longitude_length = data["longitude"].size
+    latitude_length = data["latitude"].size
+    points_number = data.size
+
+    data = data.assign_attrs(**{
+        "units": "K",
+        "long_name": "Sea surface temperature",
+        "standard_name": "Sea surface temperature",
+        # The following keys and values will be used in GRIB.
+        "GRIB_paramId": 34,
+        "GRIB_shortName": "sst",
+        "GRIB_units": "K",
+        "GRIB_name": "Sea surface temperature",
+        "GRIB_stepUnits": 1,
+        "GRIB_stepType": "instant",
+        "GRIB_gridType": "regular_ll",
+        "GRIB_iDirectionIncrementInDegrees": delta_longitude,
+        "GRIB_iScanNegatively": 0,
+        "GRIB_jDirectionIncrementInDegrees": delta_latitude,
+        "GRIB_jScanPositively": 0,
+        "GRIB_latitudeOfFirstGridPointInDegrees": latitude_start,
+        "GRIB_latitudeOfLastGridPointInDegrees": latitude_stop,
+        "GRIB_longitudeOfFirstGridPointInDegrees": longitude_start,
+        "GRIB_longitudeOfLastGridPointInDegrees": longitude_stop,
+        "GRIB_Ny": latitude_length,
+        "GRIB_Nx": longitude_length,
+        "GRIB_typeOfLevel": "surface",
+        # The following keys and values can't be found at ECMWF websites.
+        "GRIB_cfName": "unknown",
+        "GRIB_cfVarName": "sst",
+        "GRIB_dataType": "an",  # Analysis data, defined at https://codes.ecmwf.int/grib/format/mars/type/
+        "GRIB_gridDefinitionDescription": "Latitude/Longitude Grid",
+        # "GRIB_missingValue": -9999,
+        "GRIB_numberOfPoints": points_number,
+        "GRIB_totalNumber": 0,
+        "GRIB_uvRelativeToGird": 0
+    })
+
+    to_grib(
+        Dataset({
+            "sst": data
+        }, attrs={
+            "GRIB_centre": "ecmf",
+            "GRIB_edition": 1,
+        }), save_path
+    )
+
+
+__all__ = ["create_sst_grib"]

wrfrun/extension/littler/__init__.py

@@ -1 +1,57 @@
-from .utils import *
+"""
+wrfrun.extension.littler
+########################
+
+This extension can help you manage observation data, and create ``LITTLE_R`` file for data assimilation.
+
+========================================= =============================
+:doc:`core </api/extension.littler.core>` Core functionality submodule.
+========================================= =============================
+
+What Can This Extension Do?
+***************************
+
+According to the `WRFDA Online Tutorial <https://www2.mmm.ucar.edu/wrf/users/wrfda/OnlineTutorial/Help/littler.html>`_,
+``LITTLE_R`` is an ASCII-based observation file format that is designed to be an intermediate format
+so that WRFDA might be able to assimilate as many observation types as possible in a universal manner.
+
+However, ``LITTLE_R`` is really hard to process elegantly from the point of view of Python.
+To help users create ``LITTLE_R`` file easily, this extension introduces :class:`LittleR <core.LittleR>`,
+and **Zipped Little R** file.
+
+:class:`LittleR <core.LittleR>` accepts observation datas, and can generate observation reports in proper format.
+Besides, it can save an observation report to a Zipped Little R file,
+so you can read the report later or process the observation data with other program.
+Please check :class:`LittleR <core.LittleR>` for more information.
+
+How To Use This Extension?
+**************************
+
+The code snap below shows you how to use this extension.
+
+.. code-block:: Python
+    :caption: main.py
+    
+    from wrfrun.extension.littler import LittleR
+
+
+    if __name__ == '__main__':
+        littler = LittleR()
+        littler.set_header(
+            longitude=120, latitude=60, fm="FM-19", elevation=0,
+            is_bogus=True, date="20250902070000"
+        )
+        # write to LITTLE_R file
+        with open("data/test", "w") as f:
+            f.write(str(littler))
+        # write to zlr file
+        littler.to_zlr("data/test.zlr")
+
+.. toctree::
+    :maxdepth: 1
+    :hidden:
+
+    core <extension.littler.core>
+"""
+
+from .core import *