geospatialsuite 🌍

Comprehensive Geospatiotemporal Analysis and Multimodal Integration Toolkit for R

geospatialsuite is a powerful R package for geospatial analysis featuring 60+ vegetation indices, universal spatial analysis, auto-geocoding without coordinates, efficient raster visualization, and comprehensive workflows for agricultural research, environmental monitoring, and remote sensing applications.

📋 Table of Contents

• Key Features
• Quick Links
• Installation
• Quick Start
• Auto-Geocoding
• Documentation
• Real-World Examples
• What Makes geospatialsuite Special
• Supported Vegetation Indices
• Performance
• System Requirements
• Citation
• Contact
• License
• Acknowledgments

🔗 Quick Links

• JOSS Paper: https://joss.theoj.org/papers/10.21105/joss.09536
• CRAN: https://CRAN.R-project.org/package=geospatialsuite
• Documentation: https://exelegch.github.io/geospatialsuite-docs/
• GitHub: https://github.com/cwru-sdle/geospatialsuite
• Bug Reports: https://github.com/cwru-sdle/geospatialsuite/issues

✨ Key Features

🗺️ Auto-Geocoding Without Coordinates

• Work with data that has NO lat/lon! Automatically geocode using geographic identifiers
• States: Full names or abbreviations (e.g., “Ohio”, “OH”)
• Counties: County names with or without state
• FIPS codes: 5-digit Federal codes
• HUC codes: Watershed codes (handles HUC_8, HUC-8, huc8, etc.)
• ZIP codes: US postal codes
• Cities: City names (works best with state column)
• Flexible column naming: Handles spaces, hyphens, underscores, mixed case

🌱 Advanced Vegetation Analysis

• 60+ vegetation indices including NDVI, EVI, SAVI, PRI, SIPI, NDRE, MTCI
• Automatic band detection from Landsat, Sentinel, and other satellite imagery
• Crop-specific analysis for corn, soybeans, wheat, cotton, rice
• Stress detection and yield assessment workflows

🗺️ Universal Spatial Analysis

• Works with ANY data combination - points, polygons, rasters
• Automatic coordinate system handling and spatial validation
• Multiple extraction methods - simple, buffer, bilinear, nearest neighbor
• Multi-dataset integration for comprehensive environmental analysis

📊 Efficient Visualization

• No data frame conversion for large rasters (uses tidyterra, RStoolbox)
• Interactive maps with leaflet integration
• Publication-quality graphics with automatic method selection
• RGB composites with advanced stretching algorithms

🔄 Comprehensive Workflows

• End-to-end analysis pipelines for common geospatial tasks
• NDVI crop analysis with quality filtering and temporal smoothing
• Water quality assessment with spatial integration
• Terrain and temporal analysis workflows

⚡ Performance Features

• Smart fallback systems when optional packages unavailable
• Parallel processing support for multiple indices
• Efficient memory usage optimized for large datasets
• Robust error handling with informative messages

📦 Installation

From CRAN (Recommended)

# Install the stable version from CRAN
install.packages("geospatialsuite")

Development Version from GitHub

# install.packages("devtools")
devtools::install_github("cwru-sdle/geospatialsuite")

🚀 Quick Start

Load Package and Test Installation

library(geospatialsuite)

# Test your installation
test_geospatialsuite_package_simple()

# Check function availability
test_function_availability(verbose = TRUE)

Basic Usage Examples

# Load built-in sample data
red <- load_sample_data("sample_red.rds")
nir <- load_sample_data("sample_nir.rds")
blue <- load_sample_data("sample_blue.rds")
study_sites <- load_sample_data("sample_coordinates.csv")

# 1. One-line mapping (auto-detects everything!)
quick_map(red, title = "Red Band")

# 2. Universal spatial join (most common operation- Requires your own data)
result <- universal_spatial_join(
  source_data = study_sites,
  target_data = red,
  method = "extract"
)

# 3. Calculate vegetation indices with sample data
ndvi <- calculate_vegetation_index(
  red = red, 
  nir = nir, 
  index_type = "NDVI",
  verbose = TRUE
)

# 4. Enhanced NDVI with quality filtering
enhanced_ndvi <- calculate_ndvi_enhanced(
  red = red,
  nir = nir,
  quality_filter = TRUE
)

# 5. Multiple indices at once
indices <- calculate_multiple_indices(
  red = red, 
  nir = nir, 
  blue = blue,
  indices = c("NDVI", "EVI", "SAVI"),
  output_stack = TRUE
)

🗺️ Auto-Geocoding Without Coordinates

Work with data that doesn’t have latitude/longitude coordinates. geospatialsuite automatically detects and geocodes geographic identifiers:

# Works with state names or abbreviations
state_data <- data.frame(
  state = c("Ohio", "PA", "Michigan"),
  population = c(11.8, 13.0, 10.1)
)
spatial_data <- auto_geocode_data(state_data)


# Works with FIPS codes
county_data <- data.frame(
  fips = c("39049", "39035", "39113"),
  unemployment = c(4.2, 5.1, 4.8)
)
county_sf <- auto_geocode_data(county_data)

# Works with HUC codes (any format!)
watershed_data <- data.frame(
  HUC_8 = c("04100009", "04100012"),  # or HUC-8, huc8, Huc 8, etc.
  water_quality = c(72, 65)
)
huc_sf <- auto_geocode_data(watershed_data)

# Works with ZIP codes
zip_data <- data.frame(
  zip = c("43215", "44113", "45202"),
  median_income = c(58000, 45000, 72000)
)
zip_sf <- auto_geocode_data(zip_data)

# Preview what will be detected before geocoding
preview_geocoding(my_data)

Supported geographic entities: - ✅ States (names or abbreviations) - ✅ Counties - ✅ FIPS codes - ✅ HUC watershed codes (HUC-8, HUC_8, huc8, etc.) - ✅ ZIP codes - ✅ City names

Column name flexibility: The package handles any naming convention - HUC_8, HUC-8, huc8, State, STATE, state_name, etc.

📖 Documentation

• https://exelegch.github.io/geospatialsuite-docs/

Function Reference

# View all available functions
help(package = "geospatialsuite")

# Auto-geocoding functions
?auto_geocode_data
?preview_geocoding

# Test function availability
test_function_availability()

# Run basic package tests
test_geospatialsuite_package_simple()

# Run minimal functionality test
test_package_minimal(verbose = TRUE)

🎯 Real-World Examples

Census Data Analysis (No Coordinates Needed!)

# Load census data with just state names - no coordinates!
census_data <- data.frame(
  state = c("California", "Texas", "Florida", "New York"),
  population_millions = c(39.5, 29.1, 22.2, 20.2),
  median_income = c(75000, 64000, 59000, 72000),
  unemployment_rate = c(4.8, 4.1, 3.2, 4.3)
)

# Auto-geocode and visualize
census_sf <- auto_geocode_data(census_data, verbose = TRUE)
quick_map(census_sf, variable = "median_income", 
          title = "Median Household Income by State")

Watershed Analysis with HUC Codes

# Water quality data with HUC-8 codes (no coordinates!)
watershed_data <- data.frame(
  HUC_8 = c("04100009", "04100012", "04110002", "05120201"),
  basin_name = c("Great Miami", "Mill Creek-Cincinnati", 
                 "Middle Ohio", "Upper Wabash"),
  nitrogen_mg_l = c(2.3, 3.1, 1.8, 2.7),
  phosphorus_mg_l = c(0.08, 0.12, 0.06, 0.09)
)

# Auto-geocode watersheds
huc_sf <- auto_geocode_data(watershed_data, verbose = TRUE)

# Comprehensive water quality analysis
water_results <- analyze_water_quality_comprehensive(
  water_data = huc_sf,
  variable = "nitrogen_mg_l",
  thresholds = list(
    Normal = c(0, 2), 
    Elevated = c(2, 5),
    High = c(5, Inf)
  )
)

quick_map(huc_sf, variable = "nitrogen_mg_l",
          title = "Nitrogen Levels by Watershed")

Agricultural Monitoring Crop Codes

# Get crop codes for analysis
corn_codes <- get_comprehensive_cdl_codes("corn")
grain_codes <- get_comprehensive_cdl_codes("grains")

County-Level Environmental Analysis

# County data with FIPS codes (no coordinates needed!)
county_data <- data.frame(
  fips = c("39049", "39035", "39113", "39061"),
  county_name = c("Franklin", "Cuyahoga", "Montgomery", "Hamilton"),
  air_quality_index = c(45, 52, 48, 41),
  tree_canopy_pct = c(28, 35, 32, 40)
)

# Auto-geocode counties
county_sf <- auto_geocode_data(county_data, verbose = TRUE)

Analyse crop vegetation

red <- load_sample_data("sample_red.rds")
nir <- load_sample_data("sample_nir.rds")
blue <- load_sample_data("sample_blue.rds")

spectral_stack <- c(red, nir, blue)

names(spectral_stack) <- c("red", "nir", "blue")

result <- analyze_crop_vegetation(
  spectral_data = spectral_stack,
  crop_type = "corn",
  analysis_type = "comprehensive"
)

# Structure:
result$vegetation_indices      # SpatRaster with calculated indices
result$analysis_results        # Detailed analysis results
result$metadata                # Processing metadata

Crop Classification Methodology

analyze_crop_vegetation() classifies vegetation stress, growth stage, and yield potential using literature-informed thresholds across multiple indices:

• Stress detection applies independent thresholds to each available index (NDVI, EVI, GNDVI, SIPI). NDVI stress ranges (healthy ≥ 0.6, moderate stress 0.4–0.6, severe stress < 0.4) follow Tucker (1979) and Hatfield et al. (2008). EVI and GNDVI thresholds are similarly derived from Hatfield et al. (2008).

• Growth stage is predicted from mean NDVI using crop-specific cutoffs consistent with Anyamba et al. (2021), who applied explicit per-crop NDVI thresholds for large-scale crop monitoring with MODIS and crop mask data — the same conceptual approach used here. The MODIS + CDL crop monitoring framework follows Akanbi et al. (2024).

• Yield potential uses a composite score averaging up to five normalized indices (NDVI, EVI, GNDVI, DVI, RVI), consistent with the multi-index approach of Bolton & Friedl (2013) and Mkhabela et al. (2011).

Note: Thresholds are literature-informed starting points. Exact NDVI boundaries vary by region, cultivar, sensor, and season. Calibration with local ground truth data is recommended.

References: - Tucker (1979). Remote Sensing of Environment, 8(2), 127–150. https://doi.org/10.1016/0034-4257(79)90013-0

• Hatfield et al. (2008). Agronomy Journal, 100(S3), S-117–S-131. https://doi.org/10.2134/agronj2006.0370c

• Anyamba et al. (2021). Remote Sensing, 13(21), 4227. https://doi.org/10.3390/rs13214227

• Akanbi et al. (2024). Journal of Geovisualization and Spatial Analysis, 8, 9 https://doi.org/10.1007/s41651-023-00164-y

• Bolton & Friedl (2013). Agricultural and Forest Meteorology, 173, 74–84. https://doi.org/10.1016/j.agrformet.2013.01.007

• Mkhabela et al. (2011). Agricultural and Forest Meteorology, 151(3), 385–393. https://doi.org/10.1016/j.agrformet.2010.11.012

🌟 What Makes geospatialsuite Special

1. Auto-Geocoding Revolution

No more manual coordinate lookups! Work directly with: - State names, county names, FIPS codes - HUC watershed codes (any format) - ZIP codes, city names - Flexible column naming (HUC_8, HUC-8, huc8 all work!)

2. Universal Design

Works with any spatial data combination - no need to learn different functions for different data types. The universal_spatial_join() function automatically handles: - Vector-to-vector joins - Vector-to-raster extractions
- Raster-to-raster operations - Multi-dataset integrations

3. Intelligent Automation

• Auto-detects coordinate columns (lat/lng, x/y, longitude/latitude)
• Auto-geocodes geographic entities (states, counties, FIPS, HUCs, ZIPs)
• Automatically identifies satellite bands across Landsat, Sentinel-2, MODIS
• Smart coordinate system transformations with validation
• Optimal method selection for performance and accuracy

4. Efficient Visualization

• Terra-based plotting using reliable terra::plot() and terra::plotRGB()
• Quick mapping with quick_map() function for instant visualization
• Multiple color schemes: viridis, plasma, ndvi, terrain, categorical
• Interactive mapping with automatic leaflet integration when available

5. Comprehensive Coverage

• 60+ vegetation indices including latest research developments
• Complete spatial operations through universal_spatial_join()
• Robust error handling with informative messages and recovery strategies
• Cross-platform compatibility (Windows, macOS, Linux)

6. Research-Ready

Designed specifically for reproducible research with: - Comprehensive testing suite (test_geospatialsuite_package_simple()) - Function availability checking (test_function_availability()) - Quality control and filtering options - Integration with modern R spatial ecosystem

⚡ Performance

geospatialsuite is optimized for:

• Large rasters: Efficient memory usage with terra backend
• Multiple datasets: Parallel processing capabilities for vegetation indices
• Cross-platform: Tested on Windows, macOS, and Linux
• Any geographic region: Universal coordinate system handling
• Big data: Streaming and chunked processing for large satellite imagery
• Interactive analysis: Fast visualization without data conversion overhead
• Geocoding: Efficient caching and batch processing for large datasets

For realistic satellite imagery (5K×5K pixels):

• 7.6× more memory efficient than ggplot2 (75 MB vs 572 MB)
• 4.2× faster execution (684 ms vs 2,897 ms)

Performance Tips

# Test basic functionality
test_package_minimal(verbose = TRUE)

# Check which functions are available
test_function_availability(verbose = TRUE)

📊 Supported Vegetation Indices

🛠 System Requirements

Required Dependencies

# Core dependencies (automatically installed with geospatialsuite)
# These are listed in DESCRIPTION Imports and will be installed automatically
terra (>= 1.6-17)
sf (>= 1.0-0)
dplyr (>= 1.0.0)
ggplot2 (>= 3.3.0)
magrittr
viridis
leaflet          # Interactive web mapping
rnaturalearth    # Natural Earth country boundaries
tigris           # US Census boundaries (states, counties, FIPS)
# Plus: graphics, grDevices, htmlwidgets, mice, parallel, 
#       RColorBrewer, stats, stringr, tools, utils

Optional Enhancement Packages

# These packages provide additional functionality but are not required
# Install them separately for enhanced capabilities

# Raster visualization enhancements
install.packages(c(
  "tidyterra",    # Efficient raster visualization with ggplot2
  "RStoolbox"     # Remote sensing tools and visualization
))

# Figure composition and animation
install.packages(c(
  "patchwork",    # Multi-panel figures and layouts
  "gganimate"     # Animated visualizations
))

# Extended geocoding capabilities (listed in DESCRIPTION Suggests)
install.packages(c(
  "nhdplusTools",  # HUC watershed boundaries
  "zipcodeR",      # ZIP code centroids
  "tidygeocoder"   # City name geocoding
))

Minimum R Version

• R >= 3.5.0 (recommended: R >= 4.0.0)

📄 Citation

If you use geospatialsuite in your research, please cite:

citation("geospatialsuite")

📧 Contact

• Maintainer: Olatunde D. Akanbi (olatunde.akanbi@case.edu)
• Senior Maintainer: Roger H. French (roger.french@case.edu)
• Lead Developer: Olatunde D. Akanbi (olatunde.akanbi@case.edu)
• Issues & Bug Reports: https://github.com/cwru-sdle/geospatialsuite/issues

📝 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

• Development Institution: Solar Durability and Lifetime Extension (SDLE) Center, Case Western Reserve University, Cleveland, Ohio, U.S.A.
• Built on: The excellent work of the terra, sf, ggplot2, and broader R spatial community
• Funding: This material is based upon financial support by the National Science Foundation, EEC Division of Engineering Education and Centers, NSF Engineering Research Center for Advancing Sustainable and Distributed Fertilizer production (CASFER), NSF 20-553 Gen-4 Engineering Research Centers award 2133576.

Contributing Institutions

• Case Western Reserve University
• NSF Engineering Research Center for Advancing Sustainable and Distributed Fertilizer production (CASFER)

Special Thanks

• R Core Team and CRAN maintainers
• terra package developers (Robert J. Hijmans et al.)
• sf package developers (Edzer Pebesma et al.)
• Remote sensing and geospatial R community
• geocoding package developers (tigris, nhdplusTools, zipcodeR, tidygeocoder)