0
# XClim
1

2
A comprehensive Python library for climate indices computation based on Xarray. XClim provides extensive climate analysis capabilities including 200+ climate indicators, statistical downscaling, bias adjustment, ensemble analysis, and spatial analog methods for climate services applications.
3

4
## Package Information
5

6
- **Package Name**: xclim
7
- **Language**: Python  
8
- **Installation**: `pip install xclim`
9
- **Documentation**: https://xclim.readthedocs.io/
10

11
## Core Imports
12

13
```python
14
import xclim
15
```
16

17
Common for working with climate indicators:
18

19
```python
20
from xclim import atmos, land, seaIce, generic, convert
21
import xclim.indices as xci
22
```
23

24
For utilities and configuration:
25

26
```python
27
from xclim import set_options, units
28
from xclim.core import calendar, missing
29
```
30

31
## Basic Usage
32

33
```python
34
import xarray as xr
35
import xclim.atmos as xca
36
import xclim.indices as xci
37

38
# Load temperature data (example with sample dataset)
39
ds = xr.tutorial.open_dataset("air_temperature")
40
tasmax = ds.air.rename("tasmax")
41

42
# Compute growing degree days using high-level indicator
43
gdd = xca.growing_degree_days(tasmax, thresh="10 degC", freq="YS")
44

45
# Or use low-level computation function directly  
46
gdd_manual = xci.growing_degree_days(tasmax, thresh=10, freq="YS")
47

48
# Compute heat wave frequency
49
heat_waves = xca.heat_wave_frequency(
50
    tasmax=tasmax,
51
    thresh_tasmax="30 degC", 
52
    window=3,
53
    freq="YS"
54
)
55

56
# Work with precipitation data
57
pr = ds.precip.rename("pr") if "precip" in ds else None
58
if pr is not None:
59
    # Total precipitation
60
    precip_total = xca.prcptot(pr, freq="YS")
61
    
62
    # Consecutive dry days
63
    dry_days = xca.cdd(pr, thresh="1 mm/day", freq="YS")
64
```
65

66
## Architecture
67

68
XClim follows a two-layer architecture:
69

70
- **Indicators Layer**: High-level `Indicator` classes that provide automatic unit conversion, missing data validation, metadata handling, and CF-compliant output
71
- **Indices Layer**: Low-level computation functions that perform the mathematical operations on xarray DataArrays
72
- **Core Utilities**: Units handling, calendar operations, missing data detection, and configuration management
73
- **Analysis Tools**: Ensemble processing, spatial analogs, and statistical downscaling capabilities
74

75
This design enables both simple usage through indicators and advanced customization through direct access to computation functions and utilities.
76

77
## Capabilities
78

79
### Atmospheric Indicators
80

81
Comprehensive atmospheric climate indicators including temperature, precipitation, wind, and humidity analysis with over 80 pre-defined indicators for climate services applications.
82

83
```python { .api }
84
# Temperature indicators
85
def tg_mean(tas, freq="YS"): ...
86
def tx_max(tasmax, freq="YS"): ...  
87
def tn_min(tasmin, freq="YS"): ...
88
def growing_degree_days(tas, thresh="10 degC", freq="YS"): ...
89
def heating_degree_days(tas, thresh="17 degC", freq="YS"): ...
90

91
# Precipitation indicators  
92
def prcptot(pr, freq="YS"): ...
93
def sdii(pr, thresh="1 mm/day", freq="YS"): ...
94
def cdd(pr, thresh="1 mm/day", freq="YS"): ...
95
def r10mm(pr, thresh="10 mm/day", freq="YS"): ...
96
```
97

98
[Atmospheric Indicators](./atmospheric-indicators.md)
99

100
### Land-based Indicators
101

102
Land surface climate indicators focusing on snow, streamflow, and terrestrial processes for hydrological and agricultural applications.
103

104
```python { .api }
105
# Snow indicators
106
def snow_depth(snd, freq="YS"): ...
107
def snd_max(snd, freq="YS"): ...
108
def continuous_snow_season_start(snd, thresh="2 cm", freq="YS"): ...
109

110
# Streamflow indicators
111
def base_flow_index(q, freq="YS"): ...
112
def rb_flashiness_index(q, freq="YS"): ...
113
```
114

115
[Land Indicators](./land-indicators.md)
116

117
### Sea Ice Indicators
118

119
Sea ice concentration and extent indicators for polar climate analysis and marine applications.
120

121
```python { .api }
122
def sea_ice_area(sic, freq="YS"): ...
123
def sea_ice_extent(sic, freq="YS"): ...
124
def sic_days_above(sic, thresh="15%", freq="YS"): ...
125
```
126

127
[Sea Ice Indicators](./sea-ice-indicators.md)
128

129
### Statistical Indicators
130

131
Generic statistical analysis tools applicable to any climate variable, including distribution fitting, frequency analysis, and spell detection.
132

133
```python { .api }
134
def stats(da, op="mean", freq="YS"): ...
135
def fit(da, dist="norm", freq="YS"): ...
136
def spell_length(da, threshold, op=operator.ge, freq="YS"): ...
137
def threshold_count(da, threshold, op=operator.ge, freq="YS"): ...
138
```
139

140
[Statistical Indicators](./statistical-indicators.md)
141

142
### Unit Conversion Indicators
143

144
Specialized indicators for converting between climate-related units and computing derived indices like heat index and wind chill.
145

146
```python { .api }
147
def heat_index(tas, hurs, freq="YS"): ...
148
def humidex(tas, hurs, freq="YS"): ...
149
def wind_chill_index(tas, sfcwind, freq="YS"): ...
150
```
151

152
[Conversion Indicators](./conversion-indicators.md)
153

154
### Core Computation Functions
155

156
Low-level mathematical functions for climate indices calculation, providing the computational engine underlying all indicators.
157

158
```python { .api }
159
# Temperature computations
160
def tg_mean(tas, freq="YS"): ...
161
def daily_temperature_range(tasmax, tasmin, freq="YS"): ...
162
def growing_degree_days(tas, thresh=10.0, freq="YS"): ...
163

164
# Precipitation computations  
165
def precip_accumulation(pr, freq="YS"): ...
166
def wetdays(pr, thresh=1.0, freq="YS"): ...
167
def maximum_consecutive_wet_days(pr, thresh=1.0, freq="YS"): ...
168
```
169

170
[Core Computation Functions](./core-computation.md)
171

172
### Fire Weather Indices
173

174
Complete Canadian Forest Fire Weather Index System implementation for wildfire risk assessment and forest management applications.
175

176
```python { .api }
177
def drought_code(pr, tas, lat, **kwargs): ...
178
def fine_fuel_moisture_code(pr, tas, hurs, sfcwind, **kwargs): ...
179
def fire_weather_index(pr, tas, hurs, sfcwind, lat, **kwargs): ...
180
```
181

182
[Fire Weather Indices](./fire-weather.md)
183

184
### Ensemble Analysis
185

186
Multi-model climate ensemble processing and analysis tools for climate projection assessment and uncertainty quantification.
187

188
```python { .api }
189
def create_ensemble(datasets, **kwargs): ...
190
def ensemble_mean_std_max_min(ens, **kwargs): ...
191
def ensemble_percentiles(ens, values=[10, 50, 90], **kwargs): ...
192
def robustness_fractions(ens, test="threshold", **kwargs): ...
193
```
194

195
[Ensemble Analysis](./ensemble-analysis.md)
196

197
### Spatial Analogs
198

199
Spatial analog analysis for identifying regions with similar climate characteristics, useful for climate adaptation and impact assessment.
200

201
```python { .api }
202
def spatial_analogs(reference, candidates, method="kldiv", **kwargs): ...
203
```
204

205
[Spatial Analogs](./spatial-analogs.md)
206

207
### Statistical Downscaling and Bias Adjustment
208

209
Comprehensive statistical downscaling and bias correction methods for climate model post-processing.
210

211
```python { .api }
212
# Adjustment methods
213
def EmpiricalQuantileMapping(**kwargs): ...
214
def DetrendedQuantileMapping(**kwargs): ...
215
def PrincipalComponents(**kwargs): ...
216

217
# Measures and utilities
218
def bias(obs, sim, **kwargs): ...
219
def correlation(obs, sim, **kwargs): ...
220
```
221

222
[Statistical Downscaling](./statistical-downscaling.md)
223

224
### Utilities and Configuration
225

226
Core utilities for units handling, calendar operations, missing data management, and global configuration.
227

228
```python { .api }
229
# Units operations
230
def convert_units_to(da, target, **kwargs): ...
231
def check_units(da, expected): ...
232

233
# Calendar operations  
234
def convert_calendar(da, target_calendar, **kwargs): ...
235
def get_calendar(da): ...
236

237
# Configuration
238
def set_options(**kwargs): ...
239
```
240

241
[Utilities](./utilities.md)
242

243
## Types
244

245
```python { .api }
246
# Core types
247
from typing import Union, Optional, Sequence
248
import xarray as xr
249
import pandas as pd
250

251
DataArray = xr.DataArray
252
Dataset = xr.Dataset
253
Quantified = Union[str, int, float]  # Value with units
254
FreqStr = str  # Frequency string like "YS", "MS", "D"
255
ThresholdType = Union[str, int, float]  # Threshold with optional units
256

257
# Indicator classes
258
class Indicator:
259
    def __call__(self, *args, **kwargs) -> DataArray: ...
260
    
261
class Daily(Indicator): ...
262
class Monthly(Indicator): ...
263
class Percentile(Indicator): ...
264

265
# Missing data validators
266
class MissingBase: ...
267
class AtLeastNValid(MissingBase): ...
268
class SkipMissing(MissingBase): ...
269
```