climatekit: Unified Climate Indices for Temperature, Precipitation, and Drought

Description

Compute 35+ standard climate indices from daily weather observations. Includes temperature indices (frost days, ice days, growing degree days), precipitation indices (dry spells, heavy precipitation, intensity), drought indices (Standardized Precipitation Index, Standardized Precipitation-Evapotranspiration Index), agroclimatic indices (Huglin, Winkler, Branas), and comfort indices (wind chill, heat index, humidex, fire danger). All functions accept vectors of observations with dates and return tidy data frames with metadata. Implements the 'ET-SCI' Expert Team on Sector-specific Climate Indices definitions where applicable. No external API calls; pairs with data packages such as 'readnoaa' for acquisition.

Author(s)

Maintainer: Charles Coverdale charlesfcoverdale@gmail.com

See Also

Useful links:

• https://github.com/charlescoverdale/climatekit

• Report bugs at https://github.com/charlescoverdale/climatekit/issues

List All Available Climate Indices

Description

Returns a data frame listing every index that climatekit can compute, along with its category, unit, and a short description.

Usage

ck_available()

Value

A data frame with columns index, category, unit, and description.

Examples

ck_available()

Branas Hydrothermal Index

Description

The Branas index combines temperature and precipitation during the growing season to estimate disease pressure (especially downy mildew) in vineyards. It is the sum of the product of monthly mean temperature and monthly precipitation for April-August.

Usage

ck_branas(precip, tavg, dates)

Arguments

Value

A data frame with columns period, value, index, and unit.

References

Branas, J., Bernon, G., & Levadoux, L. (1946). Elements de viticulture generale.

Examples

dates <- seq(as.Date("2024-04-01"), as.Date("2024-08-31"), by = "day")
set.seed(42)
tavg <- rnorm(length(dates), mean = 12, sd = 3)
precip <- rgamma(length(dates), shape = 0.5, rate = 0.2)
ck_branas(precip, tavg, dates)

Compute a Climate Index by Name

Description

A generic dispatcher that calls the appropriate ⁠ck_*⁠ function based on a string index name. Useful for programmatic workflows where the index is selected at runtime.

Usage

ck_compute(data, index, ...)

Arguments

Value

A data frame as returned by the underlying ⁠ck_*⁠ function.

Examples

d <- data.frame(
  dates = as.Date("2024-01-01") + 0:9,
  tmin = c(-2, 3, -1, 5, -3, 0, 2, -4, 1, -1)
)
ck_compute(d, "frost_days")

Convert Temperature Units

Description

Convert between Celsius, Fahrenheit, and Kelvin.

Usage

ck_convert_temp(x, from, to)

Arguments

Value

Numeric vector of converted temperatures.

Examples

ck_convert_temp(c(0, 100), from = "C", to = "F")
ck_convert_temp(32, from = "F", to = "C")

Cooling Degree Days

Description

Sum of (Tavg - base) for all days where daily average temperature is above the base temperature (default 18 degrees C).

Usage

ck_cooling_degree_days(tavg, dates, base = 18, period = "annual")

Arguments

Value

A data frame with columns period, value, index, and unit.

Examples

dates <- as.Date("2024-07-01") + 0:9
tavg <- c(25, 30, 22, 20, 28, 19, 32, 17, 35, 27)
ck_cooling_degree_days(tavg, dates)

Diurnal Temperature Range

Description

Mean daily temperature range (Tmax - Tmin) per period.

Usage

ck_diurnal_range(tmin, tmax, dates, period = "annual")

Arguments

Value

A data frame with columns period, value, index, and unit.

Examples

dates <- as.Date("2024-01-01") + 0:9
tmin <- c(-2, 3, -1, 5, -3, 0, 2, -4, 1, -1)
tmax <- c(5, 10, 6, 12, 4, 8, 9, 3, 7, 6)
ck_diurnal_range(tmin, tmax, dates)

Maximum Consecutive Dry Days

Description

Maximum number of consecutive days with precipitation below a threshold.

Usage

ck_dry_days(precip, dates, threshold = 1, period = "annual")

Arguments

Value

A data frame with columns period, value, index, and unit.

Examples

dates <- as.Date("2024-01-01") + 0:9
precip <- c(0, 0, 5, 0, 0, 0, 2, 0, 0, 0)
ck_dry_days(precip, dates)

Fire Danger Index (Simplified)

Description

A simplified fire danger proxy based on temperature, humidity, wind speed, and recent precipitation. This is NOT the Canadian Forest Fire Weather Index (Van Wagner 1987); for the full FWI system, use the cffdrs package.

Usage

ck_fire_danger(tavg, humidity, wind_speed, precip)

Arguments

Value

A data frame with columns value, index, and unit.

Examples

ck_fire_danger(
  tavg = c(30, 25, 35),
  humidity = c(20, 40, 15),
  wind_speed = c(25, 10, 30),
  precip = c(0, 5, 0)
)

First Frost Date

Description

Date of the first autumn frost (Tmin < 0 degrees C) after July 1 in each year.

Usage

ck_first_frost(tmin, dates)

Arguments

Value

A data frame with columns period, value (day of year), date (the frost date), index, and unit.

Examples

dates <- seq(as.Date("2024-07-01"), as.Date("2024-12-31"), by = "day")
set.seed(42)
tmin <- 15 - seq_along(dates) * 0.15 + rnorm(length(dates), sd = 3)
ck_first_frost(tmin, dates)

Frost Days

Description

Count the number of days where minimum temperature is below 0 degrees C.

Usage

ck_frost_days(tmin, dates, period = "annual")

Arguments

Value

A data frame with columns period, value, index, and unit.

Examples

dates <- as.Date("2024-01-01") + 0:9
tmin <- c(-2, 3, -1, 5, -3, 0, 2, -4, 1, -1)
ck_frost_days(tmin, dates)

Growing Degree Days

Description

Sum of (Tavg - base) for all days where daily average temperature is above the base temperature (default 10 degrees C).

Usage

ck_growing_degree_days(tavg, dates, base = 10, period = "annual")

Arguments

Value

A data frame with columns period, value, index, and unit.

Examples

dates <- as.Date("2024-07-01") + 0:9
tavg <- c(15, 20, 8, 12, 25, 9, 30, 11, 22, 18)
ck_growing_degree_days(tavg, dates)

Growing Season Length

Description

Compute the growing season length following the ETCCDI definition: the number of days between the first occurrence of at least 6 consecutive days with daily mean temperature above 5 degrees C and the first span of 6 consecutive days with Tmean below 5 degrees C after July 1 (Northern Hemisphere) or January 1 (Southern Hemisphere). Calculated per year.

Usage

ck_growing_season(tavg, dates, lat = 50)

Arguments

Value

A data frame with columns period, value, index, and unit.

Examples

dates <- as.Date("2024-01-01") + 0:364
set.seed(42)
tavg <- sin(seq(0, 2 * pi, length.out = 365)) * 15 + 5
ck_growing_season(tavg, dates)

Heat Index

Description

Compute the heat index (apparent temperature) using the Rothfusz regression equation used by the US National Weather Service.

Usage

ck_heat_index(tavg, humidity)

Arguments

Value

A data frame with columns value, index, and unit.

References

Rothfusz, L. P. (1990). The heat index equation. NWS Technical Attachment SR 90-23.

Examples

ck_heat_index(tavg = c(30, 35, 40), humidity = c(60, 70, 50))

Heating Degree Days

Description

Sum of (base - Tavg) for all days where daily average temperature is below the base temperature (default 18 degrees C).

Usage

ck_heating_degree_days(tavg, dates, base = 18, period = "annual")

Arguments

Value

A data frame with columns period, value, index, and unit.

Examples

dates <- as.Date("2024-01-01") + 0:9
tavg <- c(5, 10, 15, 20, 8, 12, 18, 3, 25, 7)
ck_heating_degree_days(tavg, dates)

Heavy Precipitation Days

Description

Count of days with precipitation at or above a threshold (default 10 mm).

Usage

ck_heavy_precip(precip, dates, threshold = 10, period = "annual")

Arguments

Value

A data frame with columns period, value, index, and unit.

Examples

dates <- as.Date("2024-01-01") + 0:9
precip <- c(0, 5, 12, 0, 15, 2, 0, 11, 4, 0)
ck_heavy_precip(precip, dates)

Huglin Heliothermal Index

Description

The Huglin index is used in viticulture to characterise the thermal potential of a region for grape growing. It is computed over the growing season (April 1 to September 30 in the Northern Hemisphere; October 1 to March 31 in the Southern Hemisphere).

Usage

ck_huglin(tmin, tmax, dates, lat)

Arguments

Value

A data frame with columns period, value, index, and unit.

References

Huglin, P. (1978). Nouveau mode d'evaluation des possibilites heliothermiques d'un milieu viticole. Comptes Rendus de l'Academie d'Agriculture de France, 64, 1117-1126.

Examples

dates <- seq(as.Date("2024-04-01"), as.Date("2024-09-30"), by = "day")
set.seed(42)
tmin <- rnorm(length(dates), mean = 12, sd = 3)
tmax <- tmin + runif(length(dates), 8, 15)
ck_huglin(tmin, tmax, dates, lat = 45)

Humidex

Description

Compute the Canadian humidex from temperature and dewpoint.

Usage

ck_humidex(tavg, dewpoint)

Arguments

Value

A data frame with columns value, index, and unit.

References

Masterson, J., & Richardson, F. A. (1979). Humidex: A method of quantifying human discomfort due to excessive heat and humidity. Environment Canada.

Examples

ck_humidex(tavg = c(30, 35), dewpoint = c(20, 25))

Ice Days

Description

Count the number of days where maximum temperature is below 0 degrees C.

Usage

ck_ice_days(tmax, dates, period = "annual")

Arguments

Value

A data frame with columns period, value, index, and unit.

Examples

dates <- as.Date("2024-01-01") + 0:9
tmax <- c(-2, 3, -1, 5, -3, 0, 2, -4, 1, -1)
ck_ice_days(tmax, dates)

Last Frost Date

Description

Date of the last spring frost (Tmin < 0 degrees C) before July 1 in each year.

Usage

ck_last_frost(tmin, dates)

Arguments

Value

A data frame with columns period, value (day of year), date (the frost date), index, and unit.

Examples

dates <- seq(as.Date("2024-01-01"), as.Date("2024-06-30"), by = "day")
set.seed(42)
tmin <- -10 + seq_along(dates) * 0.12 + rnorm(length(dates), sd = 3)
ck_last_frost(tmin, dates)

Maximum 1-Day Precipitation

Description

Maximum precipitation recorded in a single day per period.

Usage

ck_max_1day_precip(precip, dates, period = "annual")

Arguments

Value

A data frame with columns period, value, index, and unit.

Examples

dates <- as.Date("2024-01-01") + 0:9
precip <- c(0, 5, 22, 0, 15, 25, 0, 11, 4, 30)
ck_max_1day_precip(precip, dates)

Maximum 5-Day Precipitation

Description

Maximum precipitation total over any 5 consecutive days per period.

Usage

ck_max_5day_precip(precip, dates, period = "annual")

Arguments

Value

A data frame with columns period, value, index, and unit.

Examples

dates <- as.Date("2024-01-01") + 0:9
precip <- c(0, 5, 22, 0, 15, 25, 0, 11, 4, 30)
ck_max_5day_precip(precip, dates)

Get Metadata for a Climate Index

Description

Returns metadata (unit, category, description, reference) for a named climate index.

Usage

ck_metadata(index)

Arguments

Value

A list with elements index, category, unit, description, and reference.

Examples

ck_metadata("frost_days")

Potential Evapotranspiration (Hargreaves Method)

Description

Estimate daily PET using the Hargreaves-Samani equation, which requires only daily temperature extremes and latitude.

Usage

ck_pet(tmin, tmax, lat, dates)

Arguments

Value

A data frame with columns date, value, index, and unit.

References

Hargreaves, G. H., & Samani, Z. A. (1985). Reference crop evapotranspiration from temperature. Applied Engineering in Agriculture, 1(2), 96-99.

Examples

dates <- as.Date("2024-07-01") + 0:9
tmin <- c(15, 16, 14, 17, 15, 13, 16, 14, 15, 16)
tmax <- c(30, 32, 28, 33, 31, 27, 34, 29, 30, 32)
ck_pet(tmin, tmax, lat = 45, dates = dates)

Precipitation Intensity (SDII)

Description

Mean precipitation on wet days (days with precipitation >= 1 mm). Also known as the Simple Daily Intensity Index.

Usage

ck_precip_intensity(precip, dates, period = "annual")

Arguments

Value

A data frame with columns period, value, index, and unit.

Examples

dates <- as.Date("2024-01-01") + 0:9
precip <- c(0, 5, 12, 0, 15, 2, 0, 11, 4, 0)
ck_precip_intensity(precip, dates)

Standardized Precipitation-Evapotranspiration Index (SPEI)

Description

Compute the SPEI by fitting a log-logistic distribution to the monthly climatic water balance (precipitation minus potential evapotranspiration) accumulated over a rolling window.

Usage

ck_spei(precip, pet, dates, scale = 3)

Arguments

Value

A data frame with columns period, value, index, and unit.

References

Vicente-Serrano, S. M., Begueria, S., & Lopez-Moreno, J. I. (2010). A multiscalar drought index sensitive to global warming: the Standardized Precipitation Evapotranspiration Index. Journal of Climate, 23(7), 1696-1718.

Examples

dates <- seq(as.Date("2020-01-01"), as.Date("2023-12-31"), by = "day")
set.seed(42)
precip <- rgamma(length(dates), shape = 0.5, rate = 0.1)
pet <- rep(3, length(dates))
ck_spei(precip, pet, dates, scale = 3)

Standardized Precipitation Index (SPI)

Description

Compute the SPI by fitting a gamma distribution to monthly precipitation totals accumulated over a rolling window, then transforming to standard normal deviates.

Usage

ck_spi(precip, dates, scale = 3)

Arguments

Value

A data frame with columns period, value, index, and unit.

References

McKee, T. B., Doesken, N. J., & Kleist, J. (1993). The relationship of drought frequency and duration to time scales.

Examples

dates <- seq(as.Date("2020-01-01"), as.Date("2023-12-31"), by = "day")
set.seed(42)
precip <- rgamma(length(dates), shape = 0.5, rate = 0.1)
ck_spi(precip, dates, scale = 3)

Summer Days

Description

Count the number of days where maximum temperature exceeds 25 degrees C.

Usage

ck_summer_days(tmax, dates, period = "annual")

Arguments

Value

A data frame with columns period, value, index, and unit.

Examples

dates <- as.Date("2024-07-01") + 0:9
tmax <- c(22, 26, 28, 24, 30, 25, 27, 23, 31, 29)
ck_summer_days(tmax, dates)

Total Precipitation

Description

Total precipitation sum by period.

Usage

ck_total_precip(precip, dates, period = "annual")

Arguments

Value

A data frame with columns period, value, index, and unit.

Examples

dates <- as.Date("2024-01-01") + 0:9
precip <- c(0, 5, 3, 0, 8, 2, 0, 1, 4, 0)
ck_total_precip(precip, dates)

Tropical Nights

Description

Count the number of days where minimum temperature exceeds 20 degrees C.

Usage

ck_tropical_nights(tmin, dates, period = "annual")

Arguments

Value

A data frame with columns period, value, index, and unit.

Examples

dates <- as.Date("2024-07-01") + 0:9
tmin <- c(18, 21, 22, 19, 25, 20, 23, 17, 24, 21)
ck_tropical_nights(tmin, dates)

Very Heavy Precipitation Days

Description

Count of days with precipitation at or above a threshold (default 20 mm).

Usage

ck_very_heavy_precip(precip, dates, threshold = 20, period = "annual")

Arguments

Value

A data frame with columns period, value, index, and unit.

Examples

dates <- as.Date("2024-01-01") + 0:9
precip <- c(0, 5, 22, 0, 15, 25, 0, 11, 4, 30)
ck_very_heavy_precip(precip, dates)

Warm Spell Days

Description

Count the number of days in warm spells, where a warm spell is defined as at least 6 consecutive days with Tmax above the threshold quantile of the full series. This computes warm spell days using a quantile threshold from the input series. It does not implement the ETCCDI WSDI, which requires calendar-day percentiles from a 1961-1990 reference period.

Usage

ck_warm_spell(tmax, dates, threshold = 0.9, period = "annual")

Arguments

Value

A data frame with columns period, value, index, and unit.

Examples

dates <- as.Date("2024-01-01") + 0:364
set.seed(42)
tmax <- rnorm(365, mean = 20, sd = 5)
ck_warm_spell(tmax, dates)

Maximum Consecutive Wet Days

Description

Maximum number of consecutive days with precipitation at or above a threshold.

Usage

ck_wet_days(precip, dates, threshold = 1, period = "annual")

Arguments

Value

A data frame with columns period, value, index, and unit.

Examples

dates <- as.Date("2024-01-01") + 0:9
precip <- c(5, 3, 0, 2, 8, 1, 0, 0, 4, 6)
ck_wet_days(precip, dates)

Wind Chill Temperature

Description

Compute wind chill using the North American Wind Chill Index formula (Environment Canada / US NWS). Valid for temperatures at or below 10 degrees C and wind speeds above 4.8 km/h.

Usage

ck_wind_chill(tavg, wind_speed)

Arguments

Value

A data frame with columns value, index, and unit.

Examples

ck_wind_chill(tavg = c(-5, -10, 0), wind_speed = c(20, 30, 15))

Winkler Index

Description

The Winkler index (also called growing degree days for viticulture) accumulates daily mean temperature above 10 degrees C during the growing season (April-October in NH, October-April in SH).

Usage

ck_winkler(tavg, dates)

Arguments

Value

A data frame with columns period, value, index, and unit.

References

Amerine, M. A., & Winkler, A. J. (1944). Composition and quality of musts and wines of California grapes.

Examples

dates <- seq(as.Date("2024-04-01"), as.Date("2024-10-31"), by = "day")
set.seed(42)
tavg <- rnorm(length(dates), mean = 18, sd = 4)
ck_winkler(tavg, dates)

Clear Cache

Description

Removes any cached reference data stored by climatekit.

Usage

clear_cache()

Value

Invisibly returns TRUE if cache was cleared, FALSE if no cache existed.

Examples

op <- options(climatekit.cache_dir = tempdir())
clear_cache()
options(op)