Package 'varunayan'

Description

Aggregate data by temporal frequency

Usage

aggregate_by_frequency(data, frequency, verbose = FALSE)

Arguments

Value

data.frame with temporally aggregated data

Description

Aggregate IMD data by temporal frequency

Usage

aggregate_imd_by_frequency(data, frequency = "daily")

Arguments

Value

A data.frame with columns date (first day of each month or year), latitude, longitude and the value column, summed for rainfall and averaged for temperature. Returned unchanged when frequency = "daily".

Examples

imd <- data.frame(
  date = rep(as.Date("2023-01-01") + 0:59, each = 2),
  latitude = 20.5, longitude = c(73.5, 79.5), rainfall = 1
)
aggregate_imd_by_frequency(imd, "monthly")

Description

Aggregate gridded data to polygon regions

Usage

aggregate_to_polygons(
  data,
  polygons,
  value_col,
  method = c("nearest_centroid", "point_in_polygon"),
  polygon_id_cols = NULL,
  agg_fun = mean
)

Arguments

Value

A tibble with one row per polygon: the polygon_id_cols columns and value, the mean of value_col over the grid points assigned to that polygon.

Examples

grid <- expand.grid(longitude = seq(72.5, 77.5, by = 1), latitude = seq(18.5, 21.5, by = 1))
grid$temperature <- seq_len(nrow(grid))
cells <- sf::st_make_grid(sf::st_as_sfc(sf::st_bbox(
  c(xmin = 72, ymin = 18, xmax = 78, ymax = 22),
  crs = 4326
)), n = c(2, 1))
polys <- sf::st_sf(region = c("west", "east"), geometry = cells)
aggregate_to_polygons(grid, polys, value_col = "temperature")

Description

Get cache statistics

Usage

cache_stats()

Value

A list with elements exists (logical), n_files and total_size_mb.

Examples

cache_stats()

Description

Calculate all heat stress indices from temperature and dewpoint.

Usage

calc_heat_indices(temp_c, dewpoint_c)

Arguments

Value

Data frame with columns: temp_c, dewpoint_c, rh, wet_bulb, heat_index, wbgt, humidex

Examples

calc_heat_indices(35, 25)
calc_heat_indices(c(30, 35, 40), c(20, 25, 28))

Description

Categorize variables by aggregation method

Usage

categorize_variables(var_names)

Arguments

Value

Named list with variables categorized by aggregation method

Examples

categorize_variables(c("2m_temperature", "total_precipitation"))

Description

Check grid coverage statistics for polygons

Usage

check_grid_coverage(grid_data, polygons, polygon_id_cols = NULL)

Arguments

Value

A list with elements total_polygons, total_grid_points, polygons_with_points, polygons_without_points, coverage_percent, points_per_polygon (a data.frame of polygon identifiers and n_points) and summary (a one-line character description).

Examples

grid <- expand.grid(longitude = seq(72.5, 77.5, by = 1), latitude = seq(18.5, 21.5, by = 1))
grid$temperature <- seq_len(nrow(grid))
cells <- sf::st_make_grid(sf::st_as_sfc(sf::st_bbox(
  c(xmin = 72, ymin = 18, xmax = 78, ymax = 22),
  crs = 4326
)), n = c(2, 1))
polys <- sf::st_sf(region = c("west", "east"), geometry = cells)
check_grid_coverage(grid, polys)

Description

Check system readiness for varunayan operations

Usage

CheckSystemReadiness(...)

check_system_readiness(verbose = TRUE)

Arguments

Value

Invisibly, TRUE if all required packages, network access and CDS credentials are available, FALSE otherwise.

Examples

check_system_readiness()

Description

Clean up temporary files matching pattern

Usage

cleanup_temp_files(pattern = "varunayan_.*", directory = tempdir())

Arguments

Value

Number of files removed

Description

Clear all timing data

Usage

clear_timings()

Value

NULL, invisibly. Called for its side effect.

Examples

clear_timings()

Description

Clear cache

Usage

ClearCache(...)

clear_cache(source = NULL, older_than = NULL, confirm = TRUE)

Arguments

Value

Invisibly, the number of files deleted.

Examples

# Remove cached ERA5 files older than 30 days
clear_cache(source = "era5", older_than = 30)

Description

Combine multiple NetCDF files into single data.frame

Usage

combine_netcdf_files(netcdf_files, verbose = FALSE)

Arguments

Value

data.frame with combined data from all files

Description

Compare multiple grids

Usage

compare_grids(
  ...,
  polygons = NULL,
  colors = NULL,
  shapes = NULL,
  point_size = 1,
  polygon_color = "#2C3E50",
  title = "Grid Comparison"
)

Arguments

Value

ggplot object

Examples

grid <- expand.grid(longitude = seq(72.5, 77.5, by = 1), latitude = seq(18.5, 21.5, by = 1))
grid$temperature <- seq_len(nrow(grid))
cells <- sf::st_make_grid(sf::st_as_sfc(sf::st_bbox(
  c(xmin = 72, ymin = 18, xmax = 78, ymax = 22),
  crs = 4326
)), n = c(2, 1))
polys <- sf::st_sf(region = c("west", "east"), geometry = cells)
coarse <- grid[grid$longitude < 75, ]
compare_grids(fine = grid, coarse = coarse, polygons = polys)

Description

Convert data to GeoJSON format

Usage

convert_to_geojson(data)

Arguments

Value

GeoJSON formatted data

Description

Create GeoJSON from bounding box coordinates

Usage

create_geojson_from_bbox(north, south, east, west)

Arguments

Value

GeoJSON object representing the bounding box

Description

Create temporary GeoJSON file

Usage

create_temp_geojson_file(geojson_data, request_id)

Arguments

Value

Path to temporary GeoJSON file

Description

Chunk size defaults to compute_optimal_chunk_size(frequency), which scales with the CDS field limit (hourly: 24 fields/day, daily: 1/day, monthly: 12/year) so each chunk fills one CDS job.

Usage

create_temporal_chunks(
  start_date,
  end_date,
  frequency,
  n_variables = 1L,
  max_days_per_chunk = NA
)

Arguments

Value

List of date pairs for chunked processing

Description

Functions to download and process the University of East Anglia Climatic Research Unit Time-Series (CRU TS) gridded monthly climate dataset. Covers global land areas (excl. Antarctica) at 0.5 degree resolution, 1901-2022.

Usage

.CRU_TS_VERSION

References

Harris et al. (2020) Version 4 of the CRU TS monthly high-resolution gridded multivariate climate dataset. Sci. Data 7:109. doi:10.1038/s41597-020-0453-3

Description

Downloads and filters CRU TS v4.07 monthly gridded climate data to a geographic bounding box. Data covers global land areas at 0.5 degree resolution, 1901-2022.

Usage

CRUTSBbox(...)

cru_ts_bbox(
  variable,
  start_year,
  end_year,
  north,
  south,
  east,
  west,
  output_dir = tempdir(),
  use_cache = TRUE,
  ...
)

Arguments

Value

data.frame with columns: year, month, latitude, longitude, value, variable.

Examples

# Monthly mean temperature for India 2010-2020
data <- cru_ts_bbox(
  variable = "tmp",
  start_year = 2010, end_year = 2020,
  north = 35, south = 8, east = 97, west = 68
)

# Precipitation for Europe 1981-2010
data <- cru_ts_bbox(
  variable = "pre",
  start_year = 1981, end_year = 2010,
  north = 71, south = 36, east = 40, west = -10
)

Description

Downloads and filters CRU TS v4.07 monthly gridded climate data to a geographic region defined by a GeoJSON polygon.

Usage

CRUTSGeojson(...)

cru_ts_geojson(
  variable,
  start_year,
  end_year,
  geojson_file,
  output_dir = tempdir(),
  use_cache = TRUE,
  ...
)

Arguments

Value

data.frame with columns: year, month, latitude, longitude, value, variable.

Examples

region <- system.file("extdata", "region.geojson", package = "varunayan")
data <- cru_ts_geojson(
  variable = "tmp",
  start_year = 1981, end_year = 2010,
  geojson_file = region
)

Description

Describe ERA5 variables in detail

Usage

DescribeVariables(...)

describe_variables(variables, dataset_type = "all")

Arguments

Value

A data.frame with columns variable_name, description, units, dataset_type and category, one row per matched variable.

Examples

# Describe specific variables
descriptions <- describe_variables(c("2m_temperature", "total_precipitation"))

# Get descriptions for pressure level variables
pressure_desc <- describe_variables("temperature", dataset_type = "pressure")

Description

Download ERA5 pressure-level data using ecmwfr

Usage

download_era5_pressure(
  variables,
  pressure_levels,
  start_date,
  end_date,
  area = NULL,
  resolution = 0.25,
  frequency = "hourly",
  output_file,
  use_cache = TRUE,
  verbose = FALSE
)

Arguments

Value

Character string path to downloaded file

Description

Download ERA5 single-level data using ecmwfr

Usage

download_era5_single(
  variables,
  start_date,
  end_date,
  area = NULL,
  resolution = 0.25,
  frequency = "hourly",
  output_file,
  timeout = 3600,
  retry_attempts = 5,
  use_cache = TRUE,
  verbose = FALSE
)

Arguments

Value

Character string path to downloaded file

Description

Downloads daily gridded rainfall data from IMD at specified resolution.

Usage

download_imd_rainfall(
  start_year,
  end_year,
  resolution = 0.25,
  output_dir = tempdir(),
  use_cache = TRUE
)

Arguments

Value

Character vector of downloaded file paths

Examples

# Download 0.25 degree rainfall for 2023-2025
files <- download_imd_rainfall(
  start_year = 2023,
  end_year = 2025,
  resolution = 0.25
)

Description

Downloads daily gridded temperature data (max or min) from IMD. Temperature data is at 1.0 degree resolution only.

Usage

download_imd_temperature(
  start_year,
  end_year,
  var_type = "tmax",
  output_dir = tempdir(),
  use_cache = TRUE
)

Arguments

Value

Character vector of downloaded file paths

Examples

# Download max temperature for 2023-2025
files <- download_imd_temperature(
  start_year = 2023,
  end_year = 2025,
  var_type = "tmax"
)

Description

Create output directory if it doesn't exist

Usage

ensure_output_dir(output_dir)

Arguments

Value

Character string path to created/existing directory

Description

Download and process ERA5 data for a bounding box

Usage

ERA5ifyBbox(...)

era5ify_bbox(
  request_id,
  variables,
  start_date,
  end_date,
  north,
  south,
  east,
  west,
  dataset_type = "single",
  pressure_levels = NULL,
  frequency = "hourly",
  resolution = 0.25,
  save_raw = FALSE,
  output_dir = tempdir(),
  use_cache = TRUE,
  convert_units = TRUE,
  verbose = FALSE
)

Arguments

Value

data.frame with processed climate data. When convert_units = TRUE:

• Temperature variables (e.g., 2m_temperature): Celsius

• Precipitation variables (e.g., total_precipitation): mm

• Other variables: original ERA5 units

Examples

setup_cds_credentials(key = "your-cds-api-key")

data <- era5ify_bbox(
  request_id = "my_request",
  variables = c("2m_temperature", "total_precipitation"),
  start_date = "2023-01-01",
  end_date = "2023-01-31",
  north = 40, south = 35, east = -70, west = -75
)
# Temperature is in Celsius, precipitation is in mm

Description

Download and process ERA5 data for a point location

Usage

ERA5ifyPoint(...)

era5ify_point(
  request_id,
  variables,
  start_date,
  end_date,
  lat,
  lon,
  dataset_type = "single",
  pressure_levels = NULL,
  frequency = "hourly",
  save_raw = FALSE,
  output_dir = tempdir(),
  use_cache = TRUE,
  convert_units = TRUE,
  verbose = FALSE,
  use_timeseries_api = NA
)

Arguments

Value

data.frame with processed climate data. When convert_units = TRUE:

• Temperature variables (e.g., 2m_temperature): Celsius

• Precipitation variables (e.g., total_precipitation): mm

• Other variables: original ERA5 units

Examples

setup_cds_credentials(key = "your-cds-api-key")

data <- era5ify_point(
  request_id = "my_request",
  variables = c("2m_temperature", "total_precipitation"),
  start_date = "2023-01-01",
  end_date = "2023-01-31",
  lat = 40.7128,
  lon = -74.0060
)
# Temperature is in Celsius, precipitation is in mm

Description

Excess Heat Factor (EHF) of Nairn & Fawcett (2015). Daily mean temperature (DMT) pairs each day's maximum with the following night's minimum, T_i = (tmax_i + tmin_(i+1)) / 2. For the three-day period starting on day i, EHI_sig = mean(T_i, T_i+1, T_i+2) - T95 and EHI_accl = mean(T_i, T_i+1, T_i+2) - mean(T_i-1, ..., T_i-30), with T95 the 95th percentile of DMT over the baseline years; EHF = EHI_sig * max(1, EHI_accl). Positive EHF marks heatwave conditions; EHF85, the 85th percentile of positive baseline EHF values, is the severe threshold and 3 * EHF85 the extreme threshold.

Usage

excess_heat_factor(date, tmax, tmin, baseline)

Arguments

Value

A data.frame with date, dmt, ehi_sig, ehi_accl and ehf (degrees Celsius squared), indexed by the first day of each three-day period, with attributes t95 and ehf85. NA where the windows are incomplete.

References

Nairn, J.R. & Fawcett, R.J.B. (2015). The Excess Heat Factor: A Metric for Heatwave Intensity and Its Use in Classifying Heatwave Severity. International Journal of Environmental Research and Public Health, 12(1), 227-253. doi:10.3390/ijerph120100227

Examples

d <- seq(as.Date("2001-01-01"), as.Date("2003-12-31"), by = "day")
doy <- as.POSIXlt(d)$yday
tmax <- 33 + 8 * sin(2 * pi * (doy - 80) / 365)
tmax[d >= as.Date("2003-05-10") & d <= as.Date("2003-05-16")] <- 47
ehf <- excess_heat_factor(d, tmax, tmax - 12, baseline = c(2001, 2002))
subset(ehf, ehf > 0 & date > as.Date("2003-05-01") & date < as.Date("2003-05-31"))

Description

These are coordinate and metadata columns that should not be aggregated.

Usage

exclude_cols

Value

A character vector of variable names.

Examples

head(exclude_cols)

Description

Summarizes daily temperature (and optionally humidity) into heat exposure indicators per location and year or month, as used in heat-health vulnerability indices: heatwave and warm-night frequency and duration, diurnal temperature range, WBGT, heat index and wet-bulb temperature, plus the ETCCDI indices TX90p, TN90p, WSDI and tropical nights.

Usage

exposure_indicators(
  data,
  by = c("latitude", "longitude"),
  period = c("year", "month"),
  months = NULL,
  baseline = c(1991, 2020),
  heatwave_method = c("imd", "percentile", "ehf"),
  warm_night_method = c("imd", "percentile", "absolute"),
  terrain = c("auto", "plains", "coastal", "hilly"),
  hill_elevation = 1200,
  cell_size = NULL
)

Arguments

Details

data needs columns date, tmax and tmin (degrees Celsius), one row per day per location, covering the baseline years. With a dewpoint column (degrees Celsius), afternoon humidity metrics are computed from tmax and dewpoint: WBGT by wbgt_simple(), heat index and wet-bulb temperature. A wbgt column, such as daily maxima of wbgt_liljegren(), replaces the wbgt_simple() estimate.

Spells are found on the full series, so a heatwave spanning two periods counts as an event in the period where it starts and its days count where they fall. months filters the summary.

Value

A data.frame with one row per location and period and columns:

n_days

days with data

tmax_mean, tmin_mean

mean daily maximum and minimum temperature

dtr_mean

mean diurnal temperature range (ETCCDI DTR)

hot_days

days with Tmax of at least 40 C

tropical_nights

nights with Tmin above 20 C (ETCCDI TR)

tx90p, tn90p

percent of days above the calendar-day 90th percentile of Tmax and Tmin

wsdi

days in runs of at least 6 days with Tmax above its 90th percentile (ETCCDI WSDI)

heatwave_days, heatwave_events, heatwave_longest, severe_heatwave_days

heatwave duration (total days), frequency (events starting in the period), longest event and severe days, from heatwave_days()

warm_nights, warm_night_spells, warm_night_longest, very_warm_nights

the same for warm_nights()

With humidity: wbgt_mean, wbgt_max, wbgt_days_high (WBGT of at least 29.4 C, 85 F) and wbgt_days_extreme (at least 31.1 C, 88 F), heat_index_max, heat_index_days_danger (at least 39.4 C, 103 F), wet_bulb_max and wet_bulb_days_31 (wet bulb of at least 31 C, near the 30.55 C mean critical limit of Vecellio et al. 2022).

References

Vecellio, D.J., Wolf, S.T., Cottle, R.M. & Kenney, W.L. (2022). Evaluating the 35 C wet-bulb temperature adaptability threshold for young, healthy subjects (PSU HEAT Project). Journal of Applied Physiology, 132(2), 340-345. doi:10.1152/japplphysiol.00738.2021

See Also

imd_exposure_bbox() to download IMD data and compute these in one call; ndvi() and ndbi() for the land-surface indicators.

Examples

d <- seq(as.Date("2001-01-01"), as.Date("2004-12-31"), by = "day")
doy <- as.POSIXlt(d)$yday
tmax <- 33 + 8 * sin(2 * pi * (doy - 80) / 365)
tmax[d >= as.Date("2004-05-10") & d <= as.Date("2004-05-14")] <- 46.5
daily <- data.frame(date = d, tmax = tmax, tmin = tmax - 13, dewpoint = 18)
exposure_indicators(daily, by = NULL, baseline = c(2001, 2003), terrain = "plains")

# Jaipur: terrain looked up from the coordinates
daily$latitude <- 26.9
daily$longitude <- 75.8
exposure_indicators(daily, baseline = c(2001, 2003))

Description

Extract data for specific point location (nearest neighbor)

Usage

extract_point_data(netcdf_file, target_lat, target_lon)

Arguments

Value

data.frame with data for nearest point

Description

Tests only unique (lat, lon) coordinates against the polygon, then joins back to full dataset via data.table keyed semi-join.

Usage

filter_dataframe_by_geojson(df, geojson_file)

Arguments

Value

data.frame with spatially filtered data

Description

Filter IMD data by spatial boundaries

Usage

filter_imd_by_bbox(data, north, south, east, west)

Arguments

Value

The input data.frame restricted to rows whose latitude/longitude fall inside the region; columns are unchanged.

Examples

imd <- data.frame(
  date = rep(as.Date("2023-01-01") + 0:59, each = 2),
  latitude = 20.5, longitude = c(73.5, 79.5), rainfall = 1
)
filter_imd_by_bbox(imd, north = 22, south = 18, east = 76, west = 72)

Description

Filter IMD data by GeoJSON polygon

Usage

filter_imd_by_geojson(data, geojson_file)

Arguments

Value

The input data.frame restricted to rows whose latitude/longitude fall inside the region; columns are unchanged.

Examples

imd <- data.frame(
  date = rep(as.Date("2023-01-01") + 0:59, each = 2),
  latitude = 20.5, longitude = c(73.5, 79.5), rainfall = 1
)
region <- system.file("extdata", "region.geojson", package = "varunayan")
filter_imd_by_geojson(imd, region)

Description

Filter NetCDF data by spatial boundaries (bounding box)

Usage

filter_netcdf_by_bbox(netcdf_file, north, south, east, west)

Arguments

Value

data.frame with spatially filtered data

Description

Filter NetCDF data by GeoJSON polygon

Usage

filter_netcdf_by_geojson(netcdf_file, geojson_file)

Arguments

Value

data.frame with spatially filtered data

Description

Format date range for CDS API requests

Usage

format_date_range(start_date, end_date)

Arguments

Value

Character vector of date strings in YYYY-MM-DD format

Description

Convert pressure levels to character format required by CDS API

Usage

format_pressure_levels(pressure_levels)

Arguments

Value

Character vector of pressure levels

Description

Get available dataset types

Usage

get_available_datasets()

Value

Character vector of available dataset types

Examples

get_available_datasets()

Description

Get bounding box from sf object

Usage

get_bbox_from_sf(sf_obj)

Arguments

Value

Named numeric vector with xmin, ymin, xmax, ymax

Description

Checks the CDS_API_KEY environment variable, then the 'ecmwfr' keyring, then ⁠~/.cdsapirc⁠. A key found in the environment variable or in ⁠~/.cdsapirc⁠ is registered with 'ecmwfr' via ecmwfr::wf_set_key().

Usage

get_cds_credentials(silent = FALSE)

Arguments

Value

TRUE if credentials are available, FALSE otherwise.

Examples

get_cds_credentials()

Description

Returns grid specifications for different IMD datasets.

Usage

get_imd_grid_specs(dataset)

Arguments

Value

A list with elements nlat, nlon, lat_start, lat_end, lon_start, lon_end, resolution (degrees), unit, missing_value, format and description.

Examples

specs <- get_imd_grid_specs("rainfall_0.25")

Description

Get all valid pressure-level variable names

Usage

get_pressure_level_variable_names()

Value

Character vector of valid pressure-level variable names

Description

Get pressure-level variables dataset

Usage

get_pressure_level_variables()

Value

List containing pressure-level variable categories

Description

Get all valid single-level variable names

Usage

get_single_level_variable_names()

Value

Character vector of valid single-level variable names

Description

Get single-level variables dataset

Usage

get_single_level_variables()

Value

List containing single-level variable categories

Description

Get time values based on frequency

Usage

get_time_values(frequency)

Arguments

Value

Character vector of time strings

Description

Get all recorded timings

Usage

get_timings()

Value

A data.frame with columns label, elapsed_seconds, timestamp and duration (formatted), one row per timed operation; zero rows if nothing has been timed.

Examples

get_timings()

Description

Get standard pressure levels available in ERA5

Usage

GetAvailablePressureLevels(...)

get_available_pressure_levels()

Arguments

Value

Character vector of pressure levels in hPa

Examples

get_available_pressure_levels()

Description

Defaults to tools::R_user_dir("varunayan", "cache"). Set the option varunayan.cache_dir to use a different directory.

Usage

GetCacheDir(...)

get_cache_dir(create = TRUE)

Arguments

Value

Character string with cache directory path

Examples

get_cache_dir(create = FALSE)

Description

Download and aggregate ERA5 temperature data for a country. Resolves the country boundary, downloads monthly data via era5ify_geojson(), and returns area-weighted (cosine-latitude) country-level averages by year and month.

Usage

GetERA5CountryTemperature(...)

get_era5_country_temperature(
  country,
  start_date,
  end_date,
  variables = "mean",
  request_id = NULL,
  resolution = 0.25,
  verbose = FALSE,
  ...
)

Arguments

Value

A data.frame with columns year, month, and one column per requested variable (e.g., temperature_mean, temperature_max, temperature_min). Temperature values are in Celsius.

Examples

# Monthly mean temperature for India
get_era5_country_temperature("India", "2023-06-01", "2023-06-30")

# Mean and max temperature for USA
get_era5_country_temperature("USA", "2023-01-01", "2023-12-31",
  variables = c("mean", "max")
)

# Using an sf object directly
library(sf)
poly <- st_read("my_country.geojson")
get_era5_country_temperature(poly, "2023-01-01", "2023-06-30")

Description

Download ERA5 climate variables (temperature, humidity, wet bulb, wind, solar radiation) for a region.

Usage

GetERA5DailyClimate(
  request_id,
  start_date,
  end_date,
  variables = c("temperature", "humidity"),
  json_file = NULL,
  north = NULL,
  south = NULL,
  east = NULL,
  west = NULL,
  resolution = 0.25,
  use_cache = TRUE,
  verbose = FALSE
)

get_era5_daily_climate(
  request_id,
  start_date,
  end_date,
  variables = c("temperature", "humidity"),
  json_file = NULL,
  north = NULL,
  south = NULL,
  east = NULL,
  west = NULL,
  resolution = 0.25,
  use_cache = TRUE,
  verbose = FALSE
)

Arguments

Value

data.frame with date, latitude, longitude, and requested variables

Examples

region <- system.file("extdata", "region.geojson", package = "varunayan")
# Get temperature and humidity
climate <- GetERA5DailyClimate(
  request_id = "india_climate",
  start_date = "2023-05-01",
  end_date = "2023-05-31",
  variables = c("temperature", "humidity"),
  json_file = region
)

Description

Download ERA5 temperature, dewpoint, and wind data for a region and calculate heat stress indices.

Usage

GetERA5DailyHeatIndexData(
  request_id,
  start_date,
  end_date,
  json_file = NULL,
  north = NULL,
  south = NULL,
  east = NULL,
  west = NULL,
  solar_load = FALSE,
  resolution = 0.25,
  use_cache = TRUE,
  verbose = FALSE
)

get_era5_daily_heat_index_data(
  request_id,
  start_date,
  end_date,
  json_file = NULL,
  north = NULL,
  south = NULL,
  east = NULL,
  west = NULL,
  solar_load = FALSE,
  resolution = 0.25,
  use_cache = TRUE,
  verbose = FALSE
)

GetERA5DailyHeatData(
  request_id,
  start_date,
  end_date,
  json_file = NULL,
  north = NULL,
  south = NULL,
  east = NULL,
  west = NULL,
  solar_load = FALSE,
  resolution = 0.25,
  use_cache = TRUE,
  verbose = FALSE
)

get_era5_daily_heat_data(
  request_id,
  start_date,
  end_date,
  json_file = NULL,
  north = NULL,
  south = NULL,
  east = NULL,
  west = NULL,
  solar_load = FALSE,
  resolution = 0.25,
  use_cache = TRUE,
  verbose = FALSE
)

Arguments

Value

data.frame with columns: date, latitude, longitude, temp_c, dewpoint_c, wind_speed, rh, wet_bulb, heat_index, wbgt, utci, humidex, wbgt_risk, heat_index_risk, utci_stress. When solar_load=TRUE, also includes solar_radiation.

Examples

region <- system.file("extdata", "region.geojson", package = "varunayan")
heat_data <- GetERA5DailyHeatIndexData(
  request_id = "india_heat_2023",
  start_date = "2023-05-01",
  end_date = "2023-05-31",
  json_file = region
)

# With solar radiation for outdoor WBGT
heat_data <- GetERA5DailyHeatIndexData(
  request_id = "india_heat_2023_solar",
  start_date = "2023-05-01",
  end_date = "2023-05-31",
  json_file = region,
  solar_load = TRUE
)

Description

Downloads temperature, dewpoint, and calculates relative humidity.

Usage

GetERA5DailyHumidity(
  request_id,
  start_date,
  end_date,
  json_file = NULL,
  north = NULL,
  south = NULL,
  east = NULL,
  west = NULL,
  resolution = 0.25,
  use_cache = TRUE,
  verbose = FALSE
)

get_era5_daily_humidity(
  request_id,
  start_date,
  end_date,
  json_file = NULL,
  north = NULL,
  south = NULL,
  east = NULL,
  west = NULL,
  resolution = 0.25,
  use_cache = TRUE,
  verbose = FALSE
)

Arguments

Value

data.frame with date, latitude, longitude, temp_c, dewpoint_c, rh

Examples

region <- system.file("extdata", "region.geojson", package = "varunayan")
humidity <- GetERA5DailyHumidity(
  request_id = "india_humidity",
  start_date = "2023-05-01",
  end_date = "2023-05-31",
  json_file = region
)

Description

Download daily ERA5 temperature data

Usage

GetERA5DailyTemperature(
  request_id,
  start_date,
  end_date,
  json_file = NULL,
  north = NULL,
  south = NULL,
  east = NULL,
  west = NULL,
  resolution = 0.25,
  use_cache = TRUE,
  verbose = FALSE
)

get_era5_daily_temperature(
  request_id,
  start_date,
  end_date,
  json_file = NULL,
  north = NULL,
  south = NULL,
  east = NULL,
  west = NULL,
  resolution = 0.25,
  use_cache = TRUE,
  verbose = FALSE
)

Arguments

Value

data.frame with date, latitude, longitude, temp_c

Examples

region <- system.file("extdata", "region.geojson", package = "varunayan")
temp <- GetERA5DailyTemperature(
  request_id = "india_temp",
  start_date = "2023-05-01",
  end_date = "2023-05-31",
  json_file = region
)

Description

Downloads temperature, dewpoint, and calculates RH and wet bulb temperature.

Usage

GetERA5DailyWetBulb(
  request_id,
  start_date,
  end_date,
  json_file = NULL,
  north = NULL,
  south = NULL,
  east = NULL,
  west = NULL,
  resolution = 0.25,
  use_cache = TRUE,
  verbose = FALSE
)

get_era5_daily_wet_bulb(
  request_id,
  start_date,
  end_date,
  json_file = NULL,
  north = NULL,
  south = NULL,
  east = NULL,
  west = NULL,
  resolution = 0.25,
  use_cache = TRUE,
  verbose = FALSE
)

Arguments

Value

data.frame with date, latitude, longitude, temp_c, dewpoint_c, rh, wet_bulb

Examples

region <- system.file("extdata", "region.geojson", package = "varunayan")
wetbulb <- GetERA5DailyWetBulb(
  request_id = "india_wetbulb",
  start_date = "2023-05-01",
  end_date = "2023-05-31",
  json_file = region
)

Description

Downloads 10m wind components and calculates wind speed.

Usage

GetERA5DailyWind(
  request_id,
  start_date,
  end_date,
  json_file = NULL,
  north = NULL,
  south = NULL,
  east = NULL,
  west = NULL,
  resolution = 0.25,
  use_cache = TRUE,
  verbose = FALSE
)

get_era5_daily_wind(
  request_id,
  start_date,
  end_date,
  json_file = NULL,
  north = NULL,
  south = NULL,
  east = NULL,
  west = NULL,
  resolution = 0.25,
  use_cache = TRUE,
  verbose = FALSE
)

Arguments

Value

data.frame with date, latitude, longitude, wind_speed

Examples

region <- system.file("extdata", "region.geojson", package = "varunayan")
wind <- GetERA5DailyWind(
  request_id = "india_wind",
  start_date = "2023-05-01",
  end_date = "2023-05-31",
  json_file = region
)

Description

Download ERA5 heat stress indices aggregated to a given month.

Usage

GetERA5MonthlyHeatIndexData(
  request_id,
  year,
  month,
  json_file = NULL,
  north = NULL,
  south = NULL,
  east = NULL,
  west = NULL,
  solar_load = FALSE,
  resolution = 0.25,
  use_cache = TRUE,
  verbose = FALSE
)

get_era5_monthly_heat_index_data(
  request_id,
  year,
  month,
  json_file = NULL,
  north = NULL,
  south = NULL,
  east = NULL,
  west = NULL,
  solar_load = FALSE,
  resolution = 0.25,
  use_cache = TRUE,
  verbose = FALSE
)

GetERA5MonthlyHeatData(
  request_id,
  year,
  month,
  json_file = NULL,
  north = NULL,
  south = NULL,
  east = NULL,
  west = NULL,
  solar_load = FALSE,
  resolution = 0.25,
  use_cache = TRUE,
  verbose = FALSE
)

get_era5_monthly_heat_data(
  request_id,
  year,
  month,
  json_file = NULL,
  north = NULL,
  south = NULL,
  east = NULL,
  west = NULL,
  solar_load = FALSE,
  resolution = 0.25,
  use_cache = TRUE,
  verbose = FALSE
)

Arguments

Value

A data.frame with one row per grid point for the requested month: year, month, latitude, longitude, monthly means of the daily heat stress variables, and the categorical columns wbgt_risk, heat_index_risk and utci_stress.

Examples

region <- system.file("extdata", "region.geojson", package = "varunayan")
heat_may <- GetERA5MonthlyHeatIndexData(
  request_id = "india_may2023",
  year = 2023,
  month = 5,
  json_file = region
)

Description

Get package version information

Usage

GetPackageInfo(...)

get_package_info()

Arguments

Value

The utils::sessionInfo() object, invisibly. Called for its side effect of reporting the R version, platform and versions of key dependencies as messages.

Examples

get_package_info()

Description

Functions to download and process the Met Office HadEX3 global climate extremes dataset based on ETCCDI indices.

Usage

.HADEX3_ANNUAL_INDICES

References

Dunn et al. (2020) Development of an updated global land in-situ-based dataset of temperature and precipitation extremes: HadEX3. J. Geophys. Res. Atmos. doi:10.1029/2019JD032263

Description

Downloads and filters HadEX3 ETCCDI climate extremes data to a geographic bounding box. Data covers 1901-2018 at 1.25 x 1.875 degree resolution.

Usage

HadEX3Bbox(...)

hadex3_bbox(
  index,
  start_year,
  end_year,
  north,
  south,
  east,
  west,
  frequency = "annual",
  baseline = "61-90",
  output_dir = tempdir(),
  use_cache = TRUE
)

Arguments

Value

data.frame with columns: year (+ month for monthly), latitude, longitude, value, index.

Examples

# Annual maximum daily maximum temperature for Europe 1981-2010
data <- hadex3_bbox(
  index = "TXx",
  start_year = 1981, end_year = 2010,
  north = 71, south = 36, east = 40, west = -10
)

# Monthly Rx1day for India
data <- hadex3_bbox(
  index = "Rx1day",
  start_year = 2000, end_year = 2018,
  north = 35, south = 8, east = 97, west = 68,
  frequency = "monthly"
)

Description

Downloads and filters HadEX3 ETCCDI climate extremes data to a geographic region defined by a GeoJSON polygon.

Usage

HadEX3Geojson(...)

hadex3_geojson(
  index,
  start_year,
  end_year,
  geojson_file,
  frequency = "annual",
  baseline = "61-90",
  output_dir = tempdir(),
  use_cache = TRUE
)

Arguments

Value

data.frame with columns: year (+ month for monthly), latitude, longitude, value, index.

Examples

region <- system.file("extdata", "region.geojson", package = "varunayan")
data <- hadex3_geojson(
  index = "TXx",
  start_year = 1981, end_year = 2010,
  geojson_file = region
)

Description

US National Weather Service heat index: Steadman's simple formula, replaced by the Rothfusz (1990) regression with its low- and high-humidity adjustments once the simple value averaged with temperature reaches 80F.

Usage

heat_index(temp_c, rh)

Arguments

Value

Heat index in Celsius

References

Rothfusz, L.P. (1990). The Heat Index Equation. NWS Southern Region Technical Attachment, SR/SSD 90-23. https://www.weather.gov/media/ffc/ta_htindx.PDF

Examples

heat_index(35, 70)

Description

Calculate heat index from dewpoint

Usage

heat_index_from_dewpoint(temp_c, dewpoint_c)

Arguments

Value

Heat index in Celsius

Examples

heat_index_from_dewpoint(35, 25)

Description

Classify heat stress risk based on heat index using NWS categories.

Usage

heat_index_risk_category(hi)

Arguments

Value

A factor of risk categories, the same length as the input.

Examples

heat_index_risk_category(c(27, 33, 40, 46, 55))

Description

heat stress index calculations

Description

Flags the days of a daily maximum temperature series that fall in a heatwave, under one of three definitions:

• "imd": India Meteorological Department. A day qualifies when Tmax is at least 40 C (plains), 37 C (coastal) or 30 C (hilly) and departs at least 4.5 C from the calendar-day normal, or when Tmax is at least 45 C. Severe: departure above 6.4 C with Tmax at least 40 C (plains, coastal) or 30 C (hilly), or Tmax of at least 47 C. A heatwave needs min_duration (2) consecutive qualifying days. IMD also requires 2 stations in a meteorological sub-division; each series here is judged on its own.

• "percentile": Tmax above the calendar-day percentile of the baseline years (5-day window) for at least min_duration (3) days, as in Rohini et al. (2016) for India.

• "ehf": days covered by a three-day period with positive excess_heat_factor(); severe when EHF reaches EHF85.

Usage

heatwave_days(
  date,
  tmax,
  tmin = NULL,
  method = c("imd", "percentile", "ehf"),
  baseline = c(1991, 2020),
  terrain = c("plains", "coastal", "hilly"),
  percentile = 0.9,
  min_duration = NULL,
  window = 2L
)

Arguments

Details

The calendar-day normal is the baseline mean over a 2 * window + 1 day window. Percentiles use stats::quantile() type 8 without the in-base bootstrap of the ETCCDI indices.

Value

A data.frame with date, day (in a heatwave), severe, spell_start and spell_length (on the first day of each heatwave).

References

India Meteorological Department. Heat wave and warm night definitions. https://mausam.imd.gov.in/pdfs/heatcolduser/Definition.pdf

Rohini, P., Rajeevan, M. & Srivastava, A.K. (2016). On the Variability and Increasing Trends of Heat Waves over India. Scientific Reports, 6, 26153. doi:10.1038/srep26153

Examples

d <- seq(as.Date("2001-01-01"), as.Date("2003-12-31"), by = "day")
doy <- as.POSIXlt(d)$yday
tmax <- 33 + 8 * sin(2 * pi * (doy - 80) / 365)
tmax[d >= as.Date("2003-05-10") & d <= as.Date("2003-05-13")] <- 46
hw <- heatwave_days(d, tmax, baseline = c(2001, 2002))
subset(hw, day)

Description

Calculate humidex (Canadian heat index)

Usage

humidex(temp_c, dewpoint_c)

Arguments

Value

Humidex in Celsius

References

Masterson, J. & Richardson, F.A. (1979). Humidex, A Method of Quantifying Human Discomfort Due to Excessive Heat and Humidity. Environment Canada, Atmospheric Environment Service.

Environment and Climate Change Canada. Glossary: Humidex. https://climate.weather.gc.ca/glossary_e.html

Examples

humidex(30, 22)

Description

Unlike imd_temperature_geojson(), which returns grid points clipped to the GeoJSON boundary, this returns one row per feature (e.g. per state) per time period, with the region-mean temperature.

Usage

imd_temperature_by_region(
  request_id,
  start_year,
  end_year,
  geojson_file,
  feature_col = NULL,
  var_type = "tmean",
  frequency = "monthly",
  use_cache = TRUE
)

Arguments

Value

A data.frame: region, year, month (if monthly), temperature.

Examples

## Not run: 
temp <- imd_temperature_by_region(
  request_id = "india_states",
  start_year = 2009, end_year = 2024,
  geojson_file = "india_states.geojson",
  feature_col = "state_name", var_type = "tmean", frequency = "monthly"
)

## End(Not run)

Description

Classifies locations as "hilly", "coastal" or "plains" for the IMD heatwave definition in heatwave_days(). IMD sets the Tmax floor by terrain but does not define it. A location is hilly when it lies in Jammu and Kashmir, Ladakh, Himachal Pradesh or Uttarakhand, whose sub-divisions IMD treats as hilly down to the Jammu plains, or when its india_elevation() reaches hill_elevation, the 1200 m boundary of the mid-hill regions by default. Otherwise it is coastal when land and open sea both lie within about 9 km.

Usage

imd_terrain(latitude, longitude, hill_elevation = 1200, cell_size = NULL)

Arguments

Details

For gridded data set cell_size to classify whole cells from their Indian land: a cell is hilly when most of it lies in those states or its median elevation reaches hill_elevation, and coastal when any of it is.

Value

A character vector of "hilly", "coastal" or "plains", NA outside the grid or over sea.

References

NOAA National Centers for Environmental Information (2022). ETOPO 2022 15 Arc-Second Global Relief Model. doi:10.25921/fd45-gt74

Ministry of Panchayati Raj. Local Government Directory district boundaries, via https://bharatviz.org.

See Also

heatwave_days(), exposure_indicators()

Examples

# Shimla, Jammu, Delhi, Chennai
imd_terrain(c(31.10, 32.73, 28.61, 13.08), c(77.17, 74.86, 77.21, 80.27))
# IMD 1 degree cells holding Jammu and Rajkot
imd_terrain(c(32.5, 22.5), c(74.5, 70.5), cell_size = 1)

Description

Downloads IMD gridded daily maximum and minimum temperature (1 degree) for the requested years and the baseline, then computes exposure_indicators() for each grid cell.

Usage

IMDExposureBbox(...)

imd_exposure_bbox(
  start_year,
  end_year,
  north,
  south,
  east,
  west,
  baseline = c(1991, 2020),
  ...,
  output_dir = tempdir(),
  use_cache = TRUE
)

Arguments

Value

The data.frame of exposure_indicators() for start_year to end_year, one row per grid cell (latitude, longitude) and period.

Examples

jaipur <- imd_exposure_bbox(2022, 2024,
  north = 28, south = 26,
  east = 77, west = 75, months = 3:6
)

Description

Downloads IMD gridded rainfall data and filters it to a specified bounding box.

Usage

IMDRainfallBbox(...)

imd_rainfall_bbox(
  request_id,
  start_year,
  end_year,
  north,
  south,
  east,
  west,
  resolution = 0.25,
  frequency = "daily",
  save_raw = FALSE,
  output_dir = tempdir(),
  use_cache = TRUE
)

Arguments

Value

A data.frame with columns date, latitude, longitude and rainfall (mm), restricted to the requested region and aggregated to frequency.

Examples

data <- imd_rainfall_bbox(
  request_id = "maharashtra_rain",
  start_year = 2023,
  end_year = 2024,
  north = 22, south = 16,
  east = 80, west = 73,
  resolution = 0.25,
  frequency = "monthly"
)

Description

Download and process IMD rainfall data for a GeoJSON region

Usage

IMDRainfallGeojson(...)

imd_rainfall_geojson(
  request_id,
  start_year,
  end_year,
  geojson_file,
  resolution = 0.25,
  frequency = "daily",
  save_raw = FALSE,
  output_dir = tempdir(),
  use_cache = TRUE
)

Arguments

Value

A data.frame with columns date, latitude, longitude and rainfall (mm), restricted to the requested region and aggregated to frequency.

Examples

region <- system.file("extdata", "region.geojson", package = "varunayan")
data <- imd_rainfall_geojson(
  request_id = "mh_rain", start_year = 2023, end_year = 2023,
  geojson_file = region, frequency = "monthly"
)

Description

Extracts the daily rainfall series for the IMD grid cell nearest to a (lat, lon). Reads only that one cell off disk per year, so it is the cheapest way to get a long series for a location.

Usage

IMDRainfallPoint(...)

imd_rainfall_point(
  request_id,
  start_year,
  end_year,
  latitude,
  longitude,
  resolution = 0.25,
  frequency = "daily",
  save_raw = FALSE,
  output_dir = tempdir(),
  use_cache = TRUE
)

Arguments

Value

data.frame with the nearest cell's rainfall series.

Examples

## Not run: 
powai <- imd_rainfall_point("powai", 1901, 2024, 19.1277, 72.9047)

## End(Not run)

Description

Retrieves the India Meteorological Department (IMD) city-weather station list and, optionally, each station's latitude/longitude. IMD's legacy endpoints expose only station names; its responsive site serves a per-station JSON record (api/fetchCity_static.php) that includes lat/lon, which this function pairs with the station list. The returned coordinates can be fed directly to era5ify_point() or used to build maps.

Usage

IMDStations(...)

imd_stations(with_coordinates = TRUE, cores = 4)

Arguments

Value

A data.frame with columns station_id, name, and — when with_coordinates = TRUE — latitude, longitude (NA where IMD has no coordinate for a station).

Examples

## Not run: 
stations <- imd_stations()
shimla <- stations[grepl("Shimla", stations$name), ]

## End(Not run)

Description

Download and process IMD temperature data for a bounding box

Usage

IMDTemperatureBbox(...)

imd_temperature_bbox(
  request_id,
  start_year,
  end_year,
  north,
  south,
  east,
  west,
  var_type = "tmax",
  frequency = "daily",
  save_raw = FALSE,
  output_dir = tempdir(),
  use_cache = TRUE
)

Arguments

Value

A data.frame with columns date, latitude, longitude and temperature (degrees Celsius), restricted to the requested region and aggregated to frequency.

Examples

data <- imd_temperature_bbox(
  request_id = "delhi_tmax",
  start_year = 2023,
  end_year = 2024,
  north = 29, south = 28,
  east = 78, west = 76,
  var_type = "tmax"
)

Description

Download and process IMD temperature data for a GeoJSON region

Usage

IMDTemperatureGeojson(...)

imd_temperature_geojson(
  request_id,
  start_year,
  end_year,
  geojson_file,
  var_type = "tmax",
  frequency = "daily",
  save_raw = FALSE,
  output_dir = tempdir(),
  use_cache = TRUE
)

Arguments

Value

A data.frame with columns date, latitude, longitude and temperature (degrees Celsius), restricted to the requested region and aggregated to frequency.

Examples

region <- system.file("extdata", "region.geojson", package = "varunayan")
data <- imd_temperature_geojson(
  request_id = "mh_tmax", start_year = 2023, end_year = 2023,
  geojson_file = region, var_type = "tmax", frequency = "monthly"
)

Description

Looks up surface elevation from a 5 arc-minute (about 9 km) grid bundled with the package, covering 6-38 N and 66-98 E. Each value is the median land elevation of the 5 arc-minute cell holding the location, built by data-raw/imd_terrain.R from ETOPO 2022 at 60 arc-seconds.

Usage

india_elevation(latitude, longitude)

Arguments

Value

Elevation in metres, NA over open sea or outside the grid.

References

NOAA National Centers for Environmental Information (2022). ETOPO 2022 15 Arc-Second Global Relief Model. doi:10.25921/fd45-gt74

See Also

imd_terrain()

Examples

# Shimla, Delhi, Leh
india_elevation(c(31.10, 28.61, 34.16), c(77.17, 77.21, 77.58))

Description

Check if a variable should use maximum

Usage

is_max_var(var_name)

Arguments

Value

Logical indicating if variable should use max

Examples

is_max_var("2m_temperature")

Description

Check if a variable should use minimum

Usage

is_min_var(var_name)

Arguments

Value

Logical indicating if variable should use min

Examples

is_min_var("2m_temperature")

Description

Check if a variable is a rate variable

Usage

is_rate_var(var_name)

Arguments

Value

Logical indicating if variable is a rate

Examples

is_rate_var("2m_temperature")

Description

Check if a variable should be summed

Usage

is_sum_var(var_name)

Arguments

Value

Logical indicating if variable should be summed

Examples

is_sum_var("total_precipitation")

Description

Check if data is valid GeoJSON

Usage

is_valid_geojson(data)

Arguments

Value

Logical indicating if data is valid GeoJSON

Description

List cached files

Usage

list_cache(source = NULL)

Arguments

Value

A data.frame with columns file, source, size_mb and modified, one row per cached file; zero rows if the cache is empty.

Examples

list_cache()

Description

List available IMD datasets

Usage

list_imd_datasets()

Value

data.frame with available IMD datasets and their characteristics

Examples

list_imd_datasets()

Description

List all available variables for a dataset type

Usage

ListAvailableVariables(...)

list_available_variables(dataset_type = "all")

Arguments

Value

Character vector of variable names

Examples

head(list_available_variables("single"))

Description

Maps CRU TS variable codes to common names, units, and ERA5 equivalents.

Usage

ListCRUTSVariables(...)

list_cru_ts_variables(...)

Arguments

Value

data.frame with columns: variable, name, description, unit, era5_equivalent, hadex3_equivalent.

Examples

list_cru_ts_variables()

Description

Returns a data.frame describing all ETCCDI climate extremes indices available in the HadEX3 dataset, including their temporal availability and physical interpretation.

Usage

ListHadEX3Indices(...)

list_hadex3_indices(frequency = "all")

Arguments

Value

data.frame with columns: index, category, description, unit, annual, monthly.

Examples

list_hadex3_indices()
list_hadex3_indices(frequency = "monthly")

Description

Variables that should use maximum aggregation

Usage

max_vars

Value

A character vector of variable names.

Examples

head(max_vars)

Description

Estimates mean radiant temperature (Tmrt) from meteorological variables. Uses simplified approach when full radiation data unavailable.

Usage

mean_radiant_temperature(temp_c, solar_radiation = NULL, wind_speed = NULL)

Arguments

Value

Mean radiant temperature in Celsius

Examples

mean_radiant_temperature(30, solar_radiation = 800, wind_speed = 2)

Description

Variables that should use minimum aggregation

Usage

min_vars

Value

A character vector of variable names.

Examples

head(min_vars)

Description

NDBI = (SWIR - NIR) / (SWIR + NIR) from surface reflectance, using the 1.55-1.75 um shortwave infrared band, e.g. Landsat 8-9 bands 6 and 5, Sentinel-2 bands 11 and 8, or Landsat 5 TM bands 5 and 4 as in Zha et al. (2003). Positive values indicate built-up or bare surfaces. Works on numeric vectors and on terra::SpatRaster layers.

Usage

ndbi(swir, nir)

Arguments

Value

NDBI in the range -1 to 1, the same shape as the inputs.

References

Zha, Y., Gao, J. & Ni, S. (2003). Use of normalized difference built-up index in automatically mapping urban areas from TM imagery. International Journal of Remote Sensing, 24(3), 583-594. doi:10.1080/01431160304987

See Also

ndvi()

Examples

ndbi(swir = 0.30, nir = 0.22)

Description

NDVI = (NIR - Red) / (NIR + Red) from surface reflectance, e.g. Landsat 8-9 bands 5 and 4, Sentinel-2 bands 8 and 4, or MODIS bands 2 and 1. Works on numeric vectors and on terra::SpatRaster layers.

Usage

ndvi(nir, red)

Arguments

Value

NDVI in the range -1 to 1, the same shape as the inputs.

References

Tucker, C.J. (1979). Red and photographic infrared linear combinations for monitoring vegetation. Remote Sensing of Environment, 8(2), 127-150. doi:10.1016/0034-4257(79)90013-0

See Also

ndbi()

Examples

ndvi(nir = 0.45, red = 0.08)

Description

Parse date string flexibly

Usage

parse_date_flexible(date_string)

Arguments

Value

Date object

Description

Copies sample IMD data files to cache for offline testing.

Usage

PopulateSampleCache(...)

populate_sample_cache(force = FALSE)

Arguments

Value

Invisibly, a named list of paths to the cached sample files, or NULL if no sample directory exists.

Examples

populate_sample_cache()

Description

Print timing summary

Usage

print_timing_summary()

Value

The timing data frame from get_timings(), invisibly (NULL if empty).

Examples

print_timing_summary()

Description

Reads and combines multiple IMD data files.

Usage

process_imd_files(
  file_paths,
  var_type,
  resolution = NULL,
  years = NULL,
  bbox = NULL
)

Arguments

Value

A data.frame with columns date, latitude, longitude and the value column (rainfall or temperature), combining all files.

Examples

files <- download_imd_temperature(2023, 2024, var_type = "tmax")
data <- process_imd_files(files, "tmax", years = c(2023, 2024))

Description

Uses ncdf4 directly for fast reading, with stars as fallback.

Usage

process_netcdf_to_dataframe(netcdf_file)

Arguments

Value

data.frame with processed climate data

Description

Rate variables that should be averaged

Usage

rate_vars

Value

A character vector of variable names.

Examples

head(rate_vars)

Description

Read CDS API credentials from ~/.cdsapirc file

Usage

read_cdsapirc(file_path = "~/.cdsapirc")

Arguments

Value

A named list of the fields in the file (typically url and key), or NULL if the file does not exist or cannot be parsed.

Examples

f <- tempfile()
writeLines(c("url: https://cds.climate.copernicus.eu/api", "key: abc-123"), f)
read_cdsapirc(f)

Description

Reads IMD NetCDF rainfall data and converts to data.frame.

Usage

read_imd_rainfall(file_path, resolution, year, bbox = NULL)

Arguments

Value

data.frame with columns: date, latitude, longitude, rainfall

Examples

f <- download_imd_rainfall(2023, 2023, resolution = 0.25)
rain_data <- read_imd_rainfall(f, 0.25, 2023)

Description

Reads IMD binary temperature data (max or min) and converts to data.frame.

Usage

read_imd_temperature(file_path, var_type, year)

Arguments

Value

data.frame with columns: date, latitude, longitude, temperature

Examples

f <- download_imd_temperature(2023, 2023, var_type = "tmax")
tmax_data <- read_imd_temperature(f, "tmax", 2023)

Description

Uses the Magnus-Tetens approximation to calculate relative humidity from air temperature and dewpoint temperature.

Usage

relative_humidity_from_dewpoint(temp_c, dewpoint_c)

Arguments

Value

Relative humidity as percentage (0-100)

Examples

relative_humidity_from_dewpoint(25, 18)

Description

Search for ERA5 variables by keyword

Usage

SearchVariable(...)

search_variable(keyword, dataset_type = "all", exact_match = FALSE)

Arguments

Value

A data.frame with columns variable_name, description, units, dataset_type and category, one row per matching variable.

Examples

# Search for temperature variables
temp_vars <- search_variable("temperature")

# Search in pressure level data only
pressure_temp <- search_variable("temperature", dataset_type = "pressure")

Description

Sets up Copernicus Climate Data Store (CDS) credentials for ERA5 downloads. Credentials are checked in the following order:

1. Directly provided key argument

2. CDS_API_KEY environment variable

3. ⁠~/.cdsapirc⁠ file

Usage

SetupCdsCredentials(...)

setup_cds_credentials(key = NULL)

Arguments

Value

Invisibly, TRUE once the key has been registered with 'ecmwfr'. Errors if no key can be found.

Examples

## Not run: 
setup_cds_credentials(key = "your-cds-api-key-here")
Sys.setenv(CDS_API_KEY = "your-cds-api-key-here")
setup_cds_credentials()

## End(Not run)

Description

Show cache contents and statistics

Usage

ShowCacheInfo(...)

show_cache_info()

Arguments

Value

Invisibly, a data.frame with columns name, size_mb and mtime describing cached files, or NULL if the cache is empty. Called mainly for its side effect of printing a summary as messages.

Examples

show_cache_info()

Description

Accumulation variables (precipitation, radiation) that use sum for temporal aggregation.

Usage

sum_vars

Value

A character vector of variable names.

Examples

head(sum_vars)

Description

Time an operation and log the duration

Usage

time_operation(expr, label, verbose = TRUE)

Arguments

Value

The value of expr. The elapsed time is recorded and can be retrieved with get_timings().

Examples

x <- time_operation(sum(1:10), "sum")
get_timings()

Description

Calculates UTCI using the polynomial approximation from Bröde et al. (2012), based on a multi-node model of human thermoregulation.

Usage

utci(temp_c, wind_speed, dewpoint_c, tmrt = NULL)

Arguments

Value

UTCI in Celsius

References

Bröde, P., et al. (2012). Deriving the operational procedure for the Universal Thermal Climate Index (UTCI). International Journal of Biometeorology, 56(3), 481-494. doi:10.1007/s00484-011-0454-1

Examples

utci(30, wind_speed = 2, dewpoint_c = 20)
utci(35, wind_speed = 1, dewpoint_c = 25, tmrt = 45)

Description

Classify thermal stress based on UTCI values.

Usage

utci_category(utci_val)

Arguments

Value

A factor of thermal stress categories, the same length as the input.

Examples

utci_category(c(-20, 0, 20, 30, 40))

Description

Calculates UTCI using the sparse regression approximation with Legendre polynomials from Roman et al. (2025). This is a more accurate approximation than the original Bröde et al. (2012) polynomial, with fewer terms and better numerical stability.

Usage

utci_sparse(temp_c, tmrt, wind_speed, rh)

Arguments

Value

UTCI in Celsius

References

Roman, S., Todorovski, L., Dzeroski, S., & Skok, G. (2025). Approximating the universal thermal climate index using sparse regression with orthogonal polynomials. doi:10.48550/arXiv.2508.11307

Roman, S. (2025). Code for Approximating the universal thermal climate index (UTCI) using sparse regression with orthogonal polynomials. Zenodo. doi:10.5281/zenodo.17465548

Examples

utci_sparse(30, tmrt = 40, wind_speed = 2, rh = 60)
utci_sparse(35, tmrt = 35, wind_speed = 1, rh = 80)

Description

Validate bounding box coordinates

Usage

validate_bbox(north, south, east, west)

Arguments