# Helper Methods

This module provides utility functions for data subsetting and spatial operations in gdptools.

## Overview

The helper methods module contains functions that support the core functionality of gdptools by providing:

- **Spatial Subsetting**: Functions to create subset dictionaries for xarray operations
- **Coordinate System Handling**: Utilities for managing different coordinate orientations
- **Data Validation**: Functions to verify input data structure and dimensions

## Key Functions

### Spatial Subsetting Functions

These functions create selection dictionaries for xarray operations:

- `build_subset()`: General-purpose subsetting with spatial and temporal dimensions
- `build_subset_tiff()`: TIFF-specific subsetting with band selection
- `build_subset_tiff_da()`: DataArray-specific TIFF subsetting

### Validation Functions

- `check_gridded_data_for_dimensions()`: Validates input data dimensions

## Usage Examples

### Basic Spatial Subsetting

```python
import numpy as np
from gdptools.helpers import build_subset

# Define spatial bounds
bounds = np.array([-180, -90, 180, 90])  # [minx, miny, maxx, maxy]

# Create subset dictionary
subset_dict = build_subset(
    bounds=bounds,
    xname='longitude',
    yname='latitude',
    tname='time',
    toptobottom=False,
    date_min='2020-01-01',
    date_max='2020-12-31'
)

# Apply to dataset
data_subset = dataset.sel(subset_dict)
```

### TIFF Data Subsetting

```python
from gdptools.helpers import build_subset_tiff

# Subset TIFF data by space and band
subset_dict = build_subset_tiff(
    bounds=bounds,
    xname='x',
    yname='y',
    toptobottom=True,
    bname='band',
    band=1
)

raster_subset = raster_data.sel(subset_dict)
```

### Data Validation

```python
from gdptools.helpers import check_gridded_data_for_dimensions

# Validate dataset dimensions
try:
    check_gridded_data_for_dimensions(dataset, ['temperature', 'precipitation'])
    print("Data validation passed")
except KeyError as e:
    print(f"Data validation failed: {e}")
```

## Coordinate System Orientation

The `toptobottom` parameter is crucial for handling different coordinate systems:

- **True**: Y-coordinates increase from north to south (typical for image data)
- **False**: Y-coordinates increase from south to north (typical for geographic data)

## Best Practices

1. **Always validate bounds**: Ensure bounds array is in correct format [minx, miny, maxx, maxy]
2. **Check coordinate orientation**: Verify the `toptobottom` parameter matches your data
3. **Validate data dimensions**: Use validation functions before processing
4. **Handle temporal data carefully**: Ensure date strings are in ISO format

## API Reference

```{eval-rst}
.. automodule:: gdptools.helpers
    :members:
    :noindex:
```