0
# Atmospheric Indicators
1

2
Comprehensive atmospheric climate indicators for temperature, precipitation, wind, and humidity analysis. These indicators provide standardized climate metrics used in climate services, impact assessment, and adaptation planning.
3

4
## Capabilities
5

6
### Temperature Indicators
7

8
#### Mean Temperature Metrics
9

10
Basic temperature statistics and averages for climate monitoring and trend analysis.
11

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

25
def tx_mean(tasmax, freq="YS"):
26
    """
27
    Mean of daily maximum temperature.
28
    
29
    Parameters:
30
    - tasmax: xr.DataArray, daily maximum temperature data
31
    - freq: str, resampling frequency
32
    
33
    Returns:
34
    xr.DataArray: Mean of daily maximum temperatures
35
    """
36

37
def tn_mean(tasmin, freq="YS"):
38
    """
39
    Mean of daily minimum temperature.
40
    
41
    Parameters:
42
    - tasmin: xr.DataArray, daily minimum temperature data
43
    - freq: str, resampling frequency
44
    
45
    Returns:
46
    xr.DataArray: Mean of daily minimum temperatures
47
    """
48
```
49

50
#### Extreme Temperature Metrics
51

52
Temperature extremes and ranges for heat wave and cold spell analysis.
53

54
```python { .api }
55
def tx_max(tasmax, freq="YS"):
56
    """
57
    Maximum of daily maximum temperature.
58
    
59
    Parameters:
60
    - tasmax: xr.DataArray, daily maximum temperature data
61
    - freq: str, resampling frequency
62
    
63
    Returns:
64
    xr.DataArray: Maximum temperature over period
65
    """
66

67
def tn_min(tasmin, freq="YS"):
68
    """
69
    Minimum of daily minimum temperature.
70
    
71
    Parameters:
72
    - tasmin: xr.DataArray, daily minimum temperature data
73
    - freq: str, resampling frequency
74
    
75
    Returns:
76
    xr.DataArray: Minimum temperature over period
77
    """
78

79
def dtr(tasmax, tasmin, freq="YS"):
80
    """
81
    Mean diurnal temperature range.
82
    
83
    Parameters:
84
    - tasmax: xr.DataArray, daily maximum temperature
85
    - tasmin: xr.DataArray, daily minimum temperature  
86
    - freq: str, resampling frequency
87
    
88
    Returns:
89
    xr.DataArray: Mean daily temperature range
90
    """
91

92
def etr(tasmax, tasmin, freq="YS"):
93
    """
94
    Extreme temperature range (max of tasmax - min of tasmin).
95
    
96
    Parameters:
97
    - tasmax: xr.DataArray, daily maximum temperature
98
    - tasmin: xr.DataArray, daily minimum temperature
99
    - freq: str, resampling frequency
100
    
101
    Returns:
102
    xr.DataArray: Extreme temperature range
103
    """
104
```
105

106
### Degree Day Indicators
107

108
Temperature accumulation indices for agricultural and energy applications.
109

110
```python { .api }
111
def growing_degree_days(tas, thresh="4.0 degC", freq="YS"):
112
    """
113
    Growing degree days above threshold temperature.
114
    
115
    Parameters:
116
    - tas: xr.DataArray, daily mean temperature
117
    - thresh: str or float, base threshold temperature (default "4.0 degC")
118
    - freq: str, resampling frequency
119
    
120
    Returns:
121
    xr.DataArray: Accumulated growing degree days
122
    """
123

124
def heating_degree_days(tas, thresh="17 degC", freq="YS"):
125
    """
126
    Heating degree days below threshold temperature.
127
    
128
    Parameters:
129
    - tas: xr.DataArray, daily mean temperature
130
    - thresh: str or float, base threshold temperature (default "17 degC")
131
    - freq: str, resampling frequency
132
    
133
    Returns:
134
    xr.DataArray: Accumulated heating degree days
135
    """
136

137
def cooling_degree_days(tas, thresh="18 degC", freq="YS"):
138
    """
139
    Cooling degree days above threshold temperature.
140
    
141
    Parameters:
142
    - tas: xr.DataArray, daily mean temperature
143
    - thresh: str or float, base threshold temperature (default "18 degC")
144
    - freq: str, resampling frequency
145
    
146
    Returns:
147
    xr.DataArray: Accumulated cooling degree days
148
    """
149

150
def freshing_degree_days(tas, thresh="0 degC", freq="YS"):
151
    """
152
    Freshing degree days below freezing point.
153
    
154
    Parameters:
155
    - tas: xr.DataArray, daily mean temperature
156
    - thresh: str or float, freezing threshold (default "0 degC")
157
    - freq: str, resampling frequency
158
    
159
    Returns:
160
    xr.DataArray: Accumulated freshing degree days
161
    """
162
```
163

164
### Temperature Threshold Indicators
165

166
Count-based temperature indices for climate extremes analysis.
167

168
```python { .api }
169
def tx_days_above(tasmax, thresh="25 degC", freq="YS"):
170
    """
171
    Number of days with maximum temperature above threshold.
172
    
173
    Parameters:
174
    - tasmax: xr.DataArray, daily maximum temperature
175
    - thresh: str or float, temperature threshold (default "25 degC")
176
    - freq: str, resampling frequency
177
    
178
    Returns:
179
    xr.DataArray: Number of days above threshold
180
    """
181

182
def tn_days_below(tasmin, thresh="0 degC", freq="YS"):
183
    """
184
    Number of days with minimum temperature below threshold.
185
    
186
    Parameters:
187
    - tasmin: xr.DataArray, daily minimum temperature
188
    - thresh: str or float, temperature threshold (default "0 degC")
189
    - freq: str, resampling frequency
190
    
191
    Returns:
192
    xr.DataArray: Number of days below threshold
193
    """
194

195
def frost_days(tasmin, thresh="0 degC", freq="YS"):
196
    """
197
    Number of frost days (minimum temperature below 0°C).
198
    
199
    Parameters:
200
    - tasmin: xr.DataArray, daily minimum temperature
201
    - thresh: str or float, frost threshold (default "0 degC")
202
    - freq: str, resampling frequency
203
    
204
    Returns:
205
    xr.DataArray: Number of frost days
206
    """
207

208
def ice_days(tasmax, thresh="0 degC", freq="YS"):
209
    """
210
    Number of ice days (maximum temperature below 0°C).
211
    
212
    Parameters:
213
    - tasmax: xr.DataArray, daily maximum temperature
214
    - thresh: str or float, ice threshold (default "0 degC")  
215
    - freq: str, resampling frequency
216
    
217
    Returns:
218
    xr.DataArray: Number of ice days
219
    """
220

221
def summer_days(tasmax, thresh="25 degC", freq="YS"):
222
    """
223
    Number of summer days (maximum temperature above 25°C).
224
    
225
    Parameters:
226
    - tasmax: xr.DataArray, daily maximum temperature
227
    - thresh: str or float, summer threshold (default "25 degC")
228
    - freq: str, resampling frequency
229
    
230
    Returns:
231
    xr.DataArray: Number of summer days
232
    """
233

234
def tropical_nights(tasmin, thresh="20 degC", freq="YS"):
235
    """
236
    Number of tropical nights (minimum temperature above 20°C).
237
    
238
    Parameters:
239
    - tasmin: xr.DataArray, daily minimum temperature
240
    - thresh: str or float, tropical threshold (default "20 degC")
241
    - freq: str, resampling frequency
242
    
243
    Returns:
244
    xr.DataArray: Number of tropical nights
245
    """
246
```
247

248
### Heat Wave and Cold Spell Indicators
249

250
Extended temperature extreme event detection and characterization.
251

252
```python { .api }
253
def hot_spell_frequency(tasmax, thresh_tasmax="30 degC", window=3, freq="YS"):
254
    """
255
    Number of hot spell events above temperature threshold.
256
    
257
    Parameters:
258
    - tasmax: xr.DataArray, daily maximum temperature
259
    - thresh_tasmax: str or float, temperature threshold (default "30 degC")
260
    - window: int, minimum number of consecutive days (default 3)
261
    - freq: str, resampling frequency
262
    
263
    Returns:
264
    xr.DataArray: Number of hot spell events
265
    """
266

267
def cold_spell_frequency(tasmin, thresh_tasmin="-10 degC", window=3, freq="YS"):
268
    """
269
    Number of cold spell events below temperature threshold.
270
    
271
    Parameters:
272
    - tasmin: xr.DataArray, daily minimum temperature
273
    - thresh_tasmin: str or float, temperature threshold (default "-10 degC")
274
    - window: int, minimum number of consecutive days (default 3)
275
    - freq: str, resampling frequency
276
    
277
    Returns:
278
    xr.DataArray: Number of cold spell events
279
    """
280

281
def hot_spell_max_length(tasmax, thresh_tasmax="30 degC", window=3, freq="YS"):
282
    """
283
    Maximum length of hot spell events.
284
    
285
    Parameters:
286
    - tasmax: xr.DataArray, daily maximum temperature
287
    - thresh_tasmax: str or float, temperature threshold
288
    - window: int, minimum number of consecutive days
289
    - freq: str, resampling frequency
290
    
291
    Returns:
292
    xr.DataArray: Maximum hot spell length in days
293
    """
294
```
295

296
### Precipitation Indicators
297

298
#### Precipitation Amount Metrics
299

300
Basic precipitation statistics and accumulation measures.
301

302
```python { .api }
303
def prcptot(pr, thresh="1 mm/day", freq="YS"):
304
    """
305
    Total precipitation from wet days.
306
    
307
    Parameters:
308
    - pr: xr.DataArray, daily precipitation data
309
    - thresh: str or float, wet day threshold (default "1 mm/day")
310
    - freq: str, resampling frequency
311
    
312
    Returns:
313
    xr.DataArray: Total precipitation amount
314
    """
315

316
def pr_max(pr, freq="YS"):
317
    """
318
    Maximum daily precipitation.
319
    
320
    Parameters:
321
    - pr: xr.DataArray, daily precipitation data
322
    - freq: str, resampling frequency
323
    
324
    Returns:
325
    xr.DataArray: Maximum daily precipitation
326
    """
327

328
def sdii(pr, thresh="1 mm/day", freq="YS"):
329
    """
330
    Simple daily intensity index (mean precipitation on wet days).
331
    
332
    Parameters:
333
    - pr: xr.DataArray, daily precipitation data
334
    - thresh: str or float, wet day threshold (default "1 mm/day")
335
    - freq: str, resampling frequency
336
    
337
    Returns:
338
    xr.DataArray: Simple daily intensity index
339
    """
340
```
341

342
#### Precipitation Frequency Indicators
343

344
Wet and dry day statistics for drought and flooding analysis.
345

346
```python { .api }
347
def wet_days(pr, thresh="1 mm/day", freq="YS"):
348
    """
349
    Number of wet days (precipitation above threshold).
350
    
351
    Parameters:
352
    - pr: xr.DataArray, daily precipitation data
353
    - thresh: str or float, wet day threshold (default "1 mm/day")
354
    - freq: str, resampling frequency
355
    
356
    Returns:
357
    xr.DataArray: Number of wet days
358
    """
359

360
def dry_days(pr, thresh="1 mm/day", freq="YS"):
361
    """
362
    Number of dry days (precipitation below threshold).
363
    
364
    Parameters:
365
    - pr: xr.DataArray, daily precipitation data
366
    - thresh: str or float, dry day threshold (default "1 mm/day")
367
    - freq: str, resampling frequency
368
    
369
    Returns:
370
    xr.DataArray: Number of dry days
371
    """
372

373
def r10mm(pr, thresh="10 mm/day", freq="YS"):
374
    """
375
    Number of days with precipitation >= 10mm.
376
    
377
    Parameters:
378
    - pr: xr.DataArray, daily precipitation data
379
    - thresh: str or float, precipitation threshold (default "10 mm/day")
380
    - freq: str, resampling frequency
381
    
382
    Returns:
383
    xr.DataArray: Number of heavy precipitation days
384
    """
385

386
def r20mm(pr, thresh="20 mm/day", freq="YS"):
387
    """
388
    Number of days with precipitation >= 20mm.
389
    
390
    Parameters:
391
    - pr: xr.DataArray, daily precipitation data  
392
    - thresh: str or float, precipitation threshold (default "20 mm/day")
393
    - freq: str, resampling frequency
394
    
395
    Returns:
396
    xr.DataArray: Number of very heavy precipitation days
397
    """
398
```
399

400
#### Consecutive Day Indicators
401

402
Drought and wet spell characterization for water resource management.
403

404
```python { .api }
405
def cdd(pr, thresh="1 mm/day", freq="YS"):
406
    """
407
    Maximum number of consecutive dry days.
408
    
409
    Parameters:
410
    - pr: xr.DataArray, daily precipitation data
411
    - thresh: str or float, dry day threshold (default "1 mm/day")
412
    - freq: str, resampling frequency
413
    
414
    Returns:
415
    xr.DataArray: Maximum consecutive dry days
416
    """
417

418
def cwd(pr, thresh="1 mm/day", freq="YS"):
419
    """
420
    Maximum number of consecutive wet days.
421
    
422
    Parameters:
423
    - pr: xr.DataArray, daily precipitation data
424
    - thresh: str or float, wet day threshold (default "1 mm/day")
425
    - freq: str, resampling frequency
426
    
427
    Returns:
428
    xr.DataArray: Maximum consecutive wet days
429
    """
430
```
431

432
### Wind Indicators
433

434
Surface wind speed analysis for renewable energy and extreme weather applications.
435

436
```python { .api }
437
def sfcwind_mean(sfcwind, freq="YS"):
438
    """
439
    Mean surface wind speed.
440
    
441
    Parameters:
442
    - sfcwind: xr.DataArray, daily surface wind speed
443
    - freq: str, resampling frequency
444
    
445
    Returns:
446
    xr.DataArray: Mean wind speed
447
    """
448

449
def sfcwind_max(sfcwind, freq="YS"):
450
    """
451
    Maximum surface wind speed.
452
    
453
    Parameters:
454
    - sfcwind: xr.DataArray, daily surface wind speed
455
    - freq: str, resampling frequency
456
    
457
    Returns:
458
    xr.DataArray: Maximum wind speed
459
    """
460

461
def windy_days(sfcwind, thresh="10 m/s", freq="YS"):
462
    """
463
    Number of windy days above wind speed threshold.
464
    
465
    Parameters:
466
    - sfcwind: xr.DataArray, daily surface wind speed
467
    - thresh: str or float, wind speed threshold (default "10 m/s")
468
    - freq: str, resampling frequency
469
    
470
    Returns:
471
    xr.DataArray: Number of windy days
472
    """
473
```
474

475
### Growing Season Indicators
476

477
Agricultural season timing and length for crop management applications.
478

479
```python { .api }
480
def growing_season_length(tas, thresh="5 degC", window=6, freq="YS"):
481
    """
482
    Length of growing season based on temperature threshold.
483
    
484
    Parameters:
485
    - tas: xr.DataArray, daily mean temperature
486
    - thresh: str or float, temperature threshold (default "5 degC")
487
    - window: int, minimum window length for season detection (default 6)
488
    - freq: str, resampling frequency
489
    
490
    Returns:
491
    xr.DataArray: Growing season length in days
492
    """
493

494
def growing_season_start(tas, thresh="5 degC", window=6, freq="YS"):
495
    """
496
    Start date of growing season.
497
    
498
    Parameters:
499
    - tas: xr.DataArray, daily mean temperature
500
    - thresh: str or float, temperature threshold (default "5 degC")
501
    - window: int, minimum window length (default 6)
502
    - freq: str, resampling frequency
503
    
504
    Returns:
505
    xr.DataArray: Growing season start day of year
506
    """
507

508
def growing_season_end(tas, thresh="5 degC", window=6, freq="YS"):
509
    """
510
    End date of growing season.
511
    
512
    Parameters:
513
    - tas: xr.DataArray, daily mean temperature
514
    - thresh: str or float, temperature threshold (default "5 degC")  
515
    - window: int, minimum window length (default 6)
516
    - freq: str, resampling frequency
517
    
518
    Returns:
519
    xr.DataArray: Growing season end day of year
520
    """
521
```
522

523
## Usage Examples
524

525
### Basic Temperature Analysis
526

527
```python
528
import xarray as xr
529
import xclim.atmos as xca
530

531
# Load temperature data
532
ds = xr.tutorial.open_dataset("air_temperature") 
533
tasmax = ds.air.rename("tasmax")
534
tasmin = tasmax - 5  # Create tasmin for example
535

536
# Compute temperature indicators
537
tmax_mean = xca.tx_mean(tasmax, freq="YS")
538
summer_days = xca.summer_days(tasmax, thresh="25 degC", freq="YS")
539
frost_days = xca.frost_days(tasmin, thresh="0 degC", freq="YS")
540
growing_dd = xca.growing_degree_days(tasmax, thresh="4.0 degC", freq="YS")
541
```
542

543
### Precipitation Analysis
544

545
```python
546
# Load precipitation data
547
pr = ds.precip.rename("pr")  # assuming precip exists
548

549
# Compute precipitation indicators  
550
total_precip = xca.prcptot(pr, freq="YS")
551
heavy_days = xca.r10mm(pr, freq="YS") 
552
dry_spell = xca.cdd(pr, thresh="1 mm/day", freq="YS")
553
wet_spell = xca.cwd(pr, thresh="1 mm/day", freq="YS")
554
intensity = xca.sdii(pr, freq="YS")
555
```
556

557
### Heat Wave Analysis
558

559
```python
560
# Detect heat waves
561
heat_waves = xca.hot_spell_frequency(
562
    tasmax, 
563
    thresh_tasmax="30 degC",
564
    window=3,  # 3+ consecutive days
565
    freq="YS"
566
)
567

568
# Maximum heat wave length
569
max_heat_wave = xca.hot_spell_max_length(
570
    tasmax,
571
    thresh_tasmax="30 degC", 
572
    window=3,
573
    freq="YS"
574
)
575
```