mosquitoR

The goal of VectorModelR is to provide a set of tools for accessing global datasets, and combining them with Mosquito Alert citizen science data to generate Vector Models (https://www.mosquitoalert.com/), including Mosquito Alert citizen science data, smart trap data from the Irideon Senscape API, and traditional mosquito trap data.

IMPORTANT: This package is at an early stage of development, and we may introduce “breaking” changes. In addition, please note that while the package contains functions for working with the Irideon Senscape API, it is not developed by Irideon and is not an official Irideon package.

Installation

You can install the development version of VectorModelR from GitHub as follows:

# install.packages("devtools")
devtools::install_github("Mosquito-Alert/vectormodelR")

Example

The following example demonstrates a complete workflow for acquiring data, processing environmental covariates, and fitting a Bayesian spatial model.

1. Setup

First, load the package and define the target area and modeling parameters.

library(vectormodelR)
library(terra)
library(dplyr)

# targeted region
target_country_iso3 <- "ESP"
target_level        <- 2
target_city         <- "Barcelona"

# modelling parameters
nchains             <- 4
threads_per_chain   <- 1

2. Data Acquisition

Download vector surveillance data and environmental covariates.

# Get vector counts from Mosquito Alert and GBIF
counts <- vectormodelR::get_vector_counts(
  iso3 = target_country_iso3, 
  level = target_level
)

# Inspect available administrative unit names
# vectormodelR::get_gadm_names(
#   country = target_country, 
#   level = target_level, 
#   view = "datatable"
# )

# Administrative boundaries
map <- vectormodelR::get_gadm_data(
  iso3 = target_country_iso3, 
  name = target_city, 
  level = target_level, 
  perimeter = TRUE, 
  rds = TRUE
)

# Download ERA5 weather data (requires ECMWF API key)
# See ?ecmwfr::wf_set_key for setup instructions
# vectormodelR::get_era5_data(
#   country_iso3 = target_country_iso3,
#   start_year = 2020, 
#   end_year = 2021,
#   write_key = TRUE
# )

# Compile downloaded ERA5 data
# vectormodelR::compile_era5_data_v2(
#   iso3 = target_country_iso3,
#   recent_n = 12,
#   verbose = TRUE
# )

3. Spatial Grid & Environmental Features

Build a hexagonal grid and process environmental layers (Landcover, Elevation, NDVI, Population).

# Create hexagonal grids at different resolutions
hex_grid400 <- vectormodelR::build_spatial_grid(
  iso3 = target_country_iso3, 
  admin_level = target_level, 
  admin_name = target_city,
  cellsize_m = 400
)

hex_grid800 <- vectormodelR::build_spatial_grid(
  iso3 = target_country_iso3, 
  admin_level = target_level, 
  admin_name = target_city, 
  cellsize_m = 800
)

hex_grid1200 <- vectormodelR::build_spatial_grid(
  iso3 = target_country_iso3, 
  admin_level = target_level, 
  admin_name = target_city, 
  cellsize_m = 1200
)

# Process ERA5 data (if downloaded)
# vectormodelR::process_era5_data(
#   iso3 = target_country_iso3,
#   admin_level = target_level,
#   admin_name = target_city,
#   aggregation_unit = "cell"
# )

# Process Landcover (requires raw raster input)
# lc <- terra::rast("path/to/landcover.tif")
# processed_lc = vectormodelR::process_landcover_data( 
#   lc,
#   iso3 = target_country_iso3,
#   admin_level = target_level,
#   admin_name = target_city,
#   proc_dir = "data/proc"
# )

# Get Elevation
elevation <- vectormodelR::get_elevation_data(
  target_country_iso3, 
  level = target_level, 
  name_value = target_city
)

4. Initialize & Enrich Dataset

Initialize the dataset structure and add processed features.

# Initialize empty dataset structure
initialized_data = vectormodelR::initialize_vector_dataset(
  iso3 = target_country_iso3, 
  admin_level = target_level,
  admin_name = target_city
)

# Add features (Population, Weather, NDVI, etc.)
enriched_data = vectormodelR::add_features(
  target_country_iso3,
  target_level,
  target_city,
  vector_sources = c("malert", "gbif"),
  features = "se,el,ndvi,pd,wx,lc,hex,hex_800,hex_1200"
)

5. Modeling

Fit a Bayesian BYM2 model to account for spatial autocorrelation.

# Run BYM2 model with brms
brms_bym2_model <- vectormodelR::run_brms_bym2_model(
  dataset = enriched_data,
  iso3 = target_country_iso3,
  admin_level = target_level,
  admin_name = target_city,
  nchains = nchains,
  threads_per_chain = threads_per_chain,
  adapt_delta = 0.95,
  max_treedepth = 15
)

# Model summary and diagnostics
summary(brms_bym2_model)
brms::rhat(brms_bym2_model)
brms::neff_ratio(brms_bym2_model)

6. Visualization

Visualize the conditional effects of predictors, such as population density.

library(ggplot2)
library(brms)

# Extract conditional effects for population density (standardized)
ce_pop <- conditional_effects(brms_bym2_model, effects = "pop_z")

plot(ce_pop, plot = FALSE)[[1]] + 
  geom_hline(yintercept = 0.5, linetype = "dashed", color = "red") + 
  labs(
    title = "Effect of Population Density on Mosquito Presence",
    x = "Population Density (Z-score)",
    y = "Probability of Presence"
  ) +
  theme_minimal()

Documentation

Online documentation can be found at https://labs.mosquitoalert.com/mosquitoR/.

Contributing

If you want to contribute new functions, fix bugs, add documentation or tests, etc., please do so on the dev branch. We are developing this package using devtools and testthat and doing our best to follow the guidelines and styles laid out in https://r-pkgs.org.

Funding

This work has been supported by the Plan Estatal de Investigación Científica, Técnica y de Innovación 2021-2023 funded by MCIN/AEI/EU - CNS2022-135646 and by the European Union’s NextGenerationEU/PRTR program, and by the European Union’s Horizon Europe programme (HORIZON Research and Innovation Actions) under Grant Agreement 101086640.