# xarray Extensions

## Jua xarray Extensions

The Jua Python SDK extends the popular [xarray](https://docs.xarray.dev/) library with weather-specific functionality to make working with meteorological data more intuitive and convenient.

### Overview

Jua's xarray extensions provide:

1. Weather-specific data selection capabilities
2. Unit conversion utilities
3. Time handling enhancements
4. Point-based geographic selection
5. Enhanced type hints for better IDE support

These extensions are automatically applied when you use the SDK - no extra steps required.

### Extended Functionality at a Glance

The SDK adds several powerful extensions to xarray:

* **Enhanced `sel()` method** with additional parameters:
  * `prediction_timedelta` - Select by forecast lead time
  * `points` - Select by geographic points
  * Support for proper North-to-South latitude slicing
* **New accessor methods** via `.jua` accessor or direct methods:
  * `.to_celcius()` - Convert temperature from Kelvin to Celsius
  * `.to_absolute_time()` - Convert from lead times to absolute dates
  * `.select_point()` - Select data at specific geographic locations
* **Variable access** with Jua's `Variables` enum for type safety

### Key Features

#### Extended Data Selection

```python
# Select data using prediction lead times
forecast_data.sel(prediction_timedelta=24)  # 24-hour forecast
forecast_data.sel(prediction_timedelta=slice(24, 72))  # 1-3 day forecast
forecast_data.sel(prediction_timedelta=slice(0, 120, 6))  # Every 6 hours up to 5 days

# Select geographic regions with natural ordering
# Note: latitude goes from North to South (higher to lower values)
europe_data = forecast_data.sel(
    latitude=slice(72, 36),    # North to South
    longitude=slice(-15, 35)   # West to East
)
```

#### Point-Based Selection

```python
from jua.types.geo import LatLon

# Select data for specific locations
cities = [
    LatLon(lat=51.5074, lon=-0.1278, name="London"),
    LatLon(lat=40.7128, lon=-74.0060, name="New York")
]

# Using direct selection
city_data = forecast_data.sel(points=cities)

# Or using the accessor
city_data = forecast_data.jua.select_point(cities)

# Access data for a specific city
london_data = city_data.sel(points="London")
```

#### Unit Conversions

```python
# Get temperature data
temperature = forecast_data["air_temperature_at_height_level_2m"]

# Convert from Kelvin to Celsius
celsius = temperature.to_celcius()
# or
celsius = temperature.jua.to_celcius()
```

#### Time Handling

```python
# Convert from prediction lead times to absolute times
absolute_times = forecast_data.to_absolute_time()
# or
absolute_times = forecast_data.jua.to_absolute_time()
```

#### Type-Safe Variable Access

```python
from jua.weather import Variables

# Access variables using enum members (with autocompletion and type checking)
temperature = forecast_data[Variables.AIR_TEMPERATURE_AT_HEIGHT_LEVEL_2M]
wind_speed = forecast_data[Variables.WIND_SPEED_AT_HEIGHT_LEVEL_10M]
```

Best Practices

1. **Use Variables enum** for type-safe variable access
2. **Use xarray's powerful data analysis capabilities** - these extensions preserve all standard xarray functionality