A comprehensive R package for creating hexagonal grids and applying spatial smoothing to satellite raster data. The package is specifically designed for hexagonal grid analysis, providing tools for extracting environmental variables from TIF files and applying Gaussian-weighted spatial smoothing using C++ optimization with chunking support for large datasets.
Features
Hexagonal Grid Creation: Create hexagonal grids from study areas (primary focus)
Spatial Topology: Compute neighbor relationships and distances for hexagonal grids
Raster Processing: Efficient extraction of values from TIF files
C++ Optimization: High-performance spatial smoothing algorithms
Custom Weights: Flexible Gaussian weight parameters
Multiple Formats: Support for various raster formats and projections
Flexible Grid Input: Accepts any sf POLYGON grid with proper structure
Installation
Prerequisites
Windows users: You need Rtools to compile C++ code. Install from https://cran.r-project.org/bin/windows/Rtools/
macOS users: Install Xcode Command Line Tools: xcode-select --install
Linux users: Install build-essential: sudo apt-get install build-essential (Ubuntu/Debian) or equivalent for your distribution.
Install hexsmoothR
# Install from GitHub
devtools::install_github("MaxMLang/hexsmoothR")
# Or install from local source
install.packages("hexsmoothR_0.1.0.tar.gz", repos = NULL, type = "source")Quick Start
library(hexsmoothR)
library(sf)
library(terra)
# Create hexagonal grid
hex_grid <- create_grid(study_area, cell_size = 20000, type = "hexagonal")
# Compute spatial topology
topology <- compute_topology(hex_grid)
# Extract raster data
raster_files <- c(ndvi = "path/to/ndvi.tif", elevation = "path/to/elevation.tif")
extracted_data <- extract_raster_data(raster_files, study_area, cell_size = 20000)
# Apply spatial smoothing
smoothed_results <- smooth_variables(
variable_values = list(ndvi = extracted_data$data$ndvi, elevation = extracted_data$data$elevation),
neighbors = topology$neighbors,
weights = topology$weights,
var_names = c("ndvi", "elevation")
)Exported Functions
hexsmoothR exports the following public functions:
-
create_grid- Create hexagonal or square grids from study areas -
compute_topology- Compute neighbor relationships and spatial weights -
extract_raster_data- Extract values from raster files to grid cells -
smooth_variables- Apply spatial smoothing with C++ optimization -
find_hex_cell_size_for_target_cells- Calculate optimal cell size for target number of cells -
get_utm_crs- Get appropriate UTM CRS for a study area -
hex_flat_to_edge- Convert between hexagon measurements -
hex_edge_to_flat- Edge length to flat-to-flat distance -
hex_flat_to_circumradius- Flat-to-flat to circumradius conversion -
hex_circumradius_to_flat- Circumradius to flat-to-flat conversion
Note: Internal C++ and R fallback functions are not exported and should not be called directly.
Grid Compatibility
hexsmoothR works with any hexagonal grid that has the required structure:
- Uber H3 grids from Python/R
- Custom hexagonal grids
- Square grids (for comparison)
Required grid structure:
Output
The smoothing results contain: - raw - Weighted average of center cell and all neighbors - neighbors_1st, neighbors_2nd, etc. - Mean of neighbors at each order - weighted_combined - Final weighted average (recommended for analysis)
Advanced Usage
Multiple Variables
raster_files <- c(ndvi = "path/to/ndvi.tif", elevation = "path/to/elevation.tif")
extracted_data <- extract_raster_data(raster_files, study_area, cell_size = 20000)
smoothed_results <- smooth_variables(
variable_values = list(ndvi = extracted_data$data$ndvi, elevation = extracted_data$data$elevation),
neighbors = topology$neighbors,
weights = topology$weights,
var_names = c("ndvi", "elevation")
)Custom Weights
topology <- compute_topology(hex_grid, neighbor_orders = 3, center_weight = 1.0)Grid Requirements
hexsmoothR works with any hexagonal grid that follows the required structure. You can use grids created with:
- Uber H3 grids from Python, R, or any programming language
- Custom hexagonal grids created with any GIS software
- Grids from other packages (as long as they follow the structure below)
Required grid structure:
grid <- st_sf(
geometry = st_sfc(polygons, crs = your_crs),
grid_id = unique_identifiers, # Character vector
grid_index = 1:length(polygons) # Numeric sequence
)Example with H3 grids from Python:
import h3
import geopandas as gpd
from shapely.geometry import Polygon
# Create H3 hexagons in Python
h3_hexes = h3.polygon_to_cells(polygon, resolution=8)
geometries = [Polygon(h3.cell_to_boundary(hex_id)) for hex_id in h3_hexes]
# Convert to GeoDataFrame with required structure
gdf = gpd.GeoDataFrame({
'grid_id': h3_hexes,
'grid_index': range(len(h3_hexes))
}, geometry=geometries, crs='EPSG:4326')Tip: Use projected CRS (UTM) for real-world analysis with cell sizes in meters.
Performance
- C++ Optimization: High-performance spatial smoothing
- Memory Efficient: Chunking support for large datasets
- Scalable: From small areas to continental scales
Implementation Details
hexsmoothR uses Rcpp for high-performance spatial smoothing algorithms with automatic fallback to R implementation if needed.
Dependencies
- Rcpp: C++ integration
- sf: Spatial data handling
- terra: Raster processing
- exactextractr: Efficient raster extraction
- data.table: Fast data manipulation
Windows-Specific Notes
Important for Windows users: hexsmoothR contains C++ code that must be compiled during installation. This requires:
- Rtools: Download and install from CRAN Rtools page
- Restart R/RStudio after installing Rtools
-
Verify installation: Run
Sys.which("make")- it should return a path, not""
Contributing
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests
- Submit a pull request
Support
For issues and questions: - Check the vignettes: vignette("hexsmoothR-complete-guide", package = "hexsmoothR") - Run examples: example(create_grid) - Report bugs on GitHub