varunayan.spatial module

Spatial aggregation utilities for climate data.

This module provides functions for aggregating gridded climate data to administrative boundaries or other polygons.

varunayan.spatial.aggregate_to_polygons(data: DataFrame, polygons: GeoDataFrame, value_cols: str | List[str], method: str = 'point_in_polygon', lat_col: str = 'latitude', lon_col: str = 'longitude', polygon_id_col: str | None = None, agg_func: str = 'mean') → GeoDataFrame

Aggregate gridded data to polygon boundaries.

Parameters:

• data – DataFrame with gridded climate data (must have lat/lon columns)

• polygons – GeoDataFrame with polygon geometries

• value_cols – Column name(s) containing values to aggregate

• method – Aggregation method: - ‘point_in_polygon’: Average all grid points within each polygon - ‘nearest_centroid’: Use value from grid point nearest to polygon centroid

• lat_col – Name of latitude column in data

• lon_col – Name of longitude column in data

• polygon_id_col – Column in polygons to use as identifier (default: index)

• agg_func – Aggregation function (‘mean’, ‘sum’, ‘max’, ‘min’, ‘median’)

Returns:

GeoDataFrame with aggregated values for each polygon

varunayan.spatial.check_grid_coverage(grid_data: DataFrame, polygons: GeoDataFrame, lat_col: str = 'latitude', lon_col: str = 'longitude', polygon_id_col: str | None = None) → Dict[str, Any]

Check how well the grid data covers the polygon boundaries.

Parameters:

• grid_data – DataFrame with gridded climate data

• polygons – GeoDataFrame with polygon geometries

• lat_col – Name of latitude column

• lon_col – Name of longitude column

• polygon_id_col – Column to use as polygon identifier

Returns:

• total_polygons: Number of polygons

• covered_polygons: Number of polygons with at least one grid point

• empty_polygons: Number of polygons with no grid points

• coverage_percent: Percentage of polygons covered

• points_per_polygon: DataFrame with point counts per polygon

• uncovered_polygon_ids: List of polygon IDs with no coverage

Return type:

Dictionary with coverage statistics

varunayan.spatial.visualize_grid_overlap(grid_data: DataFrame, polygons: GeoDataFrame, lat_col: str = 'latitude', lon_col: str = 'longitude', output_file: str | None = None, figsize: Tuple[int, int] = (12, 10), title: str = 'Grid Points and Polygon Boundaries') → None

Visualize the overlap between grid points and polygon boundaries.

Parameters:

• grid_data – DataFrame with gridded climate data

• polygons – GeoDataFrame with polygon geometries

• lat_col – Name of latitude column

• lon_col – Name of longitude column

• output_file – Path to save the figure (optional)

• figsize – Figure size as (width, height)

• title – Plot title

varunayan.spatial.compare_grids(grids: Dict[str, DataFrame], polygons: GeoDataFrame | None = None, lat_col: str = 'latitude', lon_col: str = 'longitude', output_file: str | None = None, figsize: Tuple[int, int] = (12, 10), title: str = 'Grid Comparison') → None

Compare multiple grids visually (e.g., ERA5 vs IMD).

Parameters:

• grids – Dictionary mapping grid names to DataFrames

• polygons – Optional GeoDataFrame with polygon boundaries to overlay

• lat_col – Name of latitude column

• lon_col – Name of longitude column

• output_file – Path to save the figure (optional)

• figsize – Figure size as (width, height)

• title – Plot title

varunayan.spatial.get_polygon_timeseries(data: DataFrame, polygons: GeoDataFrame, value_col: str, time_col: str = 'date', lat_col: str = 'latitude', lon_col: str = 'longitude', polygon_id_col: str | None = None, agg_func: str = 'mean') → DataFrame

Get time series of aggregated values for each polygon.

Parameters:

• data – DataFrame with gridded climate data including time column

• polygons – GeoDataFrame with polygon geometries

• value_col – Column containing values to aggregate

• time_col – Column containing time/date values

• lat_col – Name of latitude column

• lon_col – Name of longitude column

• polygon_id_col – Column to use as polygon identifier

• agg_func – Aggregation function

Returns:

polygon_id, time, aggregated_value

Return type:

DataFrame with columns