A restricted null model for the events of node_test() that keeps the shape of each side
and the distances between the sides. Each permutation moves all the sites of an event
together, by a rotation or a reflection and a translation. A move is kept when its sites
land inside the landscape: within gap of a site, or in a hole between sites, but not
beyond an edge. Sites that land where there is no site, as in a hole of a sparse
landscape, go to the nearest free site within twice gap, and a fraction outside of the
sites of an event may land beyond the landscape and be brought in the same way. Moves are
never carried across the landscape, as in a torus, which would split a side. This is the
torus-translation test of Harms et al. (2001) without the wrap-around.
Usage
rigid_permutations(
coords,
biogeography,
n_perm = 999,
gap = NULL,
outside = 0.1,
independent = Inf,
max_tries = 20 * n_perm
)Arguments
- coords
Matrix or data frame with the two coordinates of each site, in the order of the rows of
biogeography. Distances are Euclidean, so they should be projected.- biogeography
Matrix of biogeographic events with one row per site and values of 1, -1 and 0, as given to
node_test().- n_perm
Largest number of permutations. Fewer are returned when fewer distinct placements of the event exist.
- gap
A moved site counts as inside the landscape when it is closer than
gapto a site, or in a hole narrower than twicegapbetween sites (four timesgapoff a lattice, where sites leave larger voids between neighbours), but not beyond an edge. A site that lands inside but not on a site goes to the nearest free site within twicegap. The default is the median distance from a site to its fourth nearest site: the step of a full grid, where it makes a site just beyond the edge count as outside, and the spacing of sparse sites, so that holes count as inside. It is not thegapofpatch_permutations(), which is 1.5 times this one by default.- outside
Largest fraction of the sites of an event that may land outside the landscape in a move. Those sites go to the nearest free site within twice
gap, and the move is dropped when one has none.- independent
Distance beyond which parts of an event move independently of each other, while staying at least that far apart. The default,
Inf, moves the whole event together and assumes nothing about the range of autocorrelation.- max_tries
Largest number of moves tried: of the enumerated moves of one part, in random order, when placements fail or repeat a layout, or of the combinations of several independent parts, which cannot all be enumerated.
Value
List with one integer matrix per event, each with one permutation per row and the
names of the sites as column names, for area_permutations in node_test(). Rows only
move the sites of that event, so they should not be used as site_permutations.
Details
The moves are enumerated, so the permutations are distinct placements of the event, up to
the sign of the contrast, which does not change the test, and drawn at random when there
are more than n_perm. Sites on a regular lattice get all the moves of the lattice: its
symmetries with every translation in cells. Other coordinates get rotations in steps that
move the site farthest from the centre of the event by about gap, at least 4 and at most
360 of them, each with and without a reflection, and the translations that put the site
nearest the centre on each site of the landscape; the other sites go to the nearest free
sites. Which moves fit is then fixed by the landscape, and only the draw among them
changes between runs. In an event without zeros where one side has up to a third of the
sites, only that side moves and the other is the rest of the landscape, as when one area
is compared with all the others.
An event that spans the landscape, as two halves, two strips along opposite edges or areas
in opposite corners, has few placements, sometimes none, because a move would push a side
out. The function then returns fewer rows than n_perm, with a warning, or stops. The
smallest p-value in node_test() is 1 / (rows + 1), so with fewer than 19 rows no node can
reach the 5% level. This is a limit of the event, not of the function: a permutation test
that keeps the shape of two halves has almost nothing to permute.
With independent, parts of the event farther apart than that distance move independently
of each other, but keep at least that distance between them. This gives placements to sides
far apart, as across a barrier, at the price of assuming that the community is not spatially
autocorrelated beyond independent. When that assumption fails the test is liberal, and no
value of independent can be checked from the data alone, so results should be compared
across values. A large part in an irregular region may have few moves that fit. It then
stays nearly in place while the small parts move, which gives many placements that say
little, and the function warns.
This method was built for this package and has no published evaluation. In
data-raw/validation_rigid.R, with communities that followed a hidden autocorrelated
environment and areas without effect, 150 replicates and 199 permutations, the default
rejected 3.7% to 4.7% of the tests at the 5% level with areas placed at random in a square
of 20 by 20 sites and in a strip of 50 by 8. With areas fixed in the square, it rejected
2.2% to 3.5% for adjacent areas and for several small areas, and 4.2% to 4.8% for adjacent
areas, an L shape and two areas at a short distance when the hidden environment had an
exponential covariance. patch_permutations() rejected 1.4% to 6.4% in those cases, and is
conservative for adjacent areas. Where the event had room to move, power was equal to or
higher than that of patch_permutations(), up to twice for adjacent areas (24% against 13%);
with few placements it was lower (4% against 13% for blocks in the band).
With sparse sites (data-raw/validation_gap.R, 150 replicates and 99 permutations), the
default rejected 5.5% to 6.1% where the event had room to move: irregular areas with 40% of
the sites of the square, adjacent areas with 60% and random blocks with 80%. Areas in
opposite corners with 25% to 40% of the sites, and irregular areas on seven clusters of
sites, had no placement or fewer than five, so the default does not test them.
Off a lattice (data-raw/validation_offgrid.R, 150 replicates and 99 permutations), the
default rejected 4.7% for adjacent areas in the square with jitter and 5.9% in 400 sites
placed at random, and 6.8% to 8.0% for two blocks placed at random in those landscapes, in
the band with jitter and in a crescent of random sites, where it is liberal.
patch_permutations() rejected 1.2% to 6.3% in those cases. With a second generator in an
L-shaped region of random sites (data-raw/validation_nulls_check.R, 150 replicates and 199
permutations), it rejected 7.0% for two fixed areas and 8.7% for areas placed at random,
against 5.5% and 6.6% with patch_permutations(). Off a lattice this function is thus
liberal, and patch_permutations() is the safer choice unless its conservatism for
adjacent areas matters. Power for adjacent areas with jitter was 23% against 12%. With 400 sites, the enumeration and 99 placements took 0.3 to
2.8 s; with 750 sites placed at random and an event of 57 sites, 999 placements took 9 s,
and with 750 sites on a lattice with jitter and an event of 225 sites, 701 placements took
12 min, since every site of a large event has to be moved to a free site in each try.
Sides far apart remain a problem. In an irregular band most random areas had no placement
or fewer than 20, so the default does not test them. With independent = 10, random areas
in the three landscapes gave 3.9% to 5.5%, but areas in opposite corners of the square gave
6% to 7% with autocorrelation over 3 or 4 sites and 12% over 12 sites, strips along opposite
edges 8% to 9% (2% to 3% with patch_permutations()), and areas in opposite corners with
sparse sites 10% to 12%.
References
Harms, K. E., Condit, R., Hubbell, S. P., & Foster, R. B. (2001). Habitat associations of trees and shrubs in a 50-ha neotropical forest plot. Journal of Ecology, 89, 947–959.
See also
patch_permutations() moves each patch on its own, and torus_permutations()
gives a torus. biogeography_matrix() codes the events.
Other restricted null models:
patch_permutations(),
torus_permutations()
Examples
coords <- expand.grid(x = 1:10, y = 1:6)
event <- ifelse(coords$x <= 3 & coords$y <= 3, 1, ifelse(coords$x >= 5 & coords$x <= 6, -1, 0))
permutations <- rigid_permutations(coords, cbind(barrier = event), n_perm = 3)
# where the first permutation places the two sides
matrix(event[permutations$barrier[1, ]], 10)
#> [,1] [,2] [,3] [,4] [,5] [,6]
#> [1,] 0 0 0 0 0 0
#> [2,] 0 0 0 0 0 0
#> [3,] 0 0 0 0 0 0
#> [4,] 0 0 0 0 0 0
#> [5,] -1 -1 0 0 0 0
#> [6,] -1 -1 0 0 0 0
#> [7,] -1 -1 0 0 0 0
#> [8,] -1 -1 0 1 1 1
#> [9,] -1 -1 0 1 1 1
#> [10,] -1 -1 0 1 1 1
