0
# Unit Conversions
1

2
The Meteostat units module provides comprehensive conversion functions for meteorological parameters, enabling easy transformation between different unit systems (metric, imperial, scientific). It includes both individual conversion functions and pre-configured unit dictionaries.
3

4
## Capabilities
5

6
### Temperature Conversions
7

8
Convert temperature values between Celsius, Fahrenheit, and Kelvin scales.
9

10
```python { .api }
11
def fahrenheit(value):
12
    """
13
    Convert Celsius to Fahrenheit.
14
    
15
    Parameters:
16
    - value: float, temperature in Celsius
17
    
18
    Returns:
19
    float, temperature in Fahrenheit rounded to 1 decimal place
20
    
21
    Formula: °F = (°C × 9/5) + 32
22
    """
23

24
def kelvin(value):
25
    """
26
    Convert Celsius to Kelvin.
27
    
28
    Parameters:
29
    - value: float, temperature in Celsius
30
    
31
    Returns:
32
    float, temperature in Kelvin rounded to 1 decimal place
33
    
34
    Formula: K = °C + 273.15
35
    """
36
```
37

38
### Precipitation Conversions
39

40
Convert precipitation measurements between metric and imperial units.
41

42
```python { .api }
43
def inches(value):
44
    """
45
    Convert millimeters to inches.
46
    
47
    Parameters:
48
    - value: float, precipitation in millimeters
49
    
50
    Returns:
51
    float, precipitation in inches rounded to 3 decimal places
52
    
53
    Formula: inches = mm / 25.4
54
    """
55
```
56

57
### Distance Conversions
58

59
Convert distance and elevation measurements to imperial units.
60

61
```python { .api }
62
def feet(value):
63
    """
64
    Convert meters to feet.
65
    
66
    Parameters:
67
    - value: float, distance/elevation in meters
68
    
69
    Returns:
70
    float, distance/elevation in feet rounded to 1 decimal place
71
    
72
    Formula: feet = meters / 0.3048
73
    """
74
```
75

76
### Wind Speed Conversions
77

78
Convert wind speed between different velocity units.
79

80
```python { .api }
81
def ms(value):
82
    """
83
    Convert kilometers per hour to meters per second.
84
    
85
    Parameters:
86
    - value: float, wind speed in km/h
87
    
88
    Returns:
89
    float, wind speed in m/s rounded to 1 decimal place
90
    
91
    Formula: m/s = km/h / 3.6
92
    """
93

94
def mph(value):
95
    """
96
    Convert kilometers per hour to miles per hour.
97
    
98
    Parameters:
99
    - value: float, wind speed in km/h
100
    
101
    Returns:
102
    float, wind speed in mph rounded to 1 decimal place
103
    
104
    Formula: mph = km/h × 0.6214
105
    """
106
```
107

108
### Categorical Conversions
109

110
Convert numerical codes to descriptive text representations.
111

112
```python { .api }
113
def direction(value):
114
    """
115
    Convert wind direction in degrees to cardinal direction string.
116
    
117
    Parameters:
118
    - value: float, wind direction in degrees (0-360)
119
    
120
    Returns:
121
    str, cardinal direction (N, NE, E, SE, S, SW, W, NW)
122
    """
123

124
def condition(value):
125
    """
126
    Convert Meteostat weather condition code to descriptive string.
127
    
128
    Parameters:
129
    - value: float, weather condition code (1-27)
130
    
131
    Returns:
132
    str, weather condition description
133
    
134
    Condition codes:
135
    1-4: Clear to overcast
136
    5-6: Fog conditions
137
    7-13: Rain and freezing rain
138
    14-16: Snow conditions  
139
    17-22: Shower conditions
140
    23-27: Thunderstorm and severe weather
141
    """
142
```
143

144
## Unit System Dictionaries
145

146
Pre-configured dictionaries for converting entire datasets to specific unit systems.
147

148
```python { .api }
149
# Imperial unit system
150
imperial: dict = {
151
    "temp": fahrenheit,      # °C to °F
152
    "tavg": fahrenheit,      # Average temperature
153
    "tmin": fahrenheit,      # Minimum temperature
154
    "tmax": fahrenheit,      # Maximum temperature  
155
    "dwpt": fahrenheit,      # Dew point temperature
156
    "prcp": inches,          # mm to inches
157
    "snow": inches,          # Snow depth mm to inches
158
    "wspd": mph,             # km/h to mph
159
    "wpgt": mph,             # Wind gust km/h to mph
160
    "distance": feet         # m to feet (for station metadata)
161
}
162

163
# Scientific unit system  
164
scientific: dict = {
165
    "temp": kelvin,          # °C to K
166
    "tavg": kelvin,          # Average temperature
167
    "tmin": kelvin,          # Minimum temperature
168
    "tmax": kelvin,          # Maximum temperature
169
    "dwpt": kelvin,          # Dew point temperature
170
    "wspd": ms,              # km/h to m/s
171
    "wpgt": ms               # Wind gust km/h to m/s
172
}
173
```
174

175
## Usage Examples
176

177
### Individual Function Usage
178

179
```python
180
from meteostat import units
181

182
# Temperature conversions
183
temp_c = 25.0
184
temp_f = units.fahrenheit(temp_c)  # 77.0°F
185
temp_k = units.kelvin(temp_c)      # 298.2 K
186

187
print(f"{temp_c}°C = {temp_f}°F = {temp_k} K")
188

189
# Precipitation conversion
190
precip_mm = 12.7
191
precip_in = units.inches(precip_mm)  # 0.500 inches
192
print(f"{precip_mm} mm = {precip_in} inches")
193

194
# Wind speed conversions
195
wind_kmh = 36.0
196
wind_ms = units.ms(wind_kmh)   # 10.0 m/s  
197
wind_mph = units.mph(wind_kmh) # 22.4 mph
198
print(f"{wind_kmh} km/h = {wind_ms} m/s = {wind_mph} mph")
199
```
200

201
### Weather Code Conversions
202

203
```python
204
from meteostat import units
205

206
# Wind direction conversion
207
wind_degrees = [0, 45, 90, 135, 180, 225, 270, 315, 360]
208
directions = [units.direction(deg) for deg in wind_degrees]
209
print("Wind directions:", dict(zip(wind_degrees, directions)))
210

211
# Weather condition conversion
212
condition_codes = [1, 5, 8, 15, 18, 25]
213
conditions = [units.condition(code) for code in condition_codes]
214
print("Weather conditions:", dict(zip(condition_codes, conditions)))
215
```
216

217
### Dataset Unit Conversion
218

219
```python
220
from datetime import datetime
221
from meteostat import Point, Daily, units
222

223
# Get daily weather data
224
location = Point(40.7128, -74.0060)  # New York
225
start = datetime(2020, 1, 1)
226
end = datetime(2020, 3, 31)
227

228
data = Daily(location, start, end)
229

230
# Convert to Imperial units using dictionary
231
imperial_data = data.convert(units.imperial)
232
imperial_df = imperial_data.fetch()
233

234
print("Weather data in Imperial units:")
235
print(imperial_df[['tavg', 'tmin', 'tmax', 'prcp', 'wspd']].head())
236

237
# Convert to Scientific units
238
scientific_data = data.convert(units.scientific)  
239
scientific_df = scientific_data.fetch()
240

241
print("Weather data in Scientific units:")
242
print(scientific_df[['tavg', 'tmin', 'tmax', 'wspd']].head())
243
```
244

245
### Custom Unit Combinations
246

247
```python
248
from meteostat import Point, Hourly, units
249

250
# Create custom unit conversion dictionary
251
custom_units = {
252
    'temp': units.fahrenheit,    # Temperature in Fahrenheit
253
    'wspd': units.ms,           # Wind speed in m/s  
254
    'prcp': units.inches,       # Precipitation in inches
255
    'pres': lambda x: x * 0.02953,  # hPa to inHg (custom function)
256
}
257

258
# Apply custom conversions
259
location = Point(51.5074, -0.1278)  # London
260
data = Hourly(location, datetime(2020, 6, 1), datetime(2020, 6, 7))
261

262
custom_data = data.convert(custom_units)
263
custom_df = custom_data.fetch()
264

265
print("Custom unit combination:")
266
print(custom_df[['temp', 'wspd', 'prcp', 'pres']].head())
267
```
268

269
### Categorical Data Processing
270

271
```python
272
from datetime import datetime
273
from meteostat import Point, Hourly, units
274
import pandas as pd
275

276
# Get hourly data with weather conditions
277
location = Point(52.5200, 13.4050)  # Berlin
278
start = datetime(2020, 7, 1)
279
end = datetime(2020, 7, 31)
280

281
data = Hourly(location, start, end)
282
hourly_df = data.fetch()
283

284
# Convert wind direction to cardinal directions
285
hourly_df['wind_direction'] = hourly_df['wdir'].apply(units.direction)
286

287
# Convert condition codes to descriptions
288
hourly_df['weather_condition'] = hourly_df['coco'].apply(units.condition)
289

290
# Analyze weather patterns
291
weather_summary = hourly_df['weather_condition'].value_counts()
292
print("July 2020 weather conditions in Berlin:")
293
print(weather_summary)
294

295
wind_summary = hourly_df['wind_direction'].value_counts()
296
print("\nPrevailing wind directions:")
297
print(wind_summary)
298
```
299

300
### Station Metadata Conversion
301

302
```python
303
from meteostat import Stations, units
304

305
# Get nearby stations
306
stations = Stations().nearby(37.7749, -122.4194, 50000)  # San Francisco
307

308
# Convert station metadata to Imperial units
309
imperial_stations = stations.convert({
310
    'elevation': units.feet,
311
    'distance': units.feet
312
})
313

314
station_data = imperial_stations.fetch()
315
print("Station elevations and distances in feet:")
316
print(station_data[['name', 'elevation', 'distance']].head())
317
```
318

319
## Conversion Accuracy
320

321
All conversion functions maintain appropriate precision:
322

323
```python { .api }
324
# Precision specifications
325
temperature_precision = 1    # 1 decimal place (0.1°C/°F/K)
326
precipitation_precision = 3  # 3 decimal places (0.001 inches)
327
speed_precision = 1         # 1 decimal place (0.1 mph/m/s)
328
distance_precision = 1      # 1 decimal place (0.1 feet)
329
```
330

331
## Weather Condition Code Reference
332

333
Complete mapping of weather condition codes to descriptions:
334

335
```python { .api }
336
condition_codes = {
337
    1: "Clear",           2: "Fair",            3: "Cloudy",
338
    4: "Overcast",        5: "Fog",             6: "Freezing Fog", 
339
    7: "Light Rain",      8: "Rain",            9: "Heavy Rain",
340
    10: "Freezing Rain",  11: "Heavy Freezing Rain", 12: "Sleet",
341
    13: "Heavy Sleet",    14: "Light Snowfall", 15: "Snowfall",
342
    16: "Heavy Snowfall", 17: "Rain Shower",    18: "Heavy Rain Shower",
343
    19: "Sleet Shower",   20: "Heavy Sleet Shower", 21: "Snow Shower",
344
    22: "Heavy Snow Shower", 23: "Lightning",   24: "Hail",
345
    25: "Thunderstorm",   26: "Heavy Thunderstorm", 27: "Storm"
346
}
347
```
348

349
## Integration with Data Processing
350

351
Unit conversions integrate seamlessly with time series processing:
352

353
```python
354
# Chain operations: aggregate then convert
355
data = Hourly(location, start, end)
356
daily_imperial = data.aggregate('D').convert(units.imperial)
357

358
# Or convert then aggregate
359
imperial_daily = data.convert(units.imperial).aggregate('D')
360

361
# Both approaches yield equivalent results
362
```