Skip to contents

Raster-based Clustering and Interpolation of Bioregional Data

Source: R/map_bioreg.R
map_bioreg.Rd

map_bioreg performs clustering (k-means, PAM, hierarchical, GMM) on spatial point data, computes modal or user-specified interpolation (none, nearest-neighbour, TPS), aligns cluster labels by overlap, and returns both data tables and raster stacks.

Usage

map_bioreg(
  data,
  scale_cols,
  method = c("kmeans", "pam", "hclust", "gmm", "all"),
  k_override = NULL,
  x_col = "x",
  y_col = "y",
  interpolate = c("none", "nn", "tps", "all"),
  res = 0.5,
  crs = "EPSG:4326",
  plot = TRUE,
  bndy_fc = NULL
)

Arguments

data

A single data.frame of point observations or a named list of such data.frames (e.g. different scenarios). Each data.frame must contain coordinate columns and variables to scale.

scale_cols

Character vector of column names in data to standardize before clustering.

method

Character vector of clustering methods to apply; choices of "kmeans", "pam", "hclust", "gmm", or "all".

k_override

Integer. If provided, fixes the number of clusters rather than computing via silhouette.

x_col, y_col

Strings giving the names of the longitude (x) and latitude (y) columns for spatial mapping.

interpolate

One of "none", "nn", "tps", or "all"; selects which interpolation(s) to compute.

res

Numeric resolution of output rasters (in the same units as coordinates).

crs

Coordinate reference system string for raster outputs (e.g. "EPSG:4326").

plot

Logical; if TRUE, displays spatial tile plots of clusters/modes.

bndy_fc

Optional sf or SpatVector polygon to overlay.

Value

A named list with elements:

none, nn, tps

Named lists of Terra SpatRaster stacks for each scenario, each layer labelled "algn".

table

A data.frame: original points, cluster columns, modal label, aligned labels.

plots

List of ggplot objects (invisible) when plot = TRUE.

methods

Character vector of methods actually computed.

Details

Internally, the function standardizes scale_cols, runs requested clustering(s), computes a modal consensus label, and then aligns each algorithm's cluster numbers to the k-means reference by maximal cell overlap. Three interpolation functions (fill_none_full, fill_nn_full, fill_tps_full) generate rasters of raw and aligned labels. Progress bars display per scenario.

Examples

library(terra)
#> terra 1.8.54
#> 
#> Attaching package: 'terra'
#> The following object is masked from 'package:data.table':
#> 
#>     shift
#> The following object is masked from 'package:dissmapr':
#> 
#>     distance
# simulate a single data.frame
set.seed(42)
df = data.frame(
    centroid_lon = runif(100, 16, 33),
  centroid_lat = runif(100, -35, -22),
  pred_zetaExp = rnorm(100)
)
# single scenario clustering
out1 = map_bioreg(
    data = df,
  scale_cols = c("pred_zetaExp", "centroid_lon", "centroid_lat"),
  method = "all",
  k_override = 4,
  x_col = "centroid_lon",
  y_col = "centroid_lat",
  plot = FALSE
)
#> Error in mclustBIC(data = structure(c(1.42500198156474, 1.25223173123877, -1.01277564712797, 2.14114384940439, -0.640684202191608, 0.213451855866909, -0.370252126137209, -0.0385616956618058, 0.304893618544566, 0.22854535835652, 0.0690035194680168, 0.216281971303301, -0.440127378342562, -0.460899823078016, -1.74039087331004, -0.326098926187757, -0.470226713148478, 3.08499927446928, -1.40972111104754, 0.248558397677997, -1.55516756646404, -1.52952058066436, 0.234674080299275, -1.00550988266733, 0.0947396592628603, -0.376891337867333, -0.581954544554465, -2.14250258127473, -1.25779421303962, 0.295297459154071, 0.724533813860986, -0.448358229387473, 0.0968249872354595, 1.33865159751676, 1.68921051835681, -1.11663305686187, -0.0329979277615648, 1.42559149817746, -0.42275720035449, 0.0387251127984306, 0.00152228402834981, -0.88500191329479, -0.395057234983017, 0.0641899211488864, -0.360976215637644, 1.32814076124865, -0.435214168645632, -0.382321878544181, 0.867473168700306, -1.07156941195287, 0.051743642204758, -1.61922579491483, 1.38762439312945, -0.20589188519517, -0.420673246538466, -1.2727298167313, 0.0881707659856616, -0.788342548339344, -0.493277677599128, 1.52090156984004, -0.0973730809494067, -1.0886169922443, 0.277259374680054, -0.304426857242128, 0.749300025912522, 1.68098884968814, -1.00114498631681, 0.5995906562211, 0.190651195462595, 1.08723519163892, -0.157375134147761, 1.02204138607828, -1.83324559414596, 1.96526723529782, 1.05318464440946, -0.0700001482911058, -1.50582091416637, 0.807911730248399, 0.631159337505421, 0.0897262277387866, 0.264262987243151, -0.549258789956428, 0.504649186050365, 0.422637946142987, -0.212100507472859, -1.38109875569194, 0.871771283748231, 0.709687137209726, -0.828184916370853, -1.66683097010332, 0.323436017087302, -0.284905784216986, 0.376139531174712, -1.33438848642184, -0.964070171212413, 1.29760329411449, 0.543323368196809, 0.745400319582511, 2.10436611356538, 0.239229668617277, 1.2927018047919, 1.36645440884402, -0.789341491044275, 1.01332016918376, 0.388368860804637, -0.0178269694551352, 0.702473086670307, -1.29099572226881, 0.438863738395999, 0.598072176734, -0.221022212958755, 0.644595150945317, 1.3584955055275, -0.891050470141084, -0.20594987286038, 1.37618827100665, 1.50274001320452, -1.34789061292702, -0.163875391478843, 0.118742731308582, 1.25701786045401, -1.27760406117871, 1.53806178900997, 1.398224297573, -1.46396997694758, -0.0340025448927582, -0.444698330291005, 1.26267032332214, -0.256697851029099, 1.03172285527975, 0.705809114117909, 0.949095349814472, -0.451637246778279, 0.532182926162171, -1.72391376365096, 1.0214952960874, -1.71270050681474, -1.04925660601112, 1.26552935880686, 0.289123344695232, -0.479950312475272, -0.293783985396605, -1.6130244165281, 1.48721902362094, -0.307098697847277, 1.43435106112419, 1.20311274648677, 0.382517668249462, 1.47869665278645, 0.312503495299336, -0.632732242048426, -0.588615090478728, -0.417269850471862, 0.861787395991114, -1.60803857866693, 0.742900962321515, 0.506042901732553, -1.16978986208959, -0.872308301986603, -0.0333363671226376, 0.500513599406342, 1.51794391033081, 0.778499544569806, 0.139129355372199, 1.07704691322894, -1.1094825520771, -0.838531995470323, 1.00573889954093, 0.558793867073618, -0.940344186804071, -1.59461799060686, -1.27174565885734, -1.02035601993658, -0.149298382366828, -1.08319843719284, 0.645401869034932, -1.71087703433865, -0.493427105867764, -0.0333536759591991, -1.73178860726239, 0.189189742379639, -1.21403314601285, -0.547945496427581, 0.401239864194928, 0.832413313340876, 0.129718486879759, -0.963001618106906, -1.43898890122912, -1.45345651621162, -0.72615543088478, 0.473420226435697, -1.73619884514983, -1.04623957177734, 1.35307031376739, 1.32859786893341, 0.694213310942711, -0.633908700081621, -0.0311823619513204, 0.726935440144908, 0.313566704484165, 0.375248745993074, -1.06897494845687, -1.07105922376164, -0.462505075206842, 1.49158281371143, 1.56272761821127, 0.776331890633083, 0.75299847078804, 0.0558081158422806, -1.82759385216953, 0.31414578206902, 1.11858645698017, 0.817521516893924, -0.237316074923222, 0.0559094504781332, 0.0615110664300311, -1.83074335931667, -0.579991948308473, 0.325427510052698, 1.09083990067435, -0.576263735086117, -0.385931381146957, 0.188953989005632, 0.246154192642406, 0.705025872313472, -0.441224050393289, 1.40949588895235, 1.56259445262058, -1.01119780516766, 0.722113865656846, 1.35453040082296, 0.294858166589097, 0.393825301095739, 1.47368448193465, 1.16688588805457, 0.21135407758054, 1.06422737217205, -1.43415142061265, 0.863363839093898, 0.365957255344197, -1.31154933896198, -1.55225634441142, -0.197289010481803, 0.91582630286437, 0.753994220320717, 1.0494935173384, -1.23488464166124, 1.49957776894947, -0.799022490259433, -1.30934129487674, 0.704041959210739, -0.691480492713116, 0.91385402566806, -0.443102351267694, 0.560053968825627, 0.903317843993465, -1.17237422922395, -1.7329350236311, -1.35650064841677, 0.565601248166316, 1.46463655542293, 0.107820076869366, 0.288828856036733, -1.14015819258492, 0.0539558123710868, -1.20172312743781, -0.240299498874827, -0.71630805387901, -1.42548065783121, -1.17861196451208, 0.74058642457087, -0.381564527593187, -0.373876794292102, -0.139954042514329, -0.326411964688541, -1.3537591068429, 1.07579098062496, 0.255424683491826, 0.968883325306435, 0.879337509823689, 1.40544476723548, 1.20976917592442, -0.716583823791281, -0.920336938480948, 0.784844180879046, 0.802830144980073, 1.40490680067258, 0.96462653739955, -1.36491764060615, -0.819760097176518, -1.14834276578669, 0.93256448613828, -1.38065403448021, -1.37988751796275, -1.58053925456655, -1.64805240645314, 0.042086151650662, -1.43913051514919, 0.788096581125319, 0.746183377462555), dim = c(100L, 3L), dimnames = list(    NULL, c("pred_zetaExp", "centroid_lon", "centroid_lat")), "`scaled:center`" = c(pred_zetaExp = -0.0874837071722478, centroid_lon = 24.9161387025146, centroid_lat = -28.2406083335332), "`scaled:scale`" = c(pred_zetaExp = 0.904173537608661, centroid_lon = 5.13309721725938, centroid_lat = 3.68235157902991)), G = k): could not find function "mclustBIC"

# simulate multiple scenarios
df2 = df
df2$centroid_lon = df2$centroid_lon + 5
scen_list = list(current = df, future = df2)
out2 = map_bioreg(
    data = scen_list,
  scale_cols = c("pred_zetaExp", "centroid_lon", "centroid_lat"),
  method = "kmeans",
  k_override = 3,
  x_col = "centroid_lon",
  y_col = "centroid_lat",
  plot = FALSE
)