Snowfall and rain approximation from Dai 2008 (#2208)

aulemahal · web-flow · commit 20e75d734738 · 2025-08-27T10:29:15.000-04:00
### Pull Request Checklist: - [x] This PR addresses an already opened issue (for bug fixes / features) - This PR fixes #1752 - [x] Tests for the changes have been added (for bug fixes / features) - [x] (If applicable) Documentation has been added / updated (for bug fixes / features) - [x] CHANGELOG.rst has been updated (with summary of main changes) - [x] Link to issue (:issue:`number`) and pull request (:pull:`number`) has been added ### What kind of change does this PR introduce? * New methods "dai_annual" and "dai_seasonal" for snowfall and rain approximation. * New argument `landmask` to control which formulation (land or ocean) we use. ### Does this PR introduce a breaking change? No. Only new arguments added, no default changed. ### Other information: @Zeitsperre : The `landmask` argument is polymorphic (my favorite, your nemesis (?)), it can either be a DataArray (which is assumed to be of boolean dtype, but no need to check) or a straight boolean. This is not a `Quantified` because boolean have no units. Right now, I put the annotation that resolved into the "optional variable" `InputType`, which means "bool" is not part of it. Should we create a new `InputType` for boolean mask ? It would be similar to `Quantified` in that it can be a scalar or a DataArray, but without the units check. @tlogan2000 : I implemented the rain approximation as well. However, in opposition to the 3 other methods already implemented, the Dai rain approximation is not equal to `pr - prsn` because it considers some small fractions of the total precip to be of another phase (denoted "sleet" in the article). Thus, to imitate DonnéesClimatiques, ones need to compute `prra` as `pr - prsn` instead of using `rain_approximation`. Is this ok ? Tests need to be added, I'll try to base my tests off of DonnéesClimatiques' data. At least it would compare xclim with another implementation, if not an "original" one.
diff --git a/CHANGELOG.rst b/CHANGELOG.rst
@@ -27,6 +27,7 @@ New indicators and features
 * The ``xclim.indices.helpers.day_length`` function now accepts an ``infill_polar_days`` argument to control whether polar days or polar nights are filled with NaNs (``infill_polar_days=False``; default behaviour) or with a day length of 0 or 24 hours, depending on the date (``infill_polar_days=True``). (:issue:`2201`, :pull:`2207`).
 * The indices for ``uas_vas_to_sfcwind``, ``sfcwind_to_uas_vas``, ``rle_1d``, and ``cffwis_indices`` now provide their outputs via the ``NamedTuple`` format. This provides a method for accessing indice outputs using variable names in addition to positional indexing. (:pull:`2224`).
 * The new ``xclim.indicators.convert`` module is now available to provide a distinct API for conversion-focused indicators. This module is intended to regroup all conversion-based indicators that were previously scattered across different indicato realms. This module is also accessible via ``xclim.convert``. (:issue:`1289`, :pull:`2224`).
+* New methods ``dai_annual`` and ``dai_seasonal`` for ``xclim.convert.snowfall_approximation`` and ``xclim.convert.rain_approximation``, taken from :cite:t:`dai_snowfall_2008`. Indicator also take new argument ``landmask`` to switch between the land and ocean formulations. (:pull:`2208`, :issue:`1752`).
 
 Breaking changes
 ^^^^^^^^^^^^^^^^
diff --git a/docs/_static/indsearch.js b/docs/_static/indsearch.js
@@ -1,6 +1,6 @@
 /* Array of indicator objects */
 let indicators = [];
-let defModules = ["atmos", "generic", "land", "seaIce"];
+let defModules = ["atmos", "convert", "generic", "land", "seaIce"];
 /* MiniSearch object defining search mechanism */
 let miniSearch = new MiniSearch({
   fields: ['title', 'abstract', 'variables', 'keywords', 'id'], // fields to index for full-text search
diff --git a/docs/api_indicators.rst b/docs/api_indicators.rst
@@ -1,6 +1,9 @@
 Indicators are the main tool xclim provides to compute climate indices. In contrast
 to the function defined in `xclim.indices`, Indicators add a layer of health checks
-and metadata handling. Indicator objects are split into realms : atmos, land and seaIce.
+and metadata handling. Indicator objects are split into submodules according to their
+"realm" : atmos, land and seaIce, with two additional submodules : generic (for
+indicator that don't apply to a specific variable) and convert (for non-resampling
+indicators that transform between variables).
 
 Virtual modules are also inserted here. A normal installation of xclim comes with three virtual modules:
 
@@ -26,6 +29,12 @@ Climate Indicators API
    :undoc-members:
    :imported-members:
 
+.. automodule:: xclim.indicators.convert
+   :members:
+   :undoc-members:
+   :imported-members:
+
+
 Virtual Indicator Submodules
 ----------------------------
 
diff --git a/docs/conf.py b/docs/conf.py
@@ -46,7 +46,7 @@
 # Get all indicators and some information about them
 indicators = {}
 # FIXME: Include cf module when its indicators documentation is improved.
-for module in ("atmos", "generic", "land", "seaIce", "icclim", "anuclim"):
+for module in ("atmos", "convert", "generic", "land", "seaIce", "icclim", "anuclim"):
     for key, ind in getattr(_indicators, module).__dict__.items():
         if hasattr(ind, "_registry_id") and ind._registry_id in registry:  # noqa
             indicators[ind._registry_id] = {  # noqa
diff --git a/docs/indices.rst b/docs/indices.rst
@@ -28,8 +28,7 @@ types.
 
     Indices functions do not perform missing value checks, and usually do not set CF-Convention attributes
     (long_name, standard_name, description, cell_methods, etc.). These functionalities are provided by
-    :py:class:`xclim.core.indicator.Indicator` instances found in the :py:mod:`xclim.indicators.atmos`,
-    :py:mod:`xclim.indicators.land` and :mod:`xclim.indicators.seaIce` modules.
+    :py:class:`xclim.core.indicator.Indicator` instances found in the submodules of :py:mod:`xclim.indicators`.
 
 .. automodule:: xclim.indices
    :members:
diff --git a/docs/notebooks/cli.ipynb b/docs/notebooks/cli.ipynb
@@ -65,7 +65,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "For more information about a specific indicator, you can either use the `info` sub-command or directly access the `--help` message of the indicator. The former gives more information about the metadata, while the latter only prints the usage. Note that the module name (`atmos`, `land` or `seaIce`) is mandatory."
+    "For more information about a specific indicator, you can either use the `info` sub-command or directly access the `--help` message of the indicator. The former gives more information about the metadata, while the latter only prints the usage. Note that the module name (`atmos`, `convert`, `land` or `seaIce`) is mandatory."
    ]
   },
   {
diff --git a/docs/notebooks/usage.ipynb b/docs/notebooks/usage.ipynb
@@ -8,7 +8,7 @@
     "\n",
     "## Climate indicator computations\n",
     "\n",
-    "`xclim` is a library of climate indicators that operate on [xarray](https://docs.xarray.dev/en/stable/) `DataArray` objects. Indicators perform health checks on input data, converts units as needed, assign nans when input data is missing, and format outputs according to the Climate and Forecast (CF) convention. As the list of indicators has grown quite large, indicators are accessed through their *realm* (`xclim.atmos`, `xclim.land` and `xclim.seaIce`) to help browsing indicators by the domain they apply to. \n",
+    "`xclim` is a library of climate indicators that operate on [xarray](https://docs.xarray.dev/en/stable/) `DataArray` objects. Indicators perform health checks on input data, converts units as needed, assign nans when input data is missing, and format outputs according to the Climate and Forecast (CF) convention. As the list of indicators has grown quite large, indicators are accessed through their *realm* (`xclim.atmos`, `xclim.land` and `xclim.seaIce`, plus the special `xclim.convert`) to help browsing indicators by the domain they apply to. \n",
     "\n",
     "**Indicators should not be confused with *indices***, which define the algorithmic layer of each indicator. Those indices perform no checks beyond units compliance, and should be considered as low-level functions. See the respective documentation on [indicators](../indicators.rst) and [indices](../indices.rst) for more information.   \n",
     "\n",
diff --git a/docs/references.bib b/docs/references.bib
@@ -4149,6 +4149,25 @@ @article{schroter2015
 }
 
 
+@article{dai_snowfall_2008,
+  title = {Temperature and pressure dependence of the rain-snow phase transition over land
+    and ocean},
+  volume = {35},
+  copyright = {Copyright 2008 by the American Geophysical Union.},
+  issn = {1944-8007},
+  url = {https://onlinelibrary.wiley.com/doi/abs/10.1029/2008GL033295},
+  doi = {10.1029/2008GL033295},
+  language = {en},
+  number = {12},
+  urldate = {2025-07-09},
+  journal = {Geophysical Research Letters},
+  author = {Dai, Aiguo},
+  year = {2008},
+  note = {\_eprint: https://agupubs.onlinelibrary.wiley.com/doi/pdf/10.1029/2008GL033295},
+  keywords = {precipitation, phase transition, snow frequency}
+}
+
+
 @article{buck_new_1981,
   title = {New {Equations} for {Computing} {Vapor} {Pressure} and {Enhancement} {Factor}},
   volume = {20},
diff --git a/src/xclim/core/formatting.py b/src/xclim/core/formatting.py
@@ -601,6 +601,7 @@ def unprefix_attrs(source: dict, keys: Sequence, prefix: str) -> dict:
     InputKind.VARIABLE: "str or DataArray",
     InputKind.OPTIONAL_VARIABLE: "str or DataArray, optional",
     InputKind.QUANTIFIED: "quantity (string or DataArray, with units)",
+    InputKind.MASK: "DataArray or scalar",
     InputKind.FREQ_STR: "offset alias (string)",
     InputKind.NUMBER: "number",
     InputKind.NUMBER_SEQUENCE: "number or sequence of numbers",
diff --git a/src/xclim/core/utils.py b/src/xclim/core/utils.py
@@ -575,7 +575,7 @@ class InputKind(IntEnum):
     VARIABLE = 0
     """A data variable (DataArray or variable name).
 
-       Annotation : ``xr.DataArray``.
+       Annotation : ``xr.DataArray``. May not include anything else, may not be optional.
     """
     OPTIONAL_VARIABLE = 1
     """An optional data variable (DataArray or variable name).
@@ -633,6 +633,12 @@ class InputKind(IntEnum):
 
        Annotation : ``dict`` or ``dict | None``, may be optional.
     """
+    MASK = 11
+    """A mask or flag or scalar. Any value without units that might be passed as a non-temporal DataArray.
+       Can be a DataArray, a single bool or a single float.
+
+        Annotation : ``xr.DataArray | bool`` or ``xr.DataArray | float``, may be optional.
+    """
     KWARGS = 50
     """A mapping from argument name to value.
 
@@ -673,11 +679,15 @@ def infer_kind_from_parameter(param) -> InputKind:
     else:
         annot = {"no_annotation"}
 
-    if "DataArray" in annot and "None" not in annot and param.default is not None:
+    if annot == {"DataArray"} and param.default is not None:
         return InputKind.VARIABLE
 
     annot = annot - {"None"}
 
+    if annot == {"DataArray", "bool"} or annot == {"DataArray", "float"} or annot == {"DataArray", "int"}:
+        return InputKind.MASK
+
+    # Not a mask and not a required variable
     if "DataArray" in annot:
         return InputKind.OPTIONAL_VARIABLE
 
diff --git a/src/xclim/indices/converters.py b/src/xclim/indices/converters.py
diff --git a/tests/test_converters.py b/tests/test_converters.py
diff --git a/tests/test_indices.py b/tests/test_indices.py

Original file line number	Diff line number	Diff line change
`@@ -65,7 +65,7 @@`
`65`	`65`	`"cell_type": "markdown",`
`66`	`66`	`"metadata": {},`
`67`	`67`	`"source": [`
`68`		- "For more information about a specific indicator, you can either use the `info` sub-command or directly access the `--help` message of the indicator. The former gives more information about the metadata, while the latter only prints the usage. Note that the module name (`atmos`, `land` or `seaIce`) is mandatory."
	`68`	+ "For more information about a specific indicator, you can either use the `info` sub-command or directly access the `--help` message of the indicator. The former gives more information about the metadata, while the latter only prints the usage. Note that the module name (`atmos`, `convert`, `land` or `seaIce`) is mandatory."
`69`	`69`	`]`
`70`	`70`	`},`
`71`	`71`	`{`