varunayan package¶

Subpackages¶

varunayan.download package
- Submodules
  - varunayan.download.era5_downloader module
- Module contents
varunayan.processing package
- Submodules
- Module contents
varunayan.search_and_desc package
- Submodules
- Module contents
varunayan.util package
- Submodules
  - varunayan.util.geojson_utils module
  - varunayan.util.logging_utils module
- Module contents

Submodules¶

Module contents¶

varunayan.era5ify_geojson(request_id: str, variables: List[str], start_date: str, end_date: str, json_file: str, dist_features: List[str] | None = None, dataset_type: str = 'single', pressure_levels: List[str] | None = None, frequency: str = 'hourly', resolution: float = 0.25, verbosity: int = 0, save_raw: bool = True) → DataFrame[source]¶

Public function for querying data for a GeoJSON.

Parameters:

request_id (str) – Unique identifier for the request.
variables (List[str]) – List of variables to download.
start_date (str) – Start date of the data in ‘YYYY-M-D’ or ‘YYYY-MM-DD’ format.
end_date (str) – End date of the data in ‘YYYY-M-D’ or ‘YYYY-MM-DD’ format.
json_file (str) – Path to the GeoJSON file.
dist_features (List[str] | None, optional) – List of feature properties to distinguish different areas in the GeoJSON. Defaults to None.
dataset_type (str, optional) – Type of dataset. Either ‘single’ (single level) or ‘pressure’ (pressure level). Defaults to ‘single’.
pressure_levels (List[str] | None, optional) – List of pressure levels to download (e.g., [“1000”, “925”, “850”]). Defaults to None.
frequency (str, optional) – Frequency of the data (‘hourly’, ‘daily’, ‘weekly’, ‘monthly’, ‘yearly’). Defaults to ‘hourly’.
resolution (float, optional) – Spatial resolution in degrees (0.25, 0.1, 0.5, etc.). Defaults to 0.25, minimum is 0.1.
verbosity (int, optional) – Verbosity level (0 for no output, 1 for info output, 2 for debug/complete output). Defaults to 0.
save_raw (bool, optional) – Whether to save the raw data. Defaults to True.

Returns:

A DataFrame containing the processed data for the region described by GeoJSON.

Return type:

DataFrame

varunayan.era5ify_bbox(request_id: str, variables: List[str], start_date: str, end_date: str, north: float, south: float, east: float, west: float, dataset_type: str = 'single', pressure_levels: List[str] | None = None, frequency: str = 'hourly', resolution: float = 0.25, verbosity: int = 0, save_raw: bool = True) → DataFrame[source]¶

Public function for querying data for a defined bounding box (north, south, east, west bounds).

Parameters:

request_id (str) – Unique identifier for the request.
variables (List[str]) – List of variables to download.
start_date (str) – Start date of the data in ‘YYYY-M-D’ or ‘YYYY-MM-DD’ format.
end_date (str) – End date of the data in ‘YYYY-M-D’ or ‘YYYY-MM-DD’ format.
north (float) – Northern bound of the bounding box.
south (float) – Southern bound of the bounding box.
east (float) – Eastern bound of the bounding box.
west (float) – Western bound of the bounding box.
dataset_type (str, optional) – Type of dataset. Either ‘single’ (single level) or ‘pressure’ (pressure level). Defaults to ‘single’.
pressure_levels (List[str] | None, optional) – List of pressure levels to download (e.g., [“1000”, “925”, “850”]). Defaults to None.
frequency (str, optional) – Frequency of the data (‘hourly’, ‘daily’, ‘weekly’, ‘monthly’, ‘yearly’). Defaults to ‘hourly’.
resolution (float, optional) – Spatial resolution in degrees (0.25, 0.1, 0.5, etc.). Defaults to 0.25, minimum is 0.1.
verbosity (int, optional) – Verbosity level (0 for no output, 1 for info output, 2 for debug/complete output). Defaults to 0.
save_raw (bool, optional) – Whether to save the raw data. Defaults to True.

Returns:

A DataFrame containing the processed data for the specified bbox.

Return type:

DataFrame

varunayan.era5ify_point(request_id: str, variables: List[str], start_date: str, end_date: str, latitude: float, longitude: float, dataset_type: str = 'single', pressure_levels: List[str] | None = None, frequency: str = 'hourly', verbosity: int = 0, save_raw: bool = True) → DataFrame[source]¶

Public function for querying data for a single geographical point (latitude, longitude).

Parameters:

request_id (str) – Unique identifier for the request.
variables (List[str]) – List of variables to download.
start_date (str) – Start date of the data in ‘YYYY-M-D’ or ‘YYYY-MM-DD’ format.
end_date (str) – End date of the data in ‘YYYY-M-D’ or ‘YYYY-MM-DD’ format.
latitude (float) – Latitude of the point of interest.
longitude (float) – Longitude of the point of interest.
dataset_type (str, optional) – Type of dataset. Either ‘single’ (single level) or ‘pressure’ (pressure level). Defaults to ‘single’.
pressure_levels (List[str] | None, optional) – List of pressure levels to download (e.g., [“1000”, “925”, “850”]). Defaults to None.
frequency (str, optional) – Frequency of the data (‘hourly’, ‘daily’, ‘weekly’, ‘monthly’, ‘yearly’). Defaults to ‘hourly’.
verbosity (int, optional) – Verbosity level (0 for no output, 1 for info output, 2 for debug/complete output). Defaults to 0.
save_raw (bool, optional) – Whether to save the raw data. Defaults to True.

Returns:

A DataFrame containing the processed data for the specified point.

Return type:

DataFrame

varunayan.describe_variables(variable_names: List[str], dataset_type: str) → Dict[str, str][source]¶

Get descriptions for specific variables

Parameters:

variable_names (list) – List of variable names to describe
dataset_type (str) – Dataset type to search (“single”, “pressure”, “all”, or any other registered dataset)

varunayan.search_variable(pattern: str | None, dataset_type: str = 'all') → None[source]¶

Search for variables in the dataset by pattern

Parameters:

pattern (str or None) – The string pattern to search for in variable names. If None, prints all variables.
dataset_type (str) – Dataset type to search (“single”, “pressure”, “all”, or any other registered dataset)

varunayan.list_available_variables(dataset_type: str = 'single') → List[str][source]¶

List all available variable names for a dataset type.

Parameters:: dataset_type – Dataset type (“single”, “pressure”, or “all”)
Returns:: List of variable names

varunayan.get_available_pressure_levels() → List[str][source]¶

Get list of available pressure levels for ERA5 pressure level data.

Returns:: List of pressure level strings (in hPa)

varunayan.get_variable_info(variable_name: str, dataset_type: str = 'all') → Dict[str, Any] | None[source]¶

Get detailed information about a specific variable.

Parameters:

variable_name – Name of the variable
dataset_type – Dataset type to search

Returns:

Dictionary with variable info or None if not found

varunayan.get_variable_units(variable_name: str, dataset_type: str = 'all') → str | None[source]¶

Get the units for a specific variable.

Parameters:

variable_name – Name of the variable
dataset_type – Dataset type to search

Returns:

Unit string or None if not found

varunayan.get_variable_long_name(variable_name: str, dataset_type: str = 'all') → str | None[source]¶

Get the long/descriptive name for a variable.

Parameters:

variable_name – Name of the variable
dataset_type – Dataset type to search

Returns:

Description string or None if not found

varunayan.list_variable_categories(dataset_type: str = 'single') → List[str][source]¶

List all variable categories for a dataset type.

Parameters:: dataset_type – Dataset type (“single” or “pressure”)
Returns:: List of category names

Calculate relative humidity from temperature and dewpoint using Magnus-Tetens formula.

Parameters:

temp_c – Air temperature in Celsius
dewpoint_c – Dewpoint temperature in Celsius

Returns:

Relative humidity as percentage (0-100)

varunayan.vapor_pressure_from_dewpoint(dewpoint_c: float | ndarray | Series) → float | ndarray | Series[source]¶

Calculate vapor pressure from dewpoint using Magnus formula.

Parameters:: dewpoint_c – Dewpoint temperature in Celsius
Returns:: Vapor pressure in hPa

Reference: Bolton (1980), Mon. Wea. Rev. 108, 1046-1053.

Calculate wet bulb temperature using Stull (2011) empirical formula.

Reference: Stull, R. (2011). Wet-Bulb Temperature from Relative Humidity and Air Temperature. J. Appl. Meteor. Climatol., 50, 2267-2269.

Parameters:

temp_c – Air temperature in Celsius
rh – Relative humidity as percentage (0-100)

Returns:

Wet bulb temperature in Celsius

varunayan.wet_bulb_from_dewpoint(temp_c: float | ndarray | Series, dewpoint_c: float | ndarray | Series) → float | ndarray | Series[source]¶: Calculate wet bulb temperature from temperature and dewpoint.

Calculate Heat Index using the Rothfusz NWS equation.

Parameters:

temp_c – Air temperature in Celsius
rh – Relative humidity as percentage (0-100)

Returns:

Heat index in Celsius

varunayan.heat_index_from_dewpoint(temp_c: float | ndarray | Series, dewpoint_c: float | ndarray | Series) → float | ndarray | Series[source]¶: Calculate heat index from temperature and dewpoint.

Estimate Wet Bulb Globe Temperature using the Australian BoM approximation.

Closed-form WBGT from air temperature and humidity alone. Standard estimator in climate-epidemiology when wind/radiation are unavailable.

Reference: Australian Bureau of Meteorology approximation of WBGT (Steadman-based); see ACSM heat guidelines.

Parameters:

temp_c – Air temperature in Celsius
dewpoint_c – Dewpoint temperature in Celsius

Returns:

WBGT in Celsius

Calculate shade/indoor Wet Bulb Globe Temperature (ISO 7243).

Uses the indoor formula 0.7*Tw + 0.3*Ta. For a closed-form estimate from temperature and humidity alone, use wbgt_simple(); for outdoor WBGT with an explicit globe temperature, use wbgt_outdoor().

Reference: ISO 7243 standard for occupational heat stress.

Parameters:

temp_c – Air temperature in Celsius
wet_bulb_c – Wet bulb temperature in Celsius

Returns:

WBGT in Celsius

Calculate outdoor Wet Bulb Globe Temperature with solar load.

Reference: ISO 7243 standard for occupational heat stress.

Parameters:

temp_c – Air temperature in Celsius
wet_bulb_c – Wet bulb temperature in Celsius
globe_temp_c – Black globe temperature in Celsius

Returns:

WBGT in Celsius

Calculate Humidex (Canadian heat discomfort index).

Parameters:

temp_c – Air temperature in Celsius
dewpoint_c – Dewpoint temperature in Celsius

Reference: Masterson & Richardson (1979), Environment Canada.

Returns:: Humidex value (unitless, but interpreted like temperature)

Estimate mean radiant temperature from global horizontal solar radiation.

Closed-form radiation-balance estimator for a standard person from Thorsson et al. (2007), absorbing global horizontal shortwave onto the longwave radiant balance.

Reference: Thorsson, S., et al. (2007). Different methods for estimating the mean radiant temperature in an outdoor urban setting. Int. J. Climatol., 27(14), 1983-1993.

Parameters:

temp_c – Air temperature in Celsius
solar_rad_wm2 – Global horizontal solar radiation in W/m²
wind_ms – Unused; kept for backward-compatible signature. Wind enters the convective terms of UTCI/WBGT, not this radiant estimate.

Returns:

Estimated mean radiant temperature in Celsius

Calculate Universal Thermal Climate Index (UTCI) using polynomial approximation.

Reference: Bröde et al. (2012). Deriving the operational procedure for the Universal Thermal Climate Index (UTCI).

Parameters:

temp_c – Air temperature in Celsius (-50 to 50°C)
rh – Relative humidity as percentage (0-100)
wind_ms – Wind speed at 10m height in m/s (0.5 to 17 m/s)
mrt_c – Mean radiant temperature in Celsius. If None, assumes mrt = temp_c

Returns:

UTCI in Celsius

UTCI via sparse Legendre polynomial (Roman et al. 2025, doi:10.5281/zenodo.17465548).

Wider wind range than Bröde polynomial (0.5-30.3 m/s vs 0.5-17 m/s).

varunayan.heat_index_risk_category(hi: float | ndarray | Series) → str | ndarray | Series[source]¶

Categorize heat index into NWS risk categories.

Categories: - Normal: < 27°C - Caution: 27-32°C - Extreme Caution: 32-39°C - Danger: 39-51°C - Extreme Danger: >= 51°C

Parameters:: hi – Heat index in Celsius
Returns:: Risk category string(s)

varunayan.wbgt_risk_category(wbgt: float | ndarray | Series) → str | ndarray | Series[source]¶

Categorize WBGT into ISO 7243 risk categories for occupational heat stress.

Categories: - Low: < 25°C - Moderate: 25-28°C - High: 28-30°C - Very High: 30-32°C - Extreme: >= 32°C

Parameters:: wbgt – WBGT in Celsius
Returns:: Risk category string(s)

varunayan.utci_category(utci_val: float | ndarray | Series) → str | ndarray | Series[source]¶

Categorize UTCI into thermal stress categories.

Categories (10-level scale): - Extreme Cold Stress: < -40°C - Very Strong Cold Stress: -40 to -27°C - Strong Cold Stress: -27 to -13°C - Moderate Cold Stress: -13 to 0°C - Slight Cold Stress: 0 to 9°C - No Thermal Stress: 9 to 26°C - Moderate Heat Stress: 26 to 32°C - Strong Heat Stress: 32 to 38°C - Very Strong Heat Stress: 38 to 46°C - Extreme Heat Stress: >= 46°C

Parameters:: utci_val – UTCI in Celsius
Returns:: Thermal stress category string(s)

Calculate all heat stress indices at once.

Parameters:

temp_c – Air temperature in Celsius
dewpoint_c – Dewpoint temperature in Celsius
wind_ms – Wind speed in m/s (optional, needed for UTCI)
solar_rad_wm2 – Solar radiation in W/m² (optional, for outdoor MRT)

Returns:

rh: Relative humidity (%)
wet_bulb: Wet bulb temperature (°C)
heat_index: Heat index (°C)
wbgt: Wet Bulb Globe Temperature (°C)
humidex: Humidex value
utci: Universal Thermal Climate Index (°C) - if wind provided
heat_index_risk: Risk category for heat index
wbgt_risk: Risk category for WBGT
utci_stress: Stress category for UTCI - if wind provided

Return type:

Dictionary with all calculated indices

varunayan.get_era5_daily_temperature(request_id: str, start_date: str, end_date: str, north: float, south: float, east: float, west: float, resolution: float = 0.25, verbosity: int = 0) → DataFrame[source]¶

Download ERA5 daily temperature data with automatic unit conversion.

Parameters:

request_id – Unique identifier for the request
start_date – Start date in ‘YYYY-MM-DD’ format
end_date – End date in ‘YYYY-MM-DD’ format
north – Northern latitude bound
south – Southern latitude bound
east – Eastern longitude bound
west – Western longitude bound
resolution – Spatial resolution in degrees (default 0.25)
verbosity – Logging verbosity level (0-2)

Returns:

latitude, longitude, date, temp_c

Return type:

DataFrame with columns

varunayan.get_era5_daily_humidity(request_id: str, start_date: str, end_date: str, north: float, south: float, east: float, west: float, resolution: float = 0.25, verbosity: int = 0) → DataFrame[source]¶

Download ERA5 daily humidity data with automatic RH calculation.

Parameters:

request_id – Unique identifier for the request
start_date – Start date in ‘YYYY-MM-DD’ format
end_date – End date in ‘YYYY-MM-DD’ format
north – Northern latitude bound
south – Southern latitude bound
east – Eastern longitude bound
west – Western longitude bound
resolution – Spatial resolution in degrees (default 0.25)
verbosity – Logging verbosity level (0-2)

Returns:

latitude, longitude, date, temp_c, dewpoint_c, rh

Return type:

DataFrame with columns

varunayan.get_era5_daily_wind(request_id: str, start_date: str, end_date: str, north: float, south: float, east: float, west: float, resolution: float = 0.25, verbosity: int = 0) → DataFrame[source]¶

Download ERA5 daily wind data with automatic wind speed calculation.

Parameters:

request_id – Unique identifier for the request
start_date – Start date in ‘YYYY-MM-DD’ format
end_date – End date in ‘YYYY-MM-DD’ format
north – Northern latitude bound
south – Southern latitude bound
east – Eastern longitude bound
west – Western longitude bound
resolution – Spatial resolution in degrees (default 0.25)
verbosity – Logging verbosity level (0-2)

Returns:

latitude, longitude, date, u10, v10, wind_speed

Return type:

DataFrame with columns

varunayan.get_era5_daily_heat_index_data(request_id: str, start_date: str, end_date: str, north: float, south: float, east: float, west: float, solar_load: bool = False, resolution: float = 0.25, verbosity: int = 0) → DataFrame[source]¶

Download ERA5 daily data and calculate comprehensive heat stress indices.

This convenience function downloads temperature, humidity, and wind data, then calculates all common heat stress indices in one call.

Parameters:

request_id – Unique identifier for the request
start_date – Start date in ‘YYYY-MM-DD’ format
end_date – End date in ‘YYYY-MM-DD’ format
north – Northern latitude bound
south – Southern latitude bound
east – Eastern longitude bound
west – Western longitude bound
solar_load – If True, also download solar radiation for outdoor UTCI
resolution – Spatial resolution in degrees (default 0.25)
verbosity – Logging verbosity level (0-2)

Returns:

latitude, longitude, date (or year, month, day depending on aggregation)
temp_c: Temperature in Celsius
dewpoint_c: Dewpoint temperature in Celsius
rh: Relative humidity (%)
wind_speed: Wind speed in m/s
wet_bulb: Wet bulb temperature (°C)
heat_index: Heat index (°C)
wbgt: Wet Bulb Globe Temperature (°C)
humidex: Humidex value
utci: Universal Thermal Climate Index (°C)
heat_index_risk: NWS risk category
wbgt_risk: Occupational risk category
utci_stress: Thermal stress category
If solar_load=True: ssrd (solar radiation) and mrt (mean radiant temp)

Return type:

DataFrame with columns

varunayan.get_era5_monthly_heat_index_data(request_id: str, start_date: str, end_date: str, north: float, south: float, east: float, west: float, solar_load: bool = False, resolution: float = 0.25, verbosity: int = 0) → DataFrame[source]¶

Download ERA5 monthly data and calculate comprehensive heat stress indices.

Same as get_era5_daily_heat_index_data but aggregated to monthly frequency.

Parameters:

request_id – Unique identifier for the request
start_date – Start date in ‘YYYY-MM-DD’ format
end_date – End date in ‘YYYY-MM-DD’ format
north – Northern latitude bound
south – Southern latitude bound
east – Eastern longitude bound
west – Western longitude bound
solar_load – If True, also download solar radiation for outdoor UTCI
resolution – Spatial resolution in degrees (default 0.25)
verbosity – Logging verbosity level (0-2)

Returns:

DataFrame with same columns as get_era5_daily_heat_index_data, aggregated to monthly means.

varunayan.get_era5_daily_heat_index_geojson(request_id: str, start_date: str, end_date: str, geojson_file: str, dist_features: List[str] | None = None, solar_load: bool = False, resolution: float = 0.25, verbosity: int = 0) → DataFrame[source]¶

Download ERA5 daily data for a GeoJSON region and calculate heat stress indices.

Parameters:

request_id – Unique identifier for the request
start_date – Start date in ‘YYYY-MM-DD’ format
end_date – End date in ‘YYYY-MM-DD’ format
geojson_file – Path to GeoJSON file defining the region
dist_features – List of GeoJSON properties to distinguish features
solar_load – If True, also download solar radiation for outdoor UTCI
resolution – Spatial resolution in degrees (default 0.25)
verbosity – Logging verbosity level (0-2)

Returns:

DataFrame with heat stress indices for points within the GeoJSON region

varunayan.get_era5_daily_heat_index_point(request_id: str, start_date: str, end_date: str, latitude: float, longitude: float, solar_load: bool = False, verbosity: int = 0) → DataFrame[source]¶

Download ERA5 daily data for a single point and calculate heat stress indices.

Parameters:

request_id – Unique identifier for the request
start_date – Start date in ‘YYYY-MM-DD’ format
end_date – End date in ‘YYYY-MM-DD’ format
latitude – Latitude of the point
longitude – Longitude of the point
solar_load – If True, also download solar radiation for outdoor UTCI
verbosity – Logging verbosity level (0-2)

Returns:

DataFrame with heat stress indices for the specified point

varunayan.get_cache_dir() → Path[source]¶

Get the cache directory for varunayan.

Uses platformdirs-style logic to find appropriate cache location: - Linux: ~/.cache/varunayan - macOS: ~/Library/Caches/varunayan - Windows: %LOCALAPPDATA%/varunayan/cache

Returns:: Path to the cache directory

varunayan.show_cache_info() → None[source]¶: Display information about the cache directory and its contents.

varunayan.list_cache(source: str = 'all') → DataFrame[source]¶

List all cached files with metadata.

Parameters:: source – Filter by source (‘era5’, ‘imd’, or ‘all’)
Returns:: DataFrame with cache entries

varunayan.cache_stats() → Dict[str, Any][source]¶

Get statistics about the cache.

Returns:: Dictionary with cache statistics

varunayan.clear_cache(source: str = 'all', older_than_days: int | None = None, confirm: bool = True) → int[source]¶

Clear cached files.

Parameters:

source – Filter by source (‘era5’, ‘imd’, or ‘all’)
older_than_days – Only delete files older than this many days
confirm – If True, prompt for confirmation before deleting

Returns:

Number of files deleted

varunayan.cache_exists(request_id: str, variables: List[str], start_date: str, end_date: str, frequency: str, source: str = 'era5', **kwargs: Any) → bool[source]¶

Check if cached data exists for the given parameters.

Parameters:

request_id – Original request identifier
variables – List of variables requested
start_date – Start date
end_date – End date
frequency – Temporal frequency
source – Data source (‘era5’ or ‘imd’)
**kwargs – Additional parameters (bounds, resolution, etc.)

Returns:

True if cache exists, False otherwise

varunayan.get_cached_data(request_id: str, variables: List[str], start_date: str, end_date: str, frequency: str, source: str = 'era5', **kwargs: Any) → DataFrame | None[source]¶

Retrieve cached data if it exists.

Parameters:

request_id – Original request identifier
variables – List of variables requested
start_date – Start date
end_date – End date
frequency – Temporal frequency
source – Data source (‘era5’ or ‘imd’)
**kwargs – Additional parameters

Returns:

DataFrame if cache exists, None otherwise

varunayan.save_to_cache(df: DataFrame, request_id: str, variables: List[str], start_date: str, end_date: str, frequency: str, source: str = 'era5', **kwargs: Any) → str[source]¶

Save data to cache.

Parameters:

df – DataFrame to cache
request_id – Original request identifier
variables – List of variables requested
start_date – Start date
end_date – End date
frequency – Temporal frequency
source – Data source (‘era5’ or ‘imd’)
**kwargs – Additional parameters

Returns:

Cache key (MD5 hash)

varunayan.invalidate_cache(cache_key: str) → bool[source]¶

Invalidate a specific cache entry.

Parameters:: cache_key – The cache key (or partial key) to invalidate
Returns:: True if cache was found and deleted, False otherwise

varunayan.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[source]¶

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.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][source]¶

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.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[source]¶

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.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[source]¶

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.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[source]¶

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

varunayan.is_sum_var(var_name: str) → bool[source]¶: Check if a variable should be summed during aggregation.

varunayan.is_max_var(var_name: str) → bool[source]¶: Check if a variable should use max during aggregation.

varunayan.is_min_var(var_name: str) → bool[source]¶: Check if a variable should use min during aggregation.

varunayan.is_rate_var(var_name: str) → bool[source]¶: Check if a variable is a rate (should be averaged).

varunayan.categorize_variables(var_names: list) → dict[source]¶

Categorize variables by their aggregation method.

Parameters:: var_names – List of variable names
Returns:: Dictionary with keys ‘sum’, ‘max’, ‘min’, ‘rate’, ‘mean’ containing lists of variable names

varunayan.get_aggregation_method(var_name: str) → str[source]¶

Get the recommended aggregation method for a variable.

Parameters:: var_name – Variable name
Returns:: ‘sum’, ‘max’, ‘min’, or ‘mean’
Return type:: Aggregation method

varunayan.get_imd_stations(with_coordinates: bool = True, max_workers: int = 8) → DataFrame[source]¶

Return IMD observation stations, optionally with coordinates.

Parameters:

with_coordinates – if True, fetch latitude/longitude per station (concurrent requests to IMD). If False, return only id + name.
max_workers – concurrent requests when resolving coordinates.

Returns:

DataFrame with columns station_id, name and — when with_coordinates — latitude, longitude (NaN where IMD has no coordinate for a station).

varunayan.get_imd_grid_specs(dataset: str) → dict[source]¶: Return grid specifications for dataset (a key in IMD_GRID_SPECS).

varunayan.list_imd_datasets() → DataFrame[source]¶: Return a DataFrame of all IMD gridded datasets.

varunayan.download_imd_rainfall(start_year: int, end_year: int, resolution: float = 0.25, output_dir: str | None = None, use_cache: bool = True) → List[str][source]¶: Download IMD gridded rainfall for each year. Returns list of file paths.

varunayan.download_imd_temperature(start_year: int, end_year: int, var_type: str = 'tmax', output_dir: str | None = None, use_cache: bool = True) → List[str][source]¶: Download IMD gridded temperature for each year. Returns list of file paths.

varunayan.read_imd_temperature(file_path: str, var_type: str, year: int) → DataFrame[source]¶: Read an IMD binary .grd temperature file (32-bit LE floats, nlon x nlat x ndays).

varunayan.read_imd_rainfall(file_path: str, resolution: float, year: int) → DataFrame[source]¶: Read an IMD NetCDF rainfall file.

varunayan.process_imd_files(file_paths: List[str], var_type: str, resolution: float | None = None, years: List[int] | None = None) → DataFrame[source]¶: Read and concatenate multiple IMD files.

varunayan.filter_imd_by_bbox(data: DataFrame, north: float, south: float, east: float, west: float) → DataFrame[source]¶: Filter IMD data to a lat/lon bounding box.

varunayan.filter_imd_by_geojson(data: DataFrame, geojson_file: str) → DataFrame[source]¶: Filter IMD data to points within a GeoJSON polygon.

varunayan.aggregate_imd_by_frequency(data: DataFrame, frequency: str = 'daily') → DataFrame[source]¶: Aggregate IMD data: SUM for rainfall, MEAN for temperature.

varunayan.imd_rainfall_bbox(request_id: str, start_year: int, end_year: int, north: float, south: float, east: float, west: float, resolution: float = 0.25, frequency: str = 'daily', use_cache: bool = True) → DataFrame[source]¶: Download, bbox-filter, aggregate IMD rainfall.

varunayan.imd_rainfall_geojson(request_id: str, start_year: int, end_year: int, geojson_file: str, resolution: float = 0.25, frequency: str = 'daily', use_cache: bool = True) → DataFrame[source]¶: Download, geojson-filter, aggregate IMD rainfall.

varunayan.imd_temperature_bbox(request_id: str, start_year: int, end_year: int, north: float, south: float, east: float, west: float, var_type: str = 'tmax', frequency: str = 'daily', use_cache: bool = True) → DataFrame[source]¶: Download, bbox-filter, aggregate IMD temperature.

varunayan.imd_temperature_geojson(request_id: str, start_year: int, end_year: int, geojson_file: str, var_type: str = 'tmax', frequency: str = 'daily', use_cache: bool = True) → DataFrame[source]¶: Download, geojson-filter, aggregate IMD temperature.

varunayan.list_hadex3_indices(frequency: str = 'all') → DataFrame[source]¶: Return a DataFrame of all ETCCDI indices.

varunayan.hadex3_bbox(index: str, start_year: int, end_year: int, north: float, south: float, east: float, west: float, frequency: str = 'annual', baseline: str = '61-90', use_cache: bool = True) → DataFrame[source]¶: Download HadEX3 data filtered to a bounding box.

varunayan.hadex3_geojson(index: str, start_year: int, end_year: int, geojson_file: str, frequency: str = 'annual', baseline: str = '61-90', use_cache: bool = True) → DataFrame[source]¶: Download HadEX3 data filtered to a GeoJSON polygon.

varunayan.list_cru_ts_variables() → DataFrame[source]¶: Return a DataFrame of all CRU TS variables.

varunayan.cru_ts_bbox(variable: str, start_year: int, end_year: int, north: float, south: float, east: float, west: float, use_cache: bool = True) → DataFrame[source]¶: Download CRU TS data filtered to a bounding box.

varunayan.cru_ts_geojson(variable: str, start_year: int, end_year: int, geojson_file: str, use_cache: bool = True) → DataFrame[source]¶: Download CRU TS data filtered to a GeoJSON polygon.

varunayan.get_era5_country_temperature(country: str | GeoDataFrame, start_date: str, end_date: str, variables: str | List[str] = 'mean', request_id: str | None = None, resolution: float = 0.25) → DataFrame[source]¶

Download and aggregate ERA5 temperature for a country.

Resolves the country boundary via Natural Earth, downloads monthly ERA5 data, filters grid points to the country polygon, and returns cosine-latitude area-weighted national averages by year and month.

Parameters:

country – Country name, ISO-3166 code, GeoJSON file path, or GeoDataFrame.
start_date – Start date (YYYY-MM-DD).
end_date – End date (YYYY-MM-DD).
variables – Temperature shorthand(s): “mean”, “max”, “min”, or ERA5 variable names.
request_id – Cache identifier. Auto-generated from country name if omitted.
resolution – Spatial resolution in degrees.

Returns:

DataFrame with columns year, month, and one per variable (temperature_mean, temperature_max, temperature_min).