0
# Core Computation Functions
1

2
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.
3

4
## Capabilities
5

6
### Temperature Computation Functions
7

8
Basic temperature statistics and derived metrics for climate analysis.
9

10
```python { .api }
11
def tg_mean(tas, freq="YS"):
12
    """
13
    Mean of daily mean temperature.
14
    
15
    Parameters:
16
    - tas: xr.DataArray, daily mean temperature data
17
    - freq: str, resampling frequency (default "YS")
18
    
19
    Returns:
20
    xr.DataArray: Mean temperature aggregated by frequency
21
    """
22

23
def daily_temperature_range(tasmax, tasmin, freq="YS"):
24
    """
25
    Mean diurnal temperature range (tasmax - tasmin).
26
    
27
    Parameters:
28
    - tasmax: xr.DataArray, daily maximum temperature
29
    - tasmin: xr.DataArray, daily minimum temperature  
30
    - freq: str, resampling frequency
31
    
32
    Returns:
33
    xr.DataArray: Mean daily temperature range
34
    """
35

36
def extreme_temperature_range(tasmax, tasmin, freq="YS"):
37
    """
38
    Extreme temperature range (max of tasmax - min of tasmin).
39
    
40
    Parameters:
41
    - tasmax: xr.DataArray, daily maximum temperature
42
    - tasmin: xr.DataArray, daily minimum temperature
43
    - freq: str, resampling frequency
44
    
45
    Returns:
46
    xr.DataArray: Extreme temperature range over period
47
    """
48
```
49

50
### Degree Day Computation Functions
51

52
Temperature accumulation calculations for agricultural and energy applications.
53

54
```python { .api }
55
def growing_degree_days(tas, thresh=4.0, freq="YS"):
56
    """
57
    Accumulated growing degree days above threshold.
58
    
59
    Parameters:
60
    - tas: xr.DataArray, daily mean temperature  
61
    - thresh: float, base threshold temperature in same units as tas
62
    - freq: str, resampling frequency
63
    
64
    Returns:
65
    xr.DataArray: Accumulated growing degree days
66
    """
67

68
def heating_degree_days(tas, thresh=17.0, freq="YS"):
69
    """
70
    Accumulated heating degree days below threshold.
71
    
72
    Parameters:
73
    - tas: xr.DataArray, daily mean temperature
74
    - thresh: float, base threshold temperature in same units as tas
75
    - freq: str, resampling frequency
76
    
77
    Returns:
78
    xr.DataArray: Accumulated heating degree days
79
    """
80

81
def cooling_degree_days(tas, thresh=18.0, freq="YS"):
82
    """
83
    Accumulated cooling degree days above threshold.
84
    
85
    Parameters:
86
    - tas: xr.DataArray, daily mean temperature
87
    - thresh: float, base threshold temperature in same units as tas
88
    - freq: str, resampling frequency
89
    
90
    Returns:
91
    xr.DataArray: Accumulated cooling degree days  
92
    """
93

94
def freshing_degree_days(tas, thresh=0.0, freq="YS"):
95
    """
96
    Accumulated freshing degree days below freezing.
97
    
98
    Parameters:
99
    - tas: xr.DataArray, daily mean temperature
100
    - thresh: float, freezing threshold in same units as tas (default 0.0)
101
    - freq: str, resampling frequency
102
    
103
    Returns:
104
    xr.DataArray: Accumulated freshing degree days
105
    """
106
```
107

108
### Precipitation Computation Functions
109

110
Precipitation statistics and derived indices for hydrological analysis.
111

112
```python { .api }
113
def precip_accumulation(pr, freq="YS"):
114
    """
115
    Total precipitation accumulation.
116
    
117
    Parameters:
118
    - pr: xr.DataArray, daily precipitation data
119
    - freq: str, resampling frequency
120
    
121
    Returns:
122
    xr.DataArray: Total precipitation amount
123
    """
124

125
def wetdays(pr, thresh=1.0, freq="YS"):
126
    """
127
    Number of wet days (precipitation >= threshold).
128
    
129
    Parameters:
130
    - pr: xr.DataArray, daily precipitation data
131
    - thresh: float, wet day threshold in same units as pr (default 1.0)
132
    - freq: str, resampling frequency
133
    
134
    Returns:
135
    xr.DataArray: Number of wet days
136
    """
137

138
def dry_days(pr, thresh=1.0, freq="YS"):
139
    """
140
    Number of dry days (precipitation < threshold).
141
    
142
    Parameters:
143
    - pr: xr.DataArray, daily precipitation data
144
    - thresh: float, dry day threshold in same units as pr (default 1.0)
145
    - freq: str, resampling frequency
146
    
147
    Returns:
148
    xr.DataArray: Number of dry days
149
    """
150

151
def maximum_consecutive_wet_days(pr, thresh=1.0, freq="YS"):
152
    """
153
    Maximum number of consecutive wet days.
154
    
155
    Parameters:
156
    - pr: xr.DataArray, daily precipitation data
157
    - thresh: float, wet day threshold in same units as pr
158
    - freq: str, resampling frequency
159
    
160
    Returns:
161
    xr.DataArray: Maximum consecutive wet days
162
    """
163

164
def maximum_consecutive_dry_days(pr, thresh=1.0, freq="YS"):
165
    """
166
    Maximum number of consecutive dry days.
167
    
168
    Parameters:
169
    - pr: xr.DataArray, daily precipitation data
170
    - thresh: float, dry day threshold in same units as pr
171
    - freq: str, resampling frequency
172
    
173
    Returns:
174
    xr.DataArray: Maximum consecutive dry days
175
    """
176

177
def daily_pr_intensity(pr, thresh=1.0, freq="YS"):
178
    """
179
    Simple daily intensity index (mean precipitation on wet days).
180
    
181
    Parameters:
182
    - pr: xr.DataArray, daily precipitation data
183
    - thresh: float, wet day threshold in same units as pr
184
    - freq: str, resampling frequency
185
    
186
    Returns:
187
    xr.DataArray: Mean precipitation intensity on wet days
188
    """
189

190
def max_n_day_precipitation_amount(pr, window=1, freq="YS"):
191
    """
192
    Maximum N-day precipitation amount.
193
    
194
    Parameters:
195
    - pr: xr.DataArray, daily precipitation data
196
    - window: int, number of consecutive days for accumulation
197
    - freq: str, resampling frequency
198
    
199
    Returns:
200
    xr.DataArray: Maximum N-day precipitation total
201
    """
202
```
203

204
### Threshold-based Computation Functions
205

206
Generic threshold exceedance calculations applicable to any climate variable.
207

208
```python { .api }
209
def days_over_precip_thresh(pr, thresh=10.0, freq="YS"):
210
    """
211
    Number of days with precipitation over threshold.
212
    
213
    Parameters:
214
    - pr: xr.DataArray, daily precipitation data
215
    - thresh: float, precipitation threshold in same units as pr
216
    - freq: str, resampling frequency
217
    
218
    Returns:
219
    xr.DataArray: Number of days above threshold
220
    """
221

222
def fraction_over_precip_thresh(pr, thresh=10.0, freq="YS"):
223
    """
224
    Fraction of days with precipitation over threshold.
225
    
226
    Parameters:
227
    - pr: xr.DataArray, daily precipitation data
228
    - thresh: float, precipitation threshold in same units as pr
229
    - freq: str, resampling frequency
230
    
231
    Returns:
232
    xr.DataArray: Fraction of days above threshold (0-1)
233
    """
234

235
def tx_days_above(tasmax, thresh=25.0, freq="YS"):
236
    """
237
    Number of days with maximum temperature above threshold.
238
    
239
    Parameters:
240
    - tasmax: xr.DataArray, daily maximum temperature
241
    - thresh: float, temperature threshold in same units as tasmax
242
    - freq: str, resampling frequency
243
    
244
    Returns:
245
    xr.DataArray: Number of days above threshold
246
    """
247

248
def tn_days_below(tasmin, thresh=0.0, freq="YS"):
249
    """
250
    Number of days with minimum temperature below threshold.
251
    
252
    Parameters:
253
    - tasmin: xr.DataArray, daily minimum temperature
254
    - thresh: float, temperature threshold in same units as tasmin
255
    - freq: str, resampling frequency
256
    
257
    Returns:
258
    xr.DataArray: Number of days below threshold
259
    """
260

261
def temperature_sum(tas, thresh=10.0, freq="YS"):
262
    """
263
    Sum of temperature values above threshold.
264
    
265
    Parameters:
266
    - tas: xr.DataArray, daily temperature data
267
    - thresh: float, base threshold temperature in same units as tas
268
    - freq: str, resampling frequency
269
    
270
    Returns:
271
    xr.DataArray: Accumulated temperature sum above threshold
272
    """
273
```
274

275
### Generic Statistical Functions
276

277
General statistical operations applicable to any climate variable.
278

279
```python { .api }
280
def select_resample_op(da, op, freq="YS", **kwargs):
281
    """
282
    Apply statistical operation during resampling.
283
    
284
    Parameters:
285
    - da: xr.DataArray, input data
286
    - op: str or callable, statistical operation ('mean', 'max', 'min', 'sum', etc.)
287
    - freq: str, resampling frequency
288
    - **kwargs: additional arguments passed to operation
289
    
290
    Returns:
291
    xr.DataArray: Resampled data with operation applied
292
    """
293

294
def threshold_count(da, threshold, op=operator.ge, freq="YS"):
295
    """
296
    Count of values meeting threshold condition.
297
    
298
    Parameters:
299
    - da: xr.DataArray, input data
300
    - threshold: float, threshold value for comparison
301
    - op: callable, comparison operator (default operator.ge for >=)
302
    - freq: str, resampling frequency
303
    
304
    Returns:
305
    xr.DataArray: Count of values meeting condition
306
    """
307

308
def spell_length(da, threshold, op=operator.ge, freq="YS"):
309
    """
310
    Length statistics of spells meeting threshold condition.
311
    
312
    Parameters:
313
    - da: xr.DataArray, input data
314
    - threshold: float, threshold value for comparison
315
    - op: callable, comparison operator (default operator.ge)
316
    - freq: str, resampling frequency
317
    
318
    Returns:
319
    xr.DataArray: Spell length statistics
320
    """
321

322
def run_length(da, freq="YS"):
323
    """
324
    Run length encoding of consecutive values.
325
    
326
    Parameters:
327
    - da: xr.DataArray, input data (typically boolean)
328
    - freq: str, resampling frequency
329
    
330
    Returns:
331
    xr.DataArray: Run length statistics
332
    """
333

334
def first_occurrence(da, threshold, op=operator.ge, freq="YS"):
335
    """
336
    Day of year of first occurrence of condition.
337
    
338
    Parameters:
339
    - da: xr.DataArray, input data  
340
    - threshold: float, threshold value
341
    - op: callable, comparison operator
342
    - freq: str, resampling frequency
343
    
344
    Returns:
345
    xr.DataArray: Day of year of first occurrence
346
    """
347

348
def last_occurrence(da, threshold, op=operator.ge, freq="YS"):
349
    """
350
    Day of year of last occurrence of condition.
351
    
352
    Parameters:
353
    - da: xr.DataArray, input data
354
    - threshold: float, threshold value
355
    - op: callable, comparison operator
356
    - freq: str, resampling frequency
357
    
358
    Returns:
359
    xr.DataArray: Day of year of last occurrence
360
    """
361
```
362

363
## Usage Examples
364

365
### Direct Temperature Calculations
366

367
```python
368
import xarray as xr
369
import xclim.indices as xci
370

371
# Load temperature data
372
ds = xr.tutorial.open_dataset("air_temperature")
373
tas = ds.air.rename("tas")  
374

375
# Direct computation (no unit conversion)
376
gdd = xci.growing_degree_days(tas, thresh=283.15, freq="YS")  # Kelvin
377
heat_days = xci.tx_days_above(tas, thresh=298.15, freq="YS")  # Kelvin
378

379
# Temperature range calculations
380
tasmax = tas + 2  # Create example tasmax
381
tasmin = tas - 3  # Create example tasmin
382
dtr = xci.daily_temperature_range(tasmax, tasmin, freq="YS")
383
```
384

385
### Precipitation Calculations
386

387
```python
388
# Precipitation computations (assuming pr in mm/day)
389
pr = ds.precip.rename("pr")  # assuming precip exists
390
total_pr = xci.precip_accumulation(pr, freq="YS")
391
wet_days = xci.wetdays(pr, thresh=1.0, freq="YS")  
392
heavy_days = xci.days_over_precip_thresh(pr, thresh=10.0, freq="YS")
393
max_dry = xci.maximum_consecutive_dry_days(pr, thresh=1.0, freq="YS")
394
```
395

396
### Generic Statistical Operations
397

398
```python
399
# Apply statistical operations
400
annual_mean = xci.select_resample_op(tas, op="mean", freq="YS")
401
annual_max = xci.select_resample_op(tas, op="max", freq="YS")
402

403
# Threshold analysis
404
hot_days = xci.threshold_count(tas, threshold=298.15, op=operator.ge, freq="YS")
405
cold_days = xci.threshold_count(tas, threshold=273.15, op=operator.lt, freq="YS")
406
```
407

408
### Spell Analysis
409

410
```python
411
import operator
412

413
# Heat wave analysis (assuming daily max temp in Kelvin)
414
heat_spells = xci.spell_length(
415
    tasmax, 
416
    threshold=303.15,  # 30°C in Kelvin
417
    op=operator.ge,
418
    freq="YS"
419
)
420

421
# Drought analysis  
422
drought_spells = xci.spell_length(
423
    pr < 1.0,  # Create boolean array for dry days
424
    threshold=True,
425
    op=operator.eq,
426
    freq="YS"
427
)
428
```