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

Assigns each grid cell to a polygon, then aggregates the values of the cells in each polygon. The spatial match uses only the distinct cells. Thus, a daily series with many dates does not make the match slower.

Usage

aggregate_to_polygons(
  data,
  polygons,
  value_col,
  method = c("nearest_centroid", "point_in_polygon"),
  polygon_id_cols = NULL,
  agg_fun = function(x) mean(x, na.rm = TRUE),
  by = NULL,
  fill_empty = FALSE
)

Arguments

Value

Data frame with the polygon identifiers, the by columns and the aggregated values. It has one row for each polygon and each value of by. A polygon with no cell has NA.

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

This function calculates 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

Sort variables by aggregation method

Usage

categorize_variables(var_names)

Arguments

Value

Named list of the variables, sorted by aggregation method

Examples

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

Description

Calculate the 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

Make sure that the system is ready 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

Delete temporary files that match a pattern

Usage

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

Arguments

Value

Number of files removed

Description

Clear all time 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 NetCDF files into one data.frame

Usage

combine_netcdf_files(netcdf_files, verbose = FALSE)

Arguments

Value

data.frame with combined data from all files

Description

Compare two or more 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

Data in GeoJSON format

Description

Create GeoJSON from bounding box coordinates

Usage

create_geojson_from_bbox(north, south, east, west)

Arguments

Value

GeoJSON object that shows 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

The default chunk size is compute_optimal_chunk_size(frequency). This size changes with the CDS field limit (hourly: 24 fields/day, daily: 1/day, monthly: 12/year). Thus, 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, with one pair for each chunk

Description

Downloads CRU TS v4.07 monthly gridded climate data and filters the data to a geographic bounding box. The data is for the global land areas at a resolution of 0.5 degrees, for 1901-2022.

Usage

CRUTSBbox(...)

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

Arguments

Value

A data.frame with the 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 CRU TS v4.07 monthly gridded climate data and filters the data to a geographic region. A GeoJSON polygon defines the region.

Usage

CRUTSGeojson(...)

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

Arguments

Value

A data.frame with the 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 with 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 with 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 the specified resolution.

Usage

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

Arguments

Value

Character vector of the paths to the downloaded files.

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 (maximum or minimum) from IMD. Temperature data is available only at 1.0 degree resolution.

Usage

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

Arguments

Value

Character vector of the paths to the downloaded files.

Examples

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

Description

Create the output directory if it does not exist

Usage

ensure_output_dir(output_dir)

Arguments

Value

Character string. The path to the directory that the function made or found

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

Aggregation does not apply to these coordinate and metadata columns.

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 a specified point location (nearest neighbor)

Usage

extract_point_data(netcdf_file, target_lat, target_lon)

Arguments

Value

data.frame with data for the nearest point

Description

This function does a test of only the unique (lat, lon) coordinates against the polygon. Then it joins the result to the full dataset with a 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 the character format necessary for the 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 the grid specifications for an IMD dataset.

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 the dataset of pressure-level variables

Usage

get_pressure_level_variables()

Value

List that contains the 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 the dataset of single-level variables

Usage

get_single_level_variables()

Value

List that contains the single-level variable categories

Description

Get time values for a frequency

Usage

get_time_values(frequency)

Arguments

Value

Character vector of time strings

Description

Get all recorded time measurements

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 the standard pressure levels that are 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

Downloads ERA5 temperature data for a country and aggregates the data. The function finds the country boundary and downloads monthly data with era5ify_geojson(). It returns country-level averages for each year and month, with area weights (cosine of latitude).

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 the columns year, month, and one column for each requested variable (for example, temperature_mean, temperature_max, temperature_min). The 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 the USA
get_era5_country_temperature("USA", "2023-01-01", "2023-12-31",
  variables = c("mean", "max")
)

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

Description

This function downloads 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

This function downloads ERA5 temperature, dewpoint, and wind data for a region. Then it calculates the 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. If solar_load=TRUE, the data.frame also contains 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

This function downloads temperature and dewpoint data. Then it calculates the 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

This function downloads temperature and dewpoint data. Then it calculates RH and the 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

This function downloads the 10m wind components. Then it calculates the 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

This function downloads ERA5 heat stress indices and aggregates them to the specified 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

Downloads HadEX3 data on ETCCDI climate extremes and filters the data to a geographic bounding box. The data is for 1901-2018 at a resolution of 1.25 x 1.875 degrees.

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

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

Examples

# Annual maximum of the 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 HadEX3 data on ETCCDI climate extremes and filters the data to a geographic region. A GeoJSON polygon defines the region.

Usage

HadEX3Geojson(...)

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

Arguments

Value

A data.frame with the columns: year (and month for monthly data), 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

This function puts heat index values into heat stress risk categories. It uses the NWS categories.

Usage

heat_index_risk_category(hi)

Arguments

Value

Factor with the risk category

Examples

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

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

imd_temperature_geojson() returns the grid points in the GeoJSON boundary. This function is different. It returns one row for each feature (for example, each state) and each time period. Each row contains the mean temperature of the region.

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 with the columns region, year, month (only for monthly data), and temperature.

Examples

temp <- tryCatch(
  imd_temperature_by_region(
    request_id = "demo_region",
    start_year = 2023, end_year = 2023,
    geojson_file = system.file("extdata", "region.geojson", package = "varunayan"),
    var_type = "tmax", frequency = "monthly", use_cache = FALSE
  ),
  error = function(e) message("IMD server unavailable: ", conditionMessage(e))
)

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 keeps only the data in the 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 that is nearest to a (lat, lon) point. For each year, the function reads only that one cell from the disk. Thus, this function is the method with the lowest cost to get a long series for one 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 rainfall series of the nearest cell.

Examples

powai <- tryCatch(
  imd_rainfall_point("powai", 2023, 2023, 19.1277, 72.9047,
    resolution = 1, use_cache = FALSE
  ),
  error = function(e) message("IMD server unavailable: ", conditionMessage(e))
)

Description

Gets the India Meteorological Department (IMD) city-weather station list. As an option, it also gets the latitude and longitude of each station. The legacy IMD endpoints give only the station names. The responsive IMD site gives a JSON record for each station (api/fetchCity_static.php). This record contains lat and lon. The function adds these values to the station list. You can use the returned coordinates directly as input to era5ify_point(). You can also use them to make maps.

Usage

IMDStations(...)

imd_stations(
  with_coordinates = TRUE,
  cores = if (.Platform$OS.type == "windows") 1L else 2L
)

Arguments

Value

A data.frame with the columns station_id and name. If with_coordinates = TRUE, the data frame also has the columns latitude and longitude. The value is NA if IMD has no coordinate for a station.

Examples

stations <- tryCatch(
  imd_stations(with_coordinates = FALSE),
  error = function(e) message("IMD server unavailable: ", conditionMessage(e))
)

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

Find if a variable uses maximum aggregation

Usage

is_max_var(var_name)

Arguments

Value

Logical. TRUE if the variable uses maximum aggregation

Examples

is_max_var("2m_temperature")

Description

Find if a variable uses minimum aggregation

Usage

is_min_var(var_name)

Arguments

Value

Logical. TRUE if the variable uses minimum aggregation

Examples

is_min_var("2m_temperature")

Description

Find if a variable is a rate variable

Usage

is_rate_var(var_name)

Arguments

Value

Logical. TRUE if the variable is a rate

Examples

is_rate_var("2m_temperature")

Description

Find if a variable uses sum aggregation

Usage

is_sum_var(var_name)

Arguments

Value

Logical. TRUE if the variable uses sum aggregation

Examples

is_sum_var("total_precipitation")

Description

Find if data is valid GeoJSON

Usage

is_valid_geojson(data)

Arguments

Value

Logical. TRUE if the 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 the available IMD datasets and their properties.

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

Gives the common names, units, and ERA5 equivalents of the CRU TS variable codes.

Usage

ListCRUTSVariables(...)

list_cru_ts_variables(...)

Arguments

Value

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

Examples

list_cru_ts_variables()

Description

Returns a data.frame that describes all the ETCCDI indices of climate extremes in the HadEX3 dataset. The data.frame shows the temporal availability and the physical quantity of each index.

Usage

ListHadEX3Indices(...)

list_hadex3_indices(frequency = "all")

Arguments

Value

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

Examples

list_hadex3_indices()
list_hadex3_indices(frequency = "monthly")

Description

Variables for maximum aggregation

Usage

max_vars

Value

A character vector of variable names.

Examples

head(max_vars)

Description

This function estimates the mean radiant temperature (Tmrt) from meteorological variables. If full radiation data is not available, the function uses a simplified method.

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 for 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 a date string in different formats

Usage

parse_date_flexible(date_string)

Arguments

Value

Date object

Description

Copies sample IMD data files to the cache for offline tests.

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 a summary of the time data

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

This function uses ncdf4 to read the file quickly. If ncdf4 fails, it uses stars.

Usage

process_netcdf_to_dataframe(netcdf_file)

Arguments

Value

data.frame with processed climate data

Description

Rate variables to average

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 the data to a 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 (maximum or minimum) and converts the data to a 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

This function uses the Magnus-Tetens approximation to calculate the relative humidity from the air temperature and the dewpoint temperature.

Usage

relative_humidity_from_dewpoint(temp_c, dewpoint_c)

Arguments

Value

Relative humidity as a 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 only in pressure level data
pressure_temp <- search_variable("temperature", dataset_type = "pressure")

Description

This function configures the Copernicus Climate Data Store (CDS) credentials for ERA5 downloads. The function examines the credentials in this order:

1. The key argument that you give directly

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

setup_cds_credentials()

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). Temporal aggregation uses the sum for these variables.

Usage

sum_vars

Value

A character vector of variable names.

Examples

head(sum_vars)

Description

Measure the time of an operation and record 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

This function uses the polynomial approximation of Bröde et al. (2012) to calculate UTCI. The approximation uses 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

This function puts UTCI values into thermal stress categories.

Usage

utci_category(utci_val)

Arguments

Value

Factor with the thermal stress category

Examples

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

Description

This function uses the sparse regression approximation of Roman et al. (2025) to calculate UTCI. This approximation uses Legendre polynomials. It is more accurate than the original polynomial of Bröde et al. (2012). It has 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)