| Type: | Package |
| Title: | GeoAI and Digital Epidemiology Tools for Disease Surveillance |
| Version: | 0.1.0 |
| Author: | Vinodhkumar Obli Rajendran [aut, cre], Keerthi Aaradhana [aut] |
| Maintainer: | Vinodhkumar Obli Rajendran <vinodhkumar.rajendran@gmail.com> |
| 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. |
| License: | MIT + file LICENSE |
| Depends: | R (≥ 4.1.0) |
| Imports: | dplyr, ggplot2, lubridate, randomForest, sf, spdep, xgboost |
| Suggests: | knitr, rmarkdown, testthat (≥ 3.0.0) |
| Encoding: | UTF-8 |
| Config/testthat/edition: | 3 |
| Config/roxygen2/version: | 8.1.0 |
| NeedsCompilation: | no |
| Packaged: | 2026-10-30 07:02:34 UTC; m |
| Repository: | CRAN |
| Date/Publication: | 2026-11-17 12:20:11 UTC |
GeoEpiAI: GeoAI and Digital Epidemiology Tools
Description
Provides a lightweight toolkit for surveillance-data cleaning, spatial epidemiology, machine-learning risk prediction, environmental integration, dynamic risk mapping, early warning, and automated reporting.
Author(s)
Maintainer: Vinodhkumar Obli Rajendran vinodhkumar.rajendran@gmail.com
Authors:
Vinodhkumar Obli Rajendran vinodhkumar.rajendran@gmail.com
Keerthi Aaradhana vkeerthi1817@gmail.com
Validate and clean disease surveillance data
Description
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.
Usage
clean_surveillance(
data,
location,
date,
cases,
population = NULL,
aggregate = TRUE
)
Arguments
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. |
Value
A cleaned data.frame containing location, date, cases, month, and incidence. If population is supplied, the population column is also returned.
Examples
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"
)
Create a dynamic risk map
Description
Creates a ggplot-based spatial risk map with separate facets for each time period.
Usage
dynamic_risk_map(data, risk = "risk", time = "date")
Arguments
data |
sf object containing predicted risk and time. |
risk |
Column containing predicted risk. |
time |
Column containing time period. |
Value
A ggplot object faceted by time.
Examples
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"
)
Detect Early-Warning Signals in Surveillance Data
Description
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.
Usage
early_warning(data, date, cases, window = 4, threshold = 2, location = NULL)
Arguments
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. |
Details
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.
Value
A data frame containing date, cases, baseline, z_score, alert, and alert_level. A location column is retained when location-wise analysis is performed.
Examples
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
)
Generate an automated epidemiological report
Description
Generates an HTML epidemiological report containing a surveillance summary, disease trend, optional risk map, and optional early-warning results.
Usage
epi_report(
surveillance,
output_file,
title = "GeoEpiAI Epidemiological Report",
risk_map = NULL,
warning_table = NULL
)
Arguments
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. |
Value
Path to the generated report.
Examples
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"
)
}
Run the complete GeoEpiAI surveillance workflow
Description
Runs the main GeoEpiAI surveillance workflow, including surveillance-data cleaning and early-warning analysis, with optional machine-learning risk prediction and spatial risk mapping.
Usage
geoepi_pipeline(
surveillance,
location,
date,
cases,
population = NULL,
risk_formula = NULL,
sf_data = NULL
)
Arguments
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. |
Value
A named list of cleaned data, warning results and optional model and mapping results.
Examples
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)
Local Getis-Ord Gi* hotspot detection
Description
Identifies statistically high and low spatial concentrations using the Local Getis-Ord Gi* statistic.
Usage
hotspot_detection(data, value, queen = TRUE)
Arguments
data |
sf object. |
value |
Variable to analyse. |
queen |
Use queen contiguity for polygons. |
Value
An sf object containing the Gi statistic, p-value, and hotspot classification.
Examples
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_result
Integrate environmental predictors with surveillance locations
Description
Supports tabular location/date joins and sf spatial joins.
Usage
integrate_environment(
surveillance,
environment,
by = c("location", "date"),
method = c("left", "inner", "spatial_nearest"),
max_distance = Inf
)
Arguments
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. |
Value
Joined data.frame or sf object.
Examples
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"
)
Predict disease risk from a GeoEpiAI model
Description
Generates predicted disease-risk probabilities from a Random Forest or GeoEpiAI XGBoost model.
Usage
predict_risk(model, newdata)
Arguments
model |
Random Forest, xgboost, or GeoEpiAI_xgb model. |
newdata |
New observations containing predictor variables. |
Value
Numeric predicted risk probabilities.
Examples
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
)
Global Moran's I spatial autocorrelation
Description
Calculates Global Moran's I to assess spatial autocorrelation in an sf point or polygon dataset.
Usage
spatial_autocorrelation(data, value, queen = TRUE)
Arguments
data |
sf polygon/point object. |
value |
Variable to analyse. |
queen |
Use queen contiguity for polygons. |
Value
A list containing the Moran test and spatial weights.
Examples
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$test
Train a Random Forest disease-risk model
Description
Trains a Random Forest classifier for binary disease-risk prediction.
Usage
train_rf_risk(formula, data, ntree = 500, seed = 123)
Arguments
formula |
Model formula; outcome should be binary 0/1 for classification. |
data |
Training data. |
ntree |
Number of trees. |
seed |
Random seed. |
Value
A randomForest model.
Examples
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
)
rf
Train an XGBoost disease-risk model
Description
Trains an XGBoost binary classification model for disease-risk prediction.
Usage
train_xgb_risk(
formula,
data,
nrounds = 200,
max_depth = 4,
eta = 0.05,
seed = 123
)
Arguments
formula |
Binary classification formula. |
data |
Training data. |
nrounds |
Number of boosting rounds. |
max_depth |
Maximum tree depth. |
eta |
Learning rate. |
seed |
Random seed. |
Value
A list containing the xgboost model and preprocessing information.
Examples
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
)
xgb
Validate surveillance data without modifying it
Description
Checks surveillance data for missing locations, missing dates, non-numeric case counts, and negative case counts.
Usage
validate_surveillance(data, location, date, cases)
Arguments
data |
A data.frame. |
location |
Location column. |
date |
Date column. |
cases |
Case-count column. |
Value
Invisibly returns TRUE.
Examples
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"
)