tessl/pypi-xclim
Climate indices computation package based on Xarray with extensive climate analysis capabilities
core-computation.mddocs/
Core Computation Functions
Low-level mathematical functions for climate indices calculation. These functions provide the computational engine underlying all XClim indicators, operating directly on xarray DataArrays without automatic unit conversion or validation.
Capabilities
Temperature Computation Functions
Basic temperature statistics and derived metrics for climate analysis.
def tg_mean(tas, freq="YS"):
"""
Mean of daily mean temperature.
Parameters:
- tas: xr.DataArray, daily mean temperature data
- freq: str, resampling frequency (default "YS")
Returns:
xr.DataArray: Mean temperature aggregated by frequency
"""
def daily_temperature_range(tasmax, tasmin, freq="YS"):
"""
Mean diurnal temperature range (tasmax - tasmin).
Parameters:
- tasmax: xr.DataArray, daily maximum temperature
- tasmin: xr.DataArray, daily minimum temperature
- freq: str, resampling frequency
Returns:
xr.DataArray: Mean daily temperature range
"""
def extreme_temperature_range(tasmax, tasmin, freq="YS"):
"""
Extreme temperature range (max of tasmax - min of tasmin).
Parameters:
- tasmax: xr.DataArray, daily maximum temperature
- tasmin: xr.DataArray, daily minimum temperature
- freq: str, resampling frequency
Returns:
xr.DataArray: Extreme temperature range over period
"""Degree Day Computation Functions
Temperature accumulation calculations for agricultural and energy applications.
def growing_degree_days(tas, thresh=4.0, freq="YS"):
"""
Accumulated growing degree days above threshold.
Parameters:
- tas: xr.DataArray, daily mean temperature
- thresh: float, base threshold temperature in same units as tas
- freq: str, resampling frequency
Returns:
xr.DataArray: Accumulated growing degree days
"""
def heating_degree_days(tas, thresh=17.0, freq="YS"):
"""
Accumulated heating degree days below threshold.
Parameters:
- tas: xr.DataArray, daily mean temperature
- thresh: float, base threshold temperature in same units as tas
- freq: str, resampling frequency
Returns:
xr.DataArray: Accumulated heating degree days
"""
def cooling_degree_days(tas, thresh=18.0, freq="YS"):
"""
Accumulated cooling degree days above threshold.
Parameters:
- tas: xr.DataArray, daily mean temperature
- thresh: float, base threshold temperature in same units as tas
- freq: str, resampling frequency
Returns:
xr.DataArray: Accumulated cooling degree days
"""
def freshing_degree_days(tas, thresh=0.0, freq="YS"):
"""
Accumulated freshing degree days below freezing.
Parameters:
- tas: xr.DataArray, daily mean temperature
- thresh: float, freezing threshold in same units as tas (default 0.0)
- freq: str, resampling frequency
Returns:
xr.DataArray: Accumulated freshing degree days
"""Precipitation Computation Functions
Precipitation statistics and derived indices for hydrological analysis.
def precip_accumulation(pr, freq="YS"):
"""
Total precipitation accumulation.
Parameters:
- pr: xr.DataArray, daily precipitation data
- freq: str, resampling frequency
Returns:
xr.DataArray: Total precipitation amount
"""
def wetdays(pr, thresh=1.0, freq="YS"):
"""
Number of wet days (precipitation >= threshold).
Parameters:
- pr: xr.DataArray, daily precipitation data
- thresh: float, wet day threshold in same units as pr (default 1.0)
- freq: str, resampling frequency
Returns:
xr.DataArray: Number of wet days
"""
def dry_days(pr, thresh=1.0, freq="YS"):
"""
Number of dry days (precipitation < threshold).
Parameters:
- pr: xr.DataArray, daily precipitation data
- thresh: float, dry day threshold in same units as pr (default 1.0)
- freq: str, resampling frequency
Returns:
xr.DataArray: Number of dry days
"""
def maximum_consecutive_wet_days(pr, thresh=1.0, freq="YS"):
"""
Maximum number of consecutive wet days.
Parameters:
- pr: xr.DataArray, daily precipitation data
- thresh: float, wet day threshold in same units as pr
- freq: str, resampling frequency
Returns:
xr.DataArray: Maximum consecutive wet days
"""
def maximum_consecutive_dry_days(pr, thresh=1.0, freq="YS"):
"""
Maximum number of consecutive dry days.
Parameters:
- pr: xr.DataArray, daily precipitation data
- thresh: float, dry day threshold in same units as pr
- freq: str, resampling frequency
Returns:
xr.DataArray: Maximum consecutive dry days
"""
def daily_pr_intensity(pr, thresh=1.0, freq="YS"):
"""
Simple daily intensity index (mean precipitation on wet days).
Parameters:
- pr: xr.DataArray, daily precipitation data
- thresh: float, wet day threshold in same units as pr
- freq: str, resampling frequency
Returns:
xr.DataArray: Mean precipitation intensity on wet days
"""
def max_n_day_precipitation_amount(pr, window=1, freq="YS"):
"""
Maximum N-day precipitation amount.
Parameters:
- pr: xr.DataArray, daily precipitation data
- window: int, number of consecutive days for accumulation
- freq: str, resampling frequency
Returns:
xr.DataArray: Maximum N-day precipitation total
"""Threshold-based Computation Functions
Generic threshold exceedance calculations applicable to any climate variable.
def days_over_precip_thresh(pr, thresh=10.0, freq="YS"):
"""
Number of days with precipitation over threshold.
Parameters:
- pr: xr.DataArray, daily precipitation data
- thresh: float, precipitation threshold in same units as pr
- freq: str, resampling frequency
Returns:
xr.DataArray: Number of days above threshold
"""
def fraction_over_precip_thresh(pr, thresh=10.0, freq="YS"):
"""
Fraction of days with precipitation over threshold.
Parameters:
- pr: xr.DataArray, daily precipitation data
- thresh: float, precipitation threshold in same units as pr
- freq: str, resampling frequency
Returns:
xr.DataArray: Fraction of days above threshold (0-1)
"""
def tx_days_above(tasmax, thresh=25.0, freq="YS"):
"""
Number of days with maximum temperature above threshold.
Parameters:
- tasmax: xr.DataArray, daily maximum temperature
- thresh: float, temperature threshold in same units as tasmax
- freq: str, resampling frequency
Returns:
xr.DataArray: Number of days above threshold
"""
def tn_days_below(tasmin, thresh=0.0, freq="YS"):
"""
Number of days with minimum temperature below threshold.
Parameters:
- tasmin: xr.DataArray, daily minimum temperature
- thresh: float, temperature threshold in same units as tasmin
- freq: str, resampling frequency
Returns:
xr.DataArray: Number of days below threshold
"""
def temperature_sum(tas, thresh=10.0, freq="YS"):
"""
Sum of temperature values above threshold.
Parameters:
- tas: xr.DataArray, daily temperature data
- thresh: float, base threshold temperature in same units as tas
- freq: str, resampling frequency
Returns:
xr.DataArray: Accumulated temperature sum above threshold
"""Generic Statistical Functions
General statistical operations applicable to any climate variable.
def select_resample_op(da, op, freq="YS", **kwargs):
"""
Apply statistical operation during resampling.
Parameters:
- da: xr.DataArray, input data
- op: str or callable, statistical operation ('mean', 'max', 'min', 'sum', etc.)
- freq: str, resampling frequency
- **kwargs: additional arguments passed to operation
Returns:
xr.DataArray: Resampled data with operation applied
"""
def threshold_count(da, threshold, op=operator.ge, freq="YS"):
"""
Count of values meeting threshold condition.
Parameters:
- da: xr.DataArray, input data
- threshold: float, threshold value for comparison
- op: callable, comparison operator (default operator.ge for >=)
- freq: str, resampling frequency
Returns:
xr.DataArray: Count of values meeting condition
"""
def spell_length(da, threshold, op=operator.ge, freq="YS"):
"""
Length statistics of spells meeting threshold condition.
Parameters:
- da: xr.DataArray, input data
- threshold: float, threshold value for comparison
- op: callable, comparison operator (default operator.ge)
- freq: str, resampling frequency
Returns:
xr.DataArray: Spell length statistics
"""
def run_length(da, freq="YS"):
"""
Run length encoding of consecutive values.
Parameters:
- da: xr.DataArray, input data (typically boolean)
- freq: str, resampling frequency
Returns:
xr.DataArray: Run length statistics
"""
def first_occurrence(da, threshold, op=operator.ge, freq="YS"):
"""
Day of year of first occurrence of condition.
Parameters:
- da: xr.DataArray, input data
- threshold: float, threshold value
- op: callable, comparison operator
- freq: str, resampling frequency
Returns:
xr.DataArray: Day of year of first occurrence
"""
def last_occurrence(da, threshold, op=operator.ge, freq="YS"):
"""
Day of year of last occurrence of condition.
Parameters:
- da: xr.DataArray, input data
- threshold: float, threshold value
- op: callable, comparison operator
- freq: str, resampling frequency
Returns:
xr.DataArray: Day of year of last occurrence
"""Usage Examples
Direct Temperature Calculations
import xarray as xr
import xclim.indices as xci
# Load temperature data
ds = xr.tutorial.open_dataset("air_temperature")
tas = ds.air.rename("tas")
# Direct computation (no unit conversion)
gdd = xci.growing_degree_days(tas, thresh=283.15, freq="YS") # Kelvin
heat_days = xci.tx_days_above(tas, thresh=298.15, freq="YS") # Kelvin
# Temperature range calculations
tasmax = tas + 2 # Create example tasmax
tasmin = tas - 3 # Create example tasmin
dtr = xci.daily_temperature_range(tasmax, tasmin, freq="YS")Precipitation Calculations
# Precipitation computations (assuming pr in mm/day)
pr = ds.precip.rename("pr") # assuming precip exists
total_pr = xci.precip_accumulation(pr, freq="YS")
wet_days = xci.wetdays(pr, thresh=1.0, freq="YS")
heavy_days = xci.days_over_precip_thresh(pr, thresh=10.0, freq="YS")
max_dry = xci.maximum_consecutive_dry_days(pr, thresh=1.0, freq="YS")Generic Statistical Operations
# Apply statistical operations
annual_mean = xci.select_resample_op(tas, op="mean", freq="YS")
annual_max = xci.select_resample_op(tas, op="max", freq="YS")
# Threshold analysis
hot_days = xci.threshold_count(tas, threshold=298.15, op=operator.ge, freq="YS")
cold_days = xci.threshold_count(tas, threshold=273.15, op=operator.lt, freq="YS")Spell Analysis
import operator
# Heat wave analysis (assuming daily max temp in Kelvin)
heat_spells = xci.spell_length(
tasmax,
threshold=303.15, # 30°C in Kelvin
op=operator.ge,
freq="YS"
)
# Drought analysis
drought_spells = xci.spell_length(
pr < 1.0, # Create boolean array for dry days
threshold=True,
op=operator.eq,
freq="YS"
)