Package 'imdR'

Compute rainfall climate indices

Description

Computes 11 indices per grid cell per year. Handles single-year SpatRasters and multi-year named lists from get_data().

Usage

compute_rainfall_indices(
  rain_raster,
  level = NULL,
  name = NULL,
  file_dir,
  save_csv = TRUE
)

Arguments

rain_raster	A SpatRaster or named list from get_data("rain",...).
level	NULL, "state", or "district".
name	State or district name.
file_dir	Output directory for CSV.
save_csv	Save results as CSV? Default TRUE.

Value

Invisible data frame with columns year, cell, dr, d64, d115, rx1day, rx5day, rtwd, sdii, total, cwd, cdd, pci.

Examples

# Full India rainfall indices for 2020
r   <- get_data("rain", 2020, 2020, tempdir())
idx <- compute_rainfall_indices(r, file_dir = tempdir())

# State level indices
goa_idx <- compute_rainfall_indices(r,
  level    = "state",
  name     = "Goa",
  file_dir = tempdir())

# Multi-year indices for trend analysis
r_3yr   <- get_data("rain", 2018, 2020, tempdir())
idx_3yr <- compute_rainfall_indices(r_3yr, file_dir = tempdir())

---

Compute temperature climate indices

Description

Computes 13 indices per grid cell per year from daily tmax and tmin.

Usage

compute_temp_indices(
  tmax_raster,
  tmin_raster,
  level = NULL,
  name = NULL,
  file_dir,
  save_csv = TRUE
)

Arguments

tmax_raster	A SpatRaster or named list for tmax.
tmin_raster	A SpatRaster or named list for tmin.
level	NULL, "state", or "district".
name	State or district name.
file_dir	Output directory for CSV.
save_csv	Save results as CSV? Default TRUE.

Value

Invisible data frame with columns year, cell, mean_tmax, mean_tmin, mean_dtr, txx, txn, tnx, tnn, su35, su40, tr10, tr25, wsdi, csdi.

Examples

# Full India temperature indices for 2020
tx  <- get_data("tmax", 2020, 2020, tempdir())
tn  <- get_data("tmin", 2020, 2020, tempdir())
idx <- compute_temp_indices(tx, tn, file_dir = tempdir())

# State level indices
goa_idx <- compute_temp_indices(tx, tn,
  level    = "state",
  name     = "Goa",
  file_dir = tempdir())

# Multi-year temperature indices
tx_3yr  <- get_data("tmax", 2018, 2020, tempdir())
tn_3yr  <- get_data("tmin", 2018, 2020, tempdir())
idx_3yr <- compute_temp_indices(tx_3yr, tn_3yr,
                                 file_dir = tempdir())

---

Extract IMD raster masked to a state or district boundary

Description

Crops and masks an IMD SpatRaster to any named state or district using bundled SOI-approved boundaries. Supports three output formats:

• "netcdf" – CF-1.7 compliant NetCDF

• "geotiff" – Multi-band GeoTIFF, opens in QGIS/ArcGIS

• "csv" – Long-format table: date, lat, lon, value

Usage

extract_by_boundary(
  imd_raster,
  level = "state",
  name = NULL,
  variable = "rain",
  save = FALSE,
  format = "netcdf",
  file_dir
)

Arguments

imd_raster	A SpatRaster or named list from get_data().
level	"state" (default) or "district".
name	State or district name (partial match allowed).
variable	Variable name for output column and filename.
save	Save output to disk? Default FALSE.
format	"netcdf" (default), "geotiff", or "csv".
file_dir	Output directory.

Value

Invisible masked SpatRaster.

Examples

r <- get_data("rain", 2020, 2020, tempdir())

# Return masked raster without saving
nagaland_rain <- extract_by_boundary(r, "state", "Nagaland", "rain")

# State — NetCDF
extract_by_boundary(r, "state", "Nagaland", "rain",
  save = TRUE, format = "netcdf", file_dir = tempdir())

# State — GeoTIFF (QGIS/ArcGIS)
extract_by_boundary(r, "state", "Nagaland", "rain",
  save = TRUE, format = "geotiff", file_dir = tempdir())

# State — CSV (all grid points x all days)
extract_by_boundary(r, "state", "Nagaland", "rain",
  save = TRUE, format = "csv", file_dir = tempdir())

# District — all formats work the same way
extract_by_boundary(r, "district", "North Goa", "rain",
  save = TRUE, format = "csv", file_dir = tempdir())

---

Extract IMD data within a bounding box

Description

Crops IMD raster data to a user-defined latitude/longitude bounding box. Useful for custom regions such as the Indo-Gangetic Plains, Western Ghats, or any area not matching a state or district boundary. Supports three output formats: NetCDF, GeoTIFF, and long-format CSV.

Usage

get_bbox(
  lat_min,
  lat_max,
  lon_min,
  lon_max,
  variable,
  start_yr,
  end_yr,
  file_dir,
  format = "netcdf",
  save = TRUE
)

Arguments

lat_min	Numeric. Minimum latitude.
lat_max	Numeric. Maximum latitude.
lon_min	Numeric. Minimum longitude.
lon_max	Numeric. Maximum longitude.
variable	One of "rain", "tmax", "tmin".
start_yr	Integer. Start year.
end_yr	Integer. End year.
file_dir	Character. Directory for files.
format	"netcdf" (default), "geotiff", or "csv".
save	Logical. Save output? Default TRUE.

Value

Invisible SpatRaster of the cropped region.

Examples

# Indo-Gangetic Plains -- NetCDF
get_bbox(lat_min = 24, lat_max = 30,
         lon_min = 73, lon_max = 88,
         variable = "rain",
         start_yr = 2020, end_yr = 2020,
         file_dir = tempdir(),
         format   = "netcdf")

# Western Ghats -- GeoTIFF
get_bbox(lat_min = 8,  lat_max = 21,
         lon_min = 73, lon_max = 78,
         variable = "rain",
         start_yr = 2020, end_yr = 2020,
         file_dir = tempdir(),
         format   = "geotiff")

# Northeast India -- CSV (all grid points x all days)
get_bbox(lat_min = 22, lat_max = 29,
         lon_min = 89, lon_max = 97,
         variable = "rain",
         start_yr = 2020, end_yr = 2020,
         file_dir = tempdir(),
         format   = "csv")

---

Get the sf boundary for a named state or district

Description

Get the sf boundary for a named state or district

Usage

get_boundary(level = "state", name)

Arguments

level	"state" (default) or "district".
name	State or district name (partial match allowed).

Value

An sf object with the matching boundary.

Examples

goa       <- get_boundary("state", "Goa")
north_goa <- get_boundary("district", "North Goa")

---

Download and read IMD gridded data

Description

Downloads binary .grd files from IMD Pune and converts them to terra SpatRaster objects. Single year returns a SpatRaster directly. Multi-year returns a named list of SpatRasters (one per year) because leap and non-leap years have different layer counts.

Usage

get_data(variable, start_yr, end_yr, file_dir, overwrite = FALSE)

Arguments

variable	One of "rain", "tmax", "tmin".
start_yr	Start year (rain: 1901+, temp: 1951+).
end_yr	End year.
file_dir	Directory to save downloaded .grd files.
overwrite	Re-download even if file exists? Default FALSE.

Value

A SpatRaster (single year) or named list of SpatRasters (multi-year).

Examples

# Download single year rainfall
rain2020 <- get_data("rain", 2020, 2020, tempdir())

# Download multiple years (returns named list)
rain_3yr <- get_data("rain", 2018, 2020, tempdir())

# Download temperature data
tmax2020 <- get_data("tmax", 2020, 2020, tempdir())
tmin2020 <- get_data("tmin", 2020, 2020, tempdir())

---

Extract daily time series for a single variable at a point

Description

Extract daily time series for a single variable at a point

Usage

get_point(lat, lon, variable, start_yr, end_yr, file_dir, save_csv = TRUE)

Arguments

lat	Latitude in decimal degrees.
lon	Longitude in decimal degrees.
variable	One of "rain", "tmax", "tmin".
start_yr	Start year.
end_yr	End year.
file_dir	Directory for .grd files.
save_csv	Save output as CSV? Default TRUE.

Value

Invisible data frame with columns date, lat, lon, variable.

Examples

# Extract daily rainfall at Panaji, Goa
df <- get_point(lat = 15.5, lon = 73.8,
                variable = "rain",
                start_yr = 2020, end_yr = 2020,
                file_dir = tempdir())
head(df)

# Extract temperature
df_tmax <- get_point(lat = 15.5, lon = 73.8,
                     variable = "tmax",
                     start_yr = 2020, end_yr = 2020,
                     file_dir = tempdir())

---

Extract daily time series for all variables at a point

Description

Downloads or reads rain, tmax, and tmin at a location and merges them into a single data frame that also includes diurnal temperature range (DTR). Extraction is done year by year to avoid memory issues with long time series on Windows.

Usage

get_point_all(lat, lon, start_yr, end_yr, file_dir, save_csv = TRUE)

Arguments

lat	Latitude in decimal degrees.
lon	Longitude in decimal degrees.
start_yr	Start year.
end_yr	End year.
file_dir	Directory for .grd files.
save_csv	Save merged output as CSV? Default TRUE.

Value

Invisible data frame with columns date, lat, lon, rain, tmax, tmin, dtr.

Examples

# Extract rain, tmax, tmin and DTR at Panaji, Goa
df <- get_point_all(lat = 15.5, lon = 73.8,
                    start_yr = 2020, end_yr = 2020,
                    file_dir = tempdir())
head(df)

# Long time series -- works on Windows without memory errors
df <- get_point_all(lat = 15.5, lon = 73.8,
                    start_yr = 1985, end_yr = 2020,
                    file_dir = tempdir())
nrow(df)

---

India district boundaries (SOI-approved)

Description

An sf object with boundaries for 808 Indian districts, sourced from Survey of India (SOI) shapefiles, reprojected to WGS84.

Usage

india_districts

Format

An sf data frame with 808 rows and columns state_name, district_name, and geometry.

---

India state boundaries (SOI-approved)

Description

An sf object with boundaries for all 36 Indian states and union territories, sourced from Survey of India (SOI) shapefiles, reprojected to WGS84.

Usage

india_states

Format

An sf data frame with 36 rows and columns state_name and geometry.

---

List district names, optionally filtered by state

Description

List district names, optionally filtered by state

Usage

list_districts(state = NULL)

Arguments

state

Character or NULL. Partial match, case-insensitive.

Value

A sorted character vector of district names.

Examples

list_districts()
list_districts("Goa")

---

List all state names in the bundled SOI shapefile

Description

List all state names in the bundled SOI shapefile

Usage

list_states()

Value

A sorted character vector of 36 state/UT names.

Examples

list_states()

---

Read cached IMD .grd files from disk

Description

Read cached IMD .grd files from disk

Usage

open_data(variable, start_yr, end_yr, file_dir)

Arguments

variable	One of "rain", "tmax", "tmin".
start_yr	Start year.
end_yr	End year.
file_dir	Directory containing the variable sub-folder.

Value

A SpatRaster (single year) or named list (multi-year).

Examples

rain2020 <- open_data("rain", 2020, 2020, tempdir())
rain_3yr <- open_data("rain", 2018, 2020, tempdir())

---

Plot a single day of IMD gridded data

Description

Publication-quality map with SOI boundaries. Supports full-India, state-level, and district-level zoom.

Usage

plot_imd(
  imd_raster,
  date,
  variable = "rain",
  level = NULL,
  name = NULL,
  title = NULL,
  save_path = NULL,
  width = 7,
  height = 8
)

Arguments

imd_raster	A SpatRaster or named list from get_data().
date	Date to plot (must match a layer name).
variable	One of "rain", "tmax", "tmin".
level	NULL, "state", or "district" for zoom.
name	State or district name for zoom.
title	Custom title. Auto-generated if NULL.
save_path	File path to save PNG/PDF. NULL = no save.
width	Plot width in inches. Default 7.
height	Plot height in inches. Default 8.

Value

Invisible ggplot2 object.

Examples

r <- get_data("rain", 2020, 2020, tempdir())

# Full India map
plot_imd(r, "2020-06-28", "rain")

# Zoom to Kerala
plot_imd(r, "2020-06-28", "rain",
         level = "state", name = "Kerala")

# Zoom to North Goa district
plot_imd(r, "2020-06-28", "rain",
         level = "district", name = "North Goa")

# Save to file
plot_imd(r, "2020-06-28", "rain",
         save_path = file.path(tempdir(), "rain_20200628.png"))

---

Plot a daily time series with 30-day rolling mean

Description

Plot a daily time series with 30-day rolling mean

Usage

plot_timeseries(
  df,
  variable = "rain",
  title = NULL,
  save_path = NULL,
  width = 10,
  height = 5
)

Arguments

df	Data frame with columns date and the variable.
variable	Column name to plot.
title	Plot title. Auto-generated if NULL.
save_path	File path to save PNG. NULL = no save.
width	Width in inches. Default 10.
height	Height in inches. Default 5.

Value

Invisible ggplot2 object.

Examples

# Extract point data and plot
df <- get_point(lat = 15.5, lon = 73.8,
                variable = "rain",
                start_yr = 2020, end_yr = 2020,
                file_dir = tempdir(),
                save_csv = FALSE)
plot_timeseries(df, variable = "rain")

# Plot temperature with custom title
df_tmax <- get_point(lat = 15.5, lon = 73.8,
                     variable = "tmax",
                     start_yr = 2020, end_yr = 2020,
                     file_dir = tempdir(),
                     save_csv = FALSE)
plot_timeseries(df_tmax, variable = "tmax",
                title = "Goa Maximum Temperature 2020")

---

Extract a daily time series at a point location

Description

Extracts daily values from an IMD SpatRaster at the nearest grid cell to the specified latitude/longitude and returns a data frame.

Usage

to_csv(imd_raster, lat, lon, file_path = NULL)

Arguments

imd_raster	A terra SpatRaster from get_data().
lat	Latitude in decimal degrees (WGS84).
lon	Longitude in decimal degrees (WGS84).
file_path	Character or NULL. If provided, saves output as CSV.

Value

An invisible data frame with columns date and value.

Examples

r  <- get_data("rain", 2020, 2020, tempdir())
df <- to_csv(r, lat = 15.5, lon = 73.8)
head(df)

# Save directly to file
to_csv(r, lat = 15.5, lon = 73.8,
       file_path = file.path(tempdir(), "panaji_rain_2020.csv"))

---

Save an IMD SpatRaster as a compressed GeoTIFF

Description

Writes a multi-layer terra SpatRaster to a DEFLATE-compressed, tiled GeoTIFF suitable for use in QGIS, ArcGIS, Python (rasterio), and other spatial software.

Usage

to_geotiff(imd_raster, file_path)

Arguments

imd_raster	A terra SpatRaster.
file_path	Character. Output .tif file path.

Value

Invisible character: the file path written.

Examples

r <- get_data("rain", 2020, 2020, tempdir())
to_geotiff(r, file.path(tempdir(), "rain_2020.tif"))

# Save a boundary-extracted region
goa <- extract_by_boundary(r, "state", "Goa", "rain")
to_geotiff(goa, file.path(tempdir(), "rain_Goa_2020.tif"))

---

Save an IMD SpatRaster as a CF-1.7 compliant NetCDF file

Description

Writes a multi-layer terra SpatRaster to a CF-1.7 compliant NetCDF file with correct time, latitude, and longitude dimensions and standard metadata attributes.

Usage

to_netcdf(imd_raster, file_path, variable = "rain")

Arguments

imd_raster	A terra SpatRaster.
file_path	Character. Output .nc file path.
variable	One of "rain", "tmax", "tmin".

Value

Invisible character: the file path written.

Examples

r <- get_data("rain", 2020, 2020, tempdir())
to_netcdf(r, file.path(tempdir(), "rain_2020.nc"), "rain")

# Save a boundary-extracted region
goa <- extract_by_boundary(r, "state", "Goa", "rain")
to_netcdf(goa, file.path(tempdir(), "rain_Goa_2020.nc"), "rain")

---

Mann-Kendall trend analysis with Sen's slope

Description

Aggregates multi-cell index data to spatial means per year, then performs Mann-Kendall test and Sen's slope estimation.

Usage

trend_analysis(
  index_df,
  index_col,
  level = NULL,
  name = NULL,
  file_dir,
  save_csv = TRUE,
  plot = TRUE
)

Arguments

index_df	Data frame from compute_rainfall_indices() or compute_temp_indices().
index_col	Column name to analyse (e.g. "total", "dr").
level	Not used in computation; passed to filename.
name	Region name for output filename.
file_dir	Output directory.
save_csv	Save results table as CSV? Default TRUE.
plot	Produce and save a trend plot? Default TRUE.

Value

Invisible data frame with tau, S, pvalue, significance, sens_slope, trend_direction, total_change.

Examples

# Download 10 years of rainfall
r   <- get_data("rain", 2011, 2020, tempdir())
idx <- compute_rainfall_indices(r, file_dir = tempdir())

# Trend in annual total rainfall
trend_analysis(idx, index_col = "total",
               file_dir = tempdir())

# Trend in rainy days
trend_analysis(idx, index_col = "dr",
               file_dir = tempdir())

# Region-specific trend
goa_idx <- compute_rainfall_indices(r,
  level = "state", name = "Goa",
  file_dir = tempdir())
trend_analysis(goa_idx, index_col = "total",
               name = "Goa", file_dir = tempdir())

# Temperature trend
tx   <- get_data("tmax", 2011, 2020, tempdir())
tn   <- get_data("tmin", 2011, 2020, tempdir())
tidx <- compute_temp_indices(tx, tn, file_dir = tempdir())
trend_analysis(tidx, index_col = "mean_tmax",
               file_dir = tempdir())

---