| Title: | GeoAI and Digital Epidemiology Tools for Disease Surveillance |
|---|---|
| Description: | Provides tools for digital epidemiology and geospatial artificial intelligence, including surveillance-data cleaning, spatial epidemiology, spatial autocorrelation and hotspot detection, environmental data integration, machine-learning-based disease-risk prediction, dynamic risk mapping, early-warning detection, and automated epidemiological reporting. The methods include spatial autocorrelation (Moran, 1950) <doi:10.1093/biomet/37.1-2.17>, local spatial association analysis (Getis and Ord, 1992) <doi:10.1111/j.1538-4632.1992.tb00261.x>, Random Forest (Breiman, 2001) <doi:10.1023/A:1010933404324>, XGBoost (Chen and Guestrin, 2016) <doi:10.1145/2939672.2939785>, and spatial data handling (Pebesma, 2018) <doi:10.32614/RJ-2018-009>. The package supports applications in disease surveillance, epidemiological risk assessment, and environmental health. |
| Authors: | Vinodhkumar Obli Rajendran [aut, cre], Keerthi Aaradhana [aut] |
| Maintainer: | Vinodhkumar Obli Rajendran <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 0.1.0 |
| Built: | 2026-11-17 15:30:37 UTC |
| Source: | https://github.com/cran/GeoEpiAI |
Cleans disease surveillance records by standardising location, date, and case-count variables. Optionally validates population data, aggregates duplicate location-date records, and calculates monthly incidence per 100,000 population.
clean_surveillance( data, location, date, cases, population = NULL, aggregate = TRUE )clean_surveillance( data, location, date, cases, population = NULL, aggregate = TRUE )
data |
A data.frame containing surveillance records. |
location |
Column containing geographic unit. |
date |
Column containing date/month. |
cases |
Column containing disease cases. |
population |
Optional population column. |
aggregate |
If TRUE, aggregate duplicate location-date records. |
A cleaned data.frame containing location, date, cases, month, and incidence. If population is supplied, the population column is also returned.
dat <- data.frame( location = c("A", "A", "B", "B"), date = as.Date(c( "2025-01-01", "2025-02-01", "2025-01-01", "2025-02-01" )), cases = c(10, 15, 5, 8), population = c(10000, 10000, 8000, 8000) ) clean_surveillance( dat, location = "location", date = "date", cases = "cases", population = "population" )dat <- data.frame( location = c("A", "A", "B", "B"), date = as.Date(c( "2025-01-01", "2025-02-01", "2025-01-01", "2025-02-01" )), cases = c(10, 15, 5, 8), population = c(10000, 10000, 8000, 8000) ) clean_surveillance( dat, location = "location", date = "date", cases = "cases", population = "population" )
Creates a ggplot-based spatial risk map with separate facets for each time period.
dynamic_risk_map(data, risk = "risk", time = "date")dynamic_risk_map(data, risk = "risk", time = "date")
data |
sf object containing predicted risk and time. |
risk |
Column containing predicted risk. |
time |
Column containing time period. |
A ggplot object faceted by time.
map_data <- sf::st_as_sf( data.frame( risk = c(0.2, 0.5, 0.7, 0.9), date = as.Date(c( "2025-01-01", "2025-01-01", "2025-02-01", "2025-02-01" )), x = c(0, 1, 0, 1), y = c(0, 0, 1, 1) ), coords = c("x", "y"), crs = 4326 ) dynamic_risk_map( map_data, risk = "risk", time = "date" )map_data <- sf::st_as_sf( data.frame( risk = c(0.2, 0.5, 0.7, 0.9), date = as.Date(c( "2025-01-01", "2025-01-01", "2025-02-01", "2025-02-01" )), x = c(0, 1, 0, 1), y = c(0, 0, 1, 1) ), coords = c("x", "y"), crs = 4326 ) dynamic_risk_map( map_data, risk = "risk", time = "date" )
Calculates rolling baselines and Z-scores to identify potential increases in disease cases. When a location column is available, calculations are performed independently for each location. At least two previous observations are required to calculate a Z-score.
early_warning(data, date, cases, window = 4, threshold = 2, location = NULL)early_warning(data, date, cases, window = 4, threshold = 2, location = NULL)
data |
A data frame containing surveillance observations. |
date |
Character string specifying the date column. |
cases |
Character string specifying the case-count column. |
window |
Number of previous observations used for the rolling baseline. Must be at least 2. |
threshold |
Positive Z-score threshold for an alert. |
location |
Optional character string specifying the location column. If NULL, a column named "location" is detected automatically when available. |
The rolling baseline is calculated using previous observations only. Calculations are performed independently for each location. At least two previous observations are required to calculate the sample standard deviation and Z-score.
When the historical standard deviation is zero, an increase above the baseline is assigned an infinite Z-score and flagged as an alert. Otherwise, the Z-score is set to zero.
A data frame containing date, cases, baseline, z_score, alert, and alert_level. A location column is retained when location-wise analysis is performed.
surveillance <- data.frame( location = rep(c("A", "B"), each = 8), date = rep(as.Date("2026-01-01") + 0:7, 2), cases = c( 10, 11, 10, 12, 11, 13, 30, 35, 2, 2, 3, 2, 3, 2, 3, 3 ) ) early_warning( surveillance, date = "date", cases = "cases", window = 4, threshold = 2 )surveillance <- data.frame( location = rep(c("A", "B"), each = 8), date = rep(as.Date("2026-01-01") + 0:7, 2), cases = c( 10, 11, 10, 12, 11, 13, 30, 35, 2, 2, 3, 2, 3, 2, 3, 3 ) ) early_warning( surveillance, date = "date", cases = "cases", window = 4, threshold = 2 )
Generates an HTML epidemiological report containing a surveillance summary, disease trend, optional risk map, and optional early-warning results.
epi_report( surveillance, output_file, title = "GeoEpiAI Epidemiological Report", risk_map = NULL, warning_table = NULL )epi_report( surveillance, output_file, title = "GeoEpiAI Epidemiological Report", risk_map = NULL, warning_table = NULL )
surveillance |
Clean surveillance data containing at least
|
output_file |
Explicit path and filename for the generated HTML report. No default output path is used. |
title |
Report title. |
risk_map |
Optional ggplot risk map. |
warning_table |
Optional early-warning table. |
Path to the generated report.
if (requireNamespace("rmarkdown", quietly = TRUE)) { surveillance <- data.frame( location = c("A", "A", "B", "B"), date = as.Date(c( "2025-01-01", "2025-02-01", "2025-01-01", "2025-02-01" )), cases = c(10, 15, 5, 8) ) output_file <- file.path( tempdir(), "GeoEpiAI_example_report.html" ) epi_report( surveillance = surveillance, output_file = output_file, title = "Example GeoEpiAI Report" ) }if (requireNamespace("rmarkdown", quietly = TRUE)) { surveillance <- data.frame( location = c("A", "A", "B", "B"), date = as.Date(c( "2025-01-01", "2025-02-01", "2025-01-01", "2025-02-01" )), cases = c(10, 15, 5, 8) ) output_file <- file.path( tempdir(), "GeoEpiAI_example_report.html" ) epi_report( surveillance = surveillance, output_file = output_file, title = "Example GeoEpiAI Report" ) }
Runs the main GeoEpiAI surveillance workflow, including surveillance-data cleaning and early-warning analysis, with optional machine-learning risk prediction and spatial risk mapping.
geoepi_pipeline( surveillance, location, date, cases, population = NULL, risk_formula = NULL, sf_data = NULL )geoepi_pipeline( surveillance, location, date, cases, population = NULL, risk_formula = NULL, sf_data = NULL )
surveillance |
Surveillance data.frame. |
location |
Location column. |
date |
Date column. |
cases |
Case-count column. |
population |
Optional population column. |
risk_formula |
Optional binary risk formula. |
sf_data |
Optional sf spatial data for mapping. |
A named list of cleaned data, warning results and optional model and mapping results.
dat <- data.frame( location = c("A", "A", "B", "B"), date = as.Date(c( "2025-01-01", "2025-02-01", "2025-01-01", "2025-02-01" )), cases = c(10, 15, 5, 8), population = c(10000, 10000, 8000, 8000) ) result <- geoepi_pipeline( surveillance = dat, location = "location", date = "date", cases = "cases", population = "population" ) names(result)dat <- data.frame( location = c("A", "A", "B", "B"), date = as.Date(c( "2025-01-01", "2025-02-01", "2025-01-01", "2025-02-01" )), cases = c(10, 15, 5, 8), population = c(10000, 10000, 8000, 8000) ) result <- geoepi_pipeline( surveillance = dat, location = "location", date = "date", cases = "cases", population = "population" ) names(result)
Identifies statistically high and low spatial concentrations using the Local Getis-Ord Gi* statistic.
hotspot_detection(data, value, queen = TRUE)hotspot_detection(data, value, queen = TRUE)
data |
sf object. |
value |
Variable to analyse. |
queen |
Use queen contiguity for polygons. |
An sf object containing the Gi statistic, p-value, and hotspot classification.
pts <- sf::st_as_sf( data.frame( value = c( 10, 20, 30, 40, 20, 30, 40, 50, 30, 40, 50, 60, 40, 50, 60, 70 ), x = rep(0:3, each = 4), y = rep(0:3, times = 4) ), coords = c("x", "y"), crs = 4326 ) hotspot_result <- hotspot_detection( pts, value = "value" ) hotspot_resultpts <- sf::st_as_sf( data.frame( value = c( 10, 20, 30, 40, 20, 30, 40, 50, 30, 40, 50, 60, 40, 50, 60, 70 ), x = rep(0:3, each = 4), y = rep(0:3, times = 4) ), coords = c("x", "y"), crs = 4326 ) hotspot_result <- hotspot_detection( pts, value = "value" ) hotspot_result
Supports tabular location/date joins and sf spatial joins.
integrate_environment( surveillance, environment, by = c("location", "date"), method = c("left", "inner", "spatial_nearest"), max_distance = Inf )integrate_environment( surveillance, environment, by = c("location", "date"), method = c("left", "inner", "spatial_nearest"), max_distance = Inf )
surveillance |
Surveillance data.frame. |
environment |
Environmental data.frame or sf object. |
by |
Character vector of shared keys, e.g. c("location", "date"). |
method |
Join method: "left", "inner", or "spatial_nearest". |
max_distance |
Maximum distance for nearest spatial join, in CRS units. |
Joined data.frame or sf object.
surveillance <- data.frame( location = c("A", "B"), date = as.Date(c("2025-01-01", "2025-01-01")), cases = c(10, 5) ) environment <- data.frame( location = c("A", "B"), date = as.Date(c("2025-01-01", "2025-01-01")), precipitation = c(120, 80), temperature = c(25, 23) ) integrate_environment( surveillance, environment, by = c("location", "date"), method = "left" )surveillance <- data.frame( location = c("A", "B"), date = as.Date(c("2025-01-01", "2025-01-01")), cases = c(10, 5) ) environment <- data.frame( location = c("A", "B"), date = as.Date(c("2025-01-01", "2025-01-01")), precipitation = c(120, 80), temperature = c(25, 23) ) integrate_environment( surveillance, environment, by = c("location", "date"), method = "left" )
Generates predicted disease-risk probabilities from a Random Forest or GeoEpiAI XGBoost model.
predict_risk(model, newdata)predict_risk(model, newdata)
model |
Random Forest, xgboost, or GeoEpiAI_xgb model. |
newdata |
New observations containing predictor variables. |
Numeric predicted risk probabilities.
set.seed(123) dat <- data.frame( risk = factor( rep(c("Low", "High"), each = 10) ), precipitation = runif(20, 50, 200), temperature = runif(20, 20, 35) ) rf <- train_rf_risk( risk ~ precipitation + temperature, data = dat, ntree = 20 ) new_data <- data.frame( precipitation = c(100, 150), temperature = c(25, 30) ) predict_risk( rf, new_data )set.seed(123) dat <- data.frame( risk = factor( rep(c("Low", "High"), each = 10) ), precipitation = runif(20, 50, 200), temperature = runif(20, 20, 35) ) rf <- train_rf_risk( risk ~ precipitation + temperature, data = dat, ntree = 20 ) new_data <- data.frame( precipitation = c(100, 150), temperature = c(25, 30) ) predict_risk( rf, new_data )
Calculates Global Moran's I to assess spatial autocorrelation in an sf point or polygon dataset.
spatial_autocorrelation(data, value, queen = TRUE)spatial_autocorrelation(data, value, queen = TRUE)
data |
sf polygon/point object. |
value |
Variable to analyse. |
queen |
Use queen contiguity for polygons. |
A list containing the Moran test and spatial weights.
pts <- sf::st_as_sf( data.frame( value = c( 10, 20, 30, 40, 20, 30, 40, 50, 30, 40, 50, 60, 40, 50, 60, 70 ), x = rep(0:3, each = 4), y = rep(0:3, times = 4) ), coords = c("x", "y"), crs = 4326 ) moran_result <- spatial_autocorrelation( pts, value = "value" ) moran_result$testpts <- sf::st_as_sf( data.frame( value = c( 10, 20, 30, 40, 20, 30, 40, 50, 30, 40, 50, 60, 40, 50, 60, 70 ), x = rep(0:3, each = 4), y = rep(0:3, times = 4) ), coords = c("x", "y"), crs = 4326 ) moran_result <- spatial_autocorrelation( pts, value = "value" ) moran_result$test
Trains a Random Forest classifier for binary disease-risk prediction.
train_rf_risk(formula, data, ntree = 500, seed = 123)train_rf_risk(formula, data, ntree = 500, seed = 123)
formula |
Model formula; outcome should be binary 0/1 for classification. |
data |
Training data. |
ntree |
Number of trees. |
seed |
Random seed. |
A randomForest model.
set.seed(123) dat <- data.frame( risk = factor( rep(c("Low", "High"), each = 10) ), precipitation = runif(20, 50, 200), temperature = runif(20, 20, 35) ) rf <- train_rf_risk( risk ~ precipitation + temperature, data = dat, ntree = 20 ) rfset.seed(123) dat <- data.frame( risk = factor( rep(c("Low", "High"), each = 10) ), precipitation = runif(20, 50, 200), temperature = runif(20, 20, 35) ) rf <- train_rf_risk( risk ~ precipitation + temperature, data = dat, ntree = 20 ) rf
Trains an XGBoost binary classification model for disease-risk prediction.
train_xgb_risk( formula, data, nrounds = 200, max_depth = 4, eta = 0.05, seed = 123 )train_xgb_risk( formula, data, nrounds = 200, max_depth = 4, eta = 0.05, seed = 123 )
formula |
Binary classification formula. |
data |
Training data. |
nrounds |
Number of boosting rounds. |
max_depth |
Maximum tree depth. |
eta |
Learning rate. |
seed |
Random seed. |
A list containing the xgboost model and preprocessing information.
set.seed(123) dat <- data.frame( risk = rep(c(0, 1), each = 10), precipitation = runif(20, 50, 200), temperature = runif(20, 20, 35) ) xgb <- train_xgb_risk( risk ~ precipitation + temperature, data = dat, nrounds = 10 ) xgbset.seed(123) dat <- data.frame( risk = rep(c(0, 1), each = 10), precipitation = runif(20, 50, 200), temperature = runif(20, 20, 35) ) xgb <- train_xgb_risk( risk ~ precipitation + temperature, data = dat, nrounds = 10 ) xgb
Checks surveillance data for missing locations, missing dates, non-numeric case counts, and negative case counts.
validate_surveillance(data, location, date, cases)validate_surveillance(data, location, date, cases)
data |
A data.frame. |
location |
Location column. |
date |
Date column. |
cases |
Case-count column. |
Invisibly returns TRUE.
dat <- data.frame( location = c("A", "B"), date = as.Date(c( "2025-01-01", "2025-02-01" )), cases = c(10, 5) ) validate_surveillance( dat, location = "location", date = "date", cases = "cases" )dat <- data.frame( location = c("A", "B"), date = as.Date(c( "2025-01-01", "2025-02-01" )), cases = c(10, 5) ) validate_surveillance( dat, location = "location", date = "date", cases = "cases" )