Refactor first_day indices into generics

HISTORY.rst

@@ -10,11 +10,21 @@ New features and enhancements
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 * Documentation now supports intersphinx mapping references within code examples via `sphinx-codeautolink` and copying of code blocks via `sphinx-copybutton`. (:pull:`1182`).
 
+New indicators
+^^^^^^^^^^^^^^
+* New indices ``first_day_temperature_{above|below}`` and indicators ``xclim.indices.first_day_{tn|tg|tx}_{above|below}``. These indices/indicators accept operator (``op``) keyword for finer threshold comparison controls. (:issue:`1175`, :pull:`1186`).
+
 Breaking changes
 ^^^^^^^^^^^^^^^^
 * Indices that accept `lat` or `lon` coordinates in their call signatures will now use `cf-xarray` accessors to gather these variables in the event that they are not explicitly supplied. (:pull:`1180`). This affects the following
     - ``huglin_index``, ``biologically_effective_degree_days``, ``cool_night_index``, ``latitude_temperature_index``, ``water_budget``, ``potential_evapotranspiration``
-* ``cool_night_index`` now accepts ``lat: str = "north" | "south"`` for calculating CNI over DataArrays lacking a latitude coordinate. (:pull:`1180`).
+* ``cool_night_index`` now optionally accepts ``lat: str = "north" | "south"`` for calculating CNI over DataArrays lacking a latitude coordinate. (:pull:`1180`).
+* The ``first_day_below`` and ``first_day_above`` indices are now deprecated in order to clearly communicate the variables they act upon (:issue:`1175`, :pull:`1186`). The suggested migrations are as follows:
+    - ``xclim.indices.first_day_above`` -> ``xclim.indices.first_day_temperature_above``
+    - ``xclim.indices.first_day_below`` -> ``xclim.indices.first_day_temperature_below``
+* The ``first_day_below`` and ``first_day_above`` atmos indicators are now deprecated in order to clearly communicate the variables they act upon (:issue:`1175`, :pull:`1186`). The suggested migrations are as follows:
+    - ``xclim.atmos.first_day_above`` -> ``xclim.indices.first_day_{tn|tg|tx}_above``
+    - ``xclim.atmos.first_day_below`` -> ``xclim.indices.first_day_{tn|tg|tx}_below``
 
 Bug fixes
 ^^^^^^^^^
@@ -26,7 +36,8 @@ Internal changes
 * The documentation build now relies on `sphinx-codeautolink` and `sphinx-copybutton`. (:pull:`1182`).
 * Many docstrings did not fully adhere to the `numpy docstring format <https://numpydoc.readthedocs.io/en/latest/format.html>`_. Fields and entries for many classes and functions have been adjusted to adhere better. (:pull:`1182`).
 * The xdoctest namespace now provides access to session-scoped ``{variable}_dataset`` accessors, as well as a ``path_to_atmos_file`` object. These can be used for running doctests on all variables made in the pytest ``atmosds()`` fixture. (:pull:`1882`).
-* Upgrade CodeQL github action to v2 (:issue:`1188`, :pull:`1189`).
+* Upgrade CodeQL GitHub Action to v2. (:issue:`1188`, :pull:`1189`).
+* New generic indice ``first_day_threshold_reached`` is now used to compose all ``first_day_XYZ`` indices. (:issue:`1175`, :pull:`1186`).
 
 0.38.0 (2022-09-06)
 -------------------

xclim/core/calendar.py

@@ -28,7 +28,7 @@
 from xarray.coding.cftimeindex import CFTimeIndex
 from xarray.core.resample import DataArrayResample
 
-from xclim.core.utils import PercentileDataArray, uses_dask
+from xclim.core.utils import DayOfYearStr, PercentileDataArray, uses_dask
 
 from .formatting import update_xclim_history
 
@@ -79,9 +79,6 @@
 # Some xclim.core.utils functions made accessible here for backwards compatibility reasons.
 datetime_classes = {"default": pydt.datetime, **cftime._cftime.DATE_TYPES}  # noqa
 
-#: Type annotation for strings representing dates without a year (MM-DD).
-DayOfYearStr = NewType("DayOfYearStr", str)
-
 # Names of calendars that have the same number of days for all years
 uniform_calendars = ("noleap", "all_leap", "365_day", "366_day", "360_day")
 

xclim/indicators/atmos/_temperature.py

@@ -626,7 +626,53 @@ class TempWithIndexing(ResamplingIndicatorWithIndexing):
     standard_name="day_of_year",
     long_name="First day of year with temperature below {thresh}",
     description="First day of year with temperature below {thresh} for at least {window} days.",
-    compute=indices.first_day_below,
+    compute=indices.first_day_temperature_below,
+    input=dict(tas="tasmin"),
+    _version_deprecated="0.39.0",
+)
+
+first_day_tn_below = Temp(
+    identifier="first_day_tn_below",
+    units="",
+    standard_name="day_of_year",
+    long_name="First day of year with minimum temperature below {thresh}",
+    description="First day of year with minimum temperature below {thresh} for at least {window} days.",
+    compute=indices.first_day_temperature_below,
+    input=dict(tas="tasmin"),
+    parameters=dict(
+        thresh={"default": "0 degC"},
+        after_date={"default": "07-01"},
+        op={"default": "<"},
+    ),
+)
+
+first_day_tg_below = Temp(
+    identifier="first_day_tg_below",
+    units="",
+    standard_name="day_of_year",
+    long_name="First day of year with mean temperature below {thresh}",
+    description="First day of year with mean temperature below {thresh} for at least {window} days.",
+    compute=indices.first_day_temperature_below,
+    parameters=dict(
+        thresh={"default": "0 degC"},
+        after_date={"default": "07-01"},
+        op={"default": "<"},
+    ),
+)
+
+first_day_tx_below = Temp(
+    identifier="first_day_tx_below",
+    units="",
+    standard_name="day_of_year",
+    long_name="First day of year with maximum temperature below {thresh}",
+    description="First day of year with maximum temperature below {thresh} for at least {window} days.",
+    compute=indices.first_day_temperature_below,
+    input=dict(tas="tasmax"),
+    parameters=dict(
+        thresh={"default": "0 degC"},
+        after_date={"default": "07-01"},
+        op={"default": "<"},
+    ),
 )
 
 first_day_above = Temp(
@@ -635,10 +681,56 @@ class TempWithIndexing(ResamplingIndicatorWithIndexing):
     standard_name="day_of_year",
     long_name="First day of year with temperature above {thresh}",
     description="First day of year with temperature above {thresh} for at least {window} days.",
-    compute=indices.first_day_above,
+    compute=indices.first_day_temperature_above,
+    input=dict(tas="tasmin"),
+    _version_deprecated="0.39.0",
+)
+
+first_day_tn_above = Temp(
+    identifier="first_day_tn_above",
+    units="",
+    standard_name="day_of_year",
+    long_name="First day of year with minimum temperature above {thresh}",
+    description="First day of year with minimum temperature above {thresh} for at least {window} days.",
+    compute=indices.first_day_temperature_above,
+    input=dict(tas="tasmin"),
+    parameters=dict(
+        thresh={"default": "0 degC"},
+        after_date={"default": "01-01"},
+        op={"default": ">"},
+    ),
 )
 
 
+first_day_tg_above = Temp(
+    identifier="first_day_tg_above",
+    units="",
+    standard_name="day_of_year",
+    long_name="First day of year with mean temperature above {thresh}",
+    description="First day of year with mean temperature above {thresh} for at least {window} days.",
+    compute=indices.first_day_temperature_above,
+    parameters=dict(
+        thresh={"default": "0 degC"},
+        after_date={"default": "01-01"},
+        op={"default": ">"},
+    ),
+)
+
+first_day_tx_above = Temp(
+    identifier="first_day_tx_above",
+    units="",
+    standard_name="day_of_year",
+    long_name="First day of year with maximum temperature above {thresh}",
+    description="First day of year with maximum temperature above {thresh} for at least {window} days.",
+    compute=indices.first_day_temperature_above,
+    input=dict(tas="tasmax"),
+    parameters=dict(
+        thresh={"default": "0 degC"},
+        after_date={"default": "01-01"},
+        op={"default": ">"},
+    ),
+)
+
 ice_days = TempWithIndexing(
     identifier="ice_days",
     standard_name="days_with_air_temperature_below_threshold",

xclim/indices/_agro.py

@@ -11,7 +11,11 @@
 from xclim.core.calendar import parse_offset, resample_doy, select_time
 from xclim.core.units import convert_units_to, declare_units, rate2amount, to_agg_units
 from xclim.core.utils import DayOfYearStr, uses_dask
-from xclim.indices._threshold import first_day_above, first_day_below, freshet_start
+from xclim.indices._threshold import (
+    first_day_temperature_above,
+    first_day_temperature_below,
+    freshet_start,
+)
 from xclim.indices.generic import aggregate_between_dates
 from xclim.indices.helpers import _gather_lat, day_lengths
 from xclim.indices.stats import dist_method, fit
@@ -1069,7 +1073,7 @@ def effective_growing_degree_days(
         The minimum temperature threshold.
     method : {"bootsma", "qian"}
         The window method used to determine the temperature-based start date.
-        For "bootsma", the start date is defined as 10 days after the average temperature exceeds a threshold (5 degC).
+        For "bootsma", the start date is defined as 10 days after the average temperature exceeds a threshold.
         For "qian", the start date is based on a weighted 5-day rolling average,
         based on :py:func`qian_weighted_mean_average`.
     after_date : str
@@ -1111,7 +1115,7 @@ def effective_growing_degree_days(
     tas.attrs["units"] = "degC"
 
     if method.lower() == "bootsma":
-        fda = first_day_above(tasmin=tas, thresh="5.0 degC", window=1, freq=freq)
+        fda = first_day_temperature_above(tas=tas, thresh=thresh, window=1, freq=freq)
         start = fda + 10
     elif method.lower() == "qian":
         tas_weighted = qian_weighted_mean_average(tas=tas, dim=dim)
@@ -1121,8 +1125,8 @@ def effective_growing_degree_days(
 
     # The day before the first day below 0 degC
     end = (
-        first_day_below(
-            tasmin=tasmin,
+        first_day_temperature_below(
+            tasmin,
             thresh="0 degC",
             after_date=after_date,
             window=1,