v0.58.0

Contributors to this version: Sebastian Lehner (@seblehner), Trevor James Smith (@Zeitsperre), Pascal Bourgault (@aulemahal), Éric Dupuis (@coxipi), Baptiste Hamon (@baptistehamon).

New indicators and features

• New indicator xclim.atmos.antecedent_precipitation_index computes the antecedent_precipitation_index (weighted summation of daily precipitation amounts for a given window). (GH/2166, PR/2184).
• Argument indexer added to indicators max_n_day_precipitation_amount, max_pr_intensity, and blowing_snow. (GH/2187, PR/2190).
• Argument window added to indicator rain_on_frozen_ground_days. (PR/2190).
• New helper xclim.indices.generic.season_length_from_boundaries takes season_start and season_end as input and gives season_length. This is used when starts and ends are computed with different resampling frequencies: days_since are used to compute temporal lengths in this case. (PR/2189).
• Allow invalid_values as argument for relative_humidity_from_dewpoint. (GH/2202, PR/2203).
• New thermodynamic conversion indicators (GH/2165, PR/2206):
  • xclim.convert.vapor_pressure to compute the partial pressure of water vapor from specific humidity and total pressure.
  • xclim.convert.dewpoint_from_specific_humidity to compute the dewpoint temperature from specific humidity and total pressure.
• All functions using saturation vapour pressure can now compute it with a smooth transition between saturation over ice and saturation over water. The transition is controlled by the interp_power , ice_thresh and water_thresh parameters. (GH/2165, PR/2206).
  • New methods "buck81" and "aerk96" and new method "ECMWF" which is "buck81" on water and "aerk96" on ice.
  • Saturation vapor pressure calculations were reorganized. xclim.indices.converters.ESAT_FORMULAS_COEFFICIENTS now stores the August-Roche-Magnus formula's coefficients.
• New indicator xclim.atmos.hot_days as counterpart to xclim.atmos.frost_days. (GH/2194, PR/2213).
• New helper indices for computing the day-length coefficient for viticulture growing seasons based on several approaches:
  • xclim.indices.helpers.gladstones_day_length_coefficient: Based on the Gladstones (1992, 2011) method.
  • xclim.indices.helpers.huglin_day_length_coefficient: Based on the Huglin (1978, 1998) method.
  • xclim.indices.helpers.jones_day_length_coefficient: Based on the approach outlined in Hall and Jones (2010).
• 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). (GH/2201, PR/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. (PR/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. (GH/1289, PR/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. (PR/2208, GH/1752).

Breaking changes

• The "jones" method for calculating 'k' in xclim.indices.huglin_index and xclim.indices.biologically_effective_degree_days now require daily data computed at annual frequencies (freq="YS"|"YS-JAN"|"YS-JUL"). The previous behaviour for non-annual frequencies was undefined. (GH/2201, PR/2207).
  • The "jones" method now sets a floor value for "k" where it is not allowed to be less than 1.0. This is to avoid values below 1.0 for "k" which were previously allowed in xclim but not supported by the source literature.
  • Incomplete growing seasons (where the values of "k" for all latitudes during the growing season are all below 1.0) will now raise ValueError. This is to ensure that the expected output is consistent with the literature.
• The "gladstones" method for calculating 'k' in xclim.indices.biologically_effective_degree_days now uses a dedicated function based on a dynamic day_length compared to a reference latitude (40 degrees). The previous implementation of the "gladstones" method was based off an approximation found in Hall and Jones (2010). (GH/2201, PR/2207).
  • The "gladstones" approximation is now available as a separate helper function: xclim.indices.helpers.jones_day_length_coefficient with method="gladstones".
• The "icclim" method for calculating 'k' in xclim.indices.huglin_index has been renamed the "huglin" method. The "icclim" method was identical to the implementation proposed in Huglin (1978). (GH/2201, PR/2207).
• The xclim.indices._conversion submodule has been refactored into the new xclim.indices.converters module. Directly importing functions from the older location will still work but will emit a DeprecationWarning. This workaround will be removed in a future release. (GH/1289, PR/2224).
• The xclim.indicators.atmos and xclim.indicators.land submodules have been refactored to move all conversion-based indicators to the new xclim.indices.converters module. This change is intended to improve code organization and clarity. Directly importing indicators that were previously accessible via atmos and land will still work but will emit a DeprecationWarning. This workaround will be removed in a future release. (GH/1289, PR/2224).
• xclim.indicators.atmos.tg has been refactored to xclim.indicators.convert.mean_temperature_from_max_and_min. Importing tg from xclim.indices.atmos or xclim.indicators.convert will still work but will emit a DeprecationWarning. This workaround will be removed in a future release. (GH/1289, PR/2224).

Internal changes

• Modified internal logic for xclim.testing.utils.default_testdata_cache to support mocking of pooch. (PR/2188).
• The xclim.indices.helpers module now uses an __all__ variable to explicitly define the public API of the module. (PR/2207).
• Viticulture indices are more heavily tested and employ type guarding to ensure that parameters passed are those of the expected types. (PR/2207).
• Fixed some tests relying on floating-point imprecision. Avoid numbagg on sensitive fitting tests. (PR/2228).
• Conversion indicators have been split from tests/test_atmos.py into new tests/test_converters.py. This is to ensure that conversion indicators are tested separately from other atmospheric indicators. (GH/1289, PR/2224).
• xclim.testing.utils.show_versions now uses the importlib.metadata library to more accurately gather dependency information. (PR/2229).
• Replaced the deprecated "time.week" grouping strings with da.time.dt.isocalendar().week in xclim.indices.stats.standardized_index functions. (PR/2230).
• xclim.indices.run_length.lazy_indexing moved to utils. (GH/2107, PR/2231).
• Updated the command-line configuration to address DeprecationWarning messages introduced in click v8.2.0 (changes remain compatible with click v8.1.0). (GH/2212, PR/2233).

Bug fixes

• Increase the tolerance in the tests of xclim.indices.standardized_groundwater_index (the standardized indices are sensitive to package versions because of the parameter optimization in scipy). (GH/2183, PR/2193).
• In xclim.indices._conversion.humidex and xclim.indices._conversion.vapor_pressure_deficit, add a converter to ensure hurs has '%' units. (PR/2209).
• Indices relying on units.to_agg_units(src, out, 'count') will not raise on a non-inferrable frequency and instead use the common default of "D", as their docstring implies. (GH/2215, PR/2217).
• Fix spell_length_statistics and related functions for cases where thresh is a DataArray. (GH/2216, PR/2218).
• Addressed a noisy warning emitted by numpy in the xclim.indices.stats when performing a fit over data with missing values. (PR/2224).
• In the Canadian Forest Fire Weather Index System, values of 0 for both the Duff-Moisture code (DMC) and the Drought code (DC) will yield a 0 Build-Up index (BUI) instead of failing with division by zero error. (GH/2145, PR/2225).
• xclim.indices.generic.{doymax|doymin} now work with dask arrays. (GH/2107, PR/2231).