coalesce: Coalesce
In CJBarry/coalesce: Coalesce a field of weighted points

Description Usage Arguments Value Examples

View source: R/coalesce.R

Organise a field of weighted particles by grouping clusters.

1
2
3

coalesce(xyzm, cdh, cdv = cdh, mm = 0, subregions = TRUE, nppsr = 256L,
  TwoD = FALSE, na.rep = FALSE, maxnp = Inf, maxbymm = TRUE,
  print.timings = FALSE)

`xyzm`	data.table, or object coercible to one; 4- (or 3- if `TwoD`) columns, with rows representing individual particles and columns giving the x, y and z (if not `TwoD`) co-ordinates and the mass (or weight) of the particles (as with return value from `test.points`)
`cdh, cdv`	numeric [1]; horizontal and vertical search radii for finding nearby particles; the search region around each particle is a circle (`TwoD`) or an ellipsoid with circular horizontal section
`mm`	numeric [1]; minimum mass for resulting particles: particles below this mass are coalesced with the nearest particle even if outside the search radius
`subregions`	logical [1]; use subregions? Highly recommended for vast performance increases: will sort particles into rectangular subregions before coalescing so that particle distances will only be calculated between particles in the same subregion, with the sacrifice that the occasional grouping will be missed for particle pairs straddling subregion boundaries. Automatically switches off for data sets that are too small to benefit.
`nppsr`	integer [1]; if using subregions, how many particles should there be in each subregion, at least; 256 highly recommended as generally the best compromise
`TwoD`	logical [1]; set to `TRUE` if data set is 2D (i.e. no z column)
`na.rep`	logical [1]; rows which contain NAs are removed prior to coalescing; set `na.rep = TRUE` if these rows should be replaced after coalescing
`maxnp`	integer [1] or `Inf`; maximum number of particles in the result; the lightest particles that exceed this limit are forced to coalesce with their nearest neighbours, irrespective of the distance
`maxbymm`	not used
`print.timings`	logical [1]; put `TRUE` if you would like to see a print out of the timings of the various sections of this function

a data.table with columns:
..$x,y,z (num): z only if not TwoD
..$m (num): mass/ weight

library(graphics)
library(data.table)

tps <- test.points(100L, TRUE)

# total mass and centre of mass
sum(tps$m)
tps[, lapply(list(x = x, y = y), weighted.mean, m)]

# plot original points - size represents mass
plot(tps[, .(x, y)], cex = tps$m*2, pch = 16L)

cps1 <- coalesce(tps, 5, TwoD = TRUE)
cps2 <- coalesce(tps, 10, TwoD = TRUE)

# total mass and centre of mass should be unchanged
sum(cps1$m)
cps1[, lapply(list(x = x, y = y), weighted.mean, m)]
sum(cps2$m)
cps2[, lapply(list(x = x, y = y), weighted.mean, m)]

points(cps1[, .(x, y)], cex = cps1$m*2, pch = 16L, col = "red")
points(cps2[, .(x, y)], cex = cps2$m*2, pch = 16L, col = "blue")
points(tps[, .(x, y)], cex = tps$m*2)

legend("bottom", legend = c("original", "cdh = 5", "cdh = 10"),
       ncol = 3L, col = c("black", "red", "blue"), pch = 16L,
       bg = "white")