spread() and spread2() implement similar contagious spread processes, but
they are separate implementations with different argument names and,
importantly, different output column names. Code cannot be switched from
one to the other simply by renaming the function. This topic documents the
correspondences; it is referenced from the help of both functions.
spread and spread2Which to use. spread2() is the more robust of the two: its behaviour is
better tested, it can be called iteratively (passing its own output back in as
start), and more combinations of its arguments work as documented.
spread() is generally faster, sometimes substantially so, but several of its
argument combinations are untested, deprecated, or unimplemented.
Argument correspondence. Arguments with the same name in both functions generally mean the same thing, with the exceptions noted below.
spread | spread2 | Notes |
loci | start | In spread2, start may also be the data.table
or raster returned by a previous spread2 call. |
persistence | persistProb | Default 0 vs NA (NA behaves as 0). |
returnIndices | asRaster | spread returns a raster when
returnIndices = FALSE, a data.table when 1/TRUE, and a bare vector
of pixel indices when 2. spread2 returns a raster when
asRaster = TRUE (the default) and a data.table when FALSE; it has no
equivalent of returnIndices = 2. |
exactSizes | exactSize | Different types. spread's exactSizes
is a logical that reinterprets maxSize as exact; spread2's exactSize
is itself the numeric vector of target sizes. |
spreadState | start | spread takes previous state in a dedicated
argument; spread2 takes it as start, carrying state in its attributes. |
quick, skipChecks | skipChecks | spread accepts either name. |
relativeSpreadProb | spreadProbRel | Different mechanisms: a logical rescaling flag vs an actual surface of relative weights. |
allowOverlap | allowOverlap | Logical in spread; numeric 0:3
in spread2 (logical accepted for back-compatibility). |
maxSize | maxSize | spread has default 1e8; spread2 has no
default and distinguishes supplied from missing. |
mask, mapID, lowMemory | – | Not present in spread2; all three
are unimplemented or deprecated in spread as well. |
id, stopRule, stopRuleBehavior, circleMaxRadius | – | No equivalent in spread2. |
| – | returnDirections, returnFrom, oneNeighbourOnly,
maxRetriesPerID | No equivalent in spread. |
Output column names. This is the most common source of errors when
converting code. The returned data.tables share no column names:
| Meaning | spread(returnIndices = TRUE) | spread2(asRaster = FALSE) |
| Cell touched by the spread | indices | pixels |
| Cell the event started from | initialLocus | initialPixels |
| Whether the cell can still spread | active (logical) | state
(character: "activeSource", "successful", "inactive", "holding",
"tooSmall") |
| Event identifier | id | not in the main table; see
attr(out, "spreadState")$clusterDT$id |
| Distance from origin | dists (only with circle/allowOverlap) | distance (with returnDistances) |
| Source of the previous step | – | from (with returnFrom) |