Package {imdR}

Convert a 3D IMD array to a terra SpatRaster

Description

Convert a 3D IMD array to a terra SpatRaster

Usage

array_to_raster(arr, variable, year)

Arguments

Value

A terra SpatRaster with named layers and time dimension.

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

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

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

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

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

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

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

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

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

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

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

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

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")

Read an IMD binary .grd file

Description

Read an IMD binary .grd file

Usage

read_imd_binary(filepath, variable, year)

Arguments

Value

A numeric 3-dimensional array of dimensions ncols x nrows x ndays.

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

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

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

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

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())