monmonier {adegenet} | R Documentation |
The Monmonier's algorithm detects boundaries by finding the path
exhibiting the largest differences (provided in a distance matrix)
between neighbouring objects.
The highest distance between two linked objects (i.e. neighbours) is found, giving the starting point of the path. Starting from this point, the algorithm seeks the highest distance between immediate neighbours, and so on until a threshold value is attained. It is recommended to choose this threshold from the barplot of sorted local differences: a boundary will likely be indicated by an abrupt decrease of these values.
When several paths are looked for, the previous paths are taken into account, and cannot be either crossed or redrawn. Monmonier's algorithm can be used to assess the boundaries between patches of homogeneous observations.
Although Monmonier algorithm was initially designed for Voronoi
tesselation, this function generalizes this algorithm to different
connection networks. The optimize.monmonier
function produces a
monmonier
object by trying several starting points, and
returning the best boundary (largest sum of local differences). This
is designed to avoid the algorithm to be trapped by a single strong
local difference inside an homogeneous patch.
monmonier(xy, dist, cn, threshold=NULL, nrun=1, skip.local.diff=rep(0,nrun),scanthres=is.null(threshold)) optimize.monmonier(xy, dist, cn, ntry=10, return.best=TRUE, display.graph=TRUE, threshold=NULL, scanthres=is.null(threshold)) ## S3 method for class 'monmonier': plot(x, variable=NULL, displayed.runs=1:x$nrun, add.arrows=TRUE, col='blue', lty=1, bwd=4, clegend=1, csize=0.7, method=c('squaresize','greylevel'), sub='', csub=1, possub='topleft', cneig=1, pixmap=NULL, contour=NULL, area=NULL, add.plot=FALSE, ...) ## S3 method for class 'monmonier': print(x, ...)
xy |
a matrix yielding the spatial coordinates of the objects, with two columns respectively giving X and Y |
dist |
an object of class dist , giving the distances between the objects |
cn |
a connection network of class nb (package spdep ) |
threshold |
a number giving the minimal distance between two neighbours crossed by the path; by default, this is the third quartile of all the distances between neighbours |
nrun |
is a integer giving the number of runs of the algorithm, that is, the number of paths to search, being one by default |
skip.local.diff |
is a vector of integers, whose length is the number of paths (nrun ); each integer gives the number of starting point to skip, to avoid being stuck in a local difference between two neighbours into an homogeneous patch; none are skipped by default |
scanthres |
a logical stating whether the threshold sould be chosen from the barplot of sorted distances between neighbours |
ntry |
an integer giving the number of different starting points tried. |
return.best |
a logical stating whether the best monmonier object should be returned (TRUE, default) or not (FALSE) |
display.graph |
a logical whether the scores of each try should be plotted (TRUE, default) or not |
x |
a monmonier object |
variable |
a variable to be plotted using s.value (package
ade4 ) |
displayed.runs |
an integer vector giving the rank of the paths to represent |
add.arrows |
a logical, stating whether arrows should indicate the direction of the path (TRUE) or not (FALSE, used by default) |
col |
a characters vector giving the colors to be used for each boundary; recycled is needed; 'blue' is used by default |
lty |
a characters vector giving the type of line to be used for each boundary; 1 is used by default |
bwd |
a number giving the boundary width factor, applying to every segments of the paths; 4 is used by default |
clegend |
like in s.value , the size factor of the legend if a variable is represented |
csize |
like in s.value , the size factor of the squares used to represent a variable |
method |
like in s.value , a character giving the method to be used to represent the variable, either 'squaresize' (by default) or 'greylevel' |
sub |
a string of characters giving the subtitle of the plot |
csub |
the size factor of the subtitle |
possub |
the position of the subtitle; available choices are 'topleft' (by default), 'topright', 'bottomleft', and 'bottomright' |
cneig |
the size factor of the connection network |
pixmap |
an object of the class pixmap displayed in the map background |
contour |
a data frame with 4 columns to plot the contour of the map: each row gives a segment (x1,y1,x2,y2) |
area |
a data frame of class 'area' to plot a set of surface units in contour |
add.plot |
a logical stating whether the plot should be added to the current one (TRUE), or displayed in a new window (FALSE, by default) |
... |
further arguments passed to other methods |
The function monmonier
returns a list of the class monmonier
, which contains the general informations about the algorithm, and about each run.
When displayed, the width of the boundaries reflect their strength.
Let a segment MN be part of the path, M being the middle of AB, N of CD.
Then the boundary width for MN is proportionnal to (d(AB)+d(CD))/2.
As there is no perfect method to display graphically a quantitative
variable (see for instance the differences between the two methods of
s.value
), the boundaries provided by this algorithm seem
sometimes more reliable than the boundaries our eyes perceive (or miss).
Returns an object of class monmonier
, which contains the following elements :
run1 (run2, ...) |
for each run, a list containing a dataframe giving the path coordinates, and a vector of the distances between neighbours of the path |
nrun |
the number of runs performed, i.e. the number of boundaries in the monmonier object |
threshold |
the threshold value, minimal distance between neighbours accounted for by the algorithm |
xy |
the matrix of spatial coordinates |
cn |
the connection network of class nb |
call |
the call of the function |
Thibaut Jombart jombart@biomserv.univ-lyon1.fr
Monmonier, M. (1973) Maximum-difference barriers: an alternative numerical regionalization method. Geographic Analysis, 3, 245–261.
Manni, F., Guerard, E. and Heyer, E. (2004) Geographic patterns of (genetic, morphologic, linguistic) variation: how barriers can be detected by "Monmonier's algorithm". Human Biology, 76, 173–190
## Not run: require(spdep) require(ade4) ### non-interactive example # est-west separation load(system.file("files/mondata1.rda",package="adegenet")) cn1 <- chooseCN(mondata1$xy,type=2,ask=F) mon1 <- monmonier(mondata1$xy,dist(mondata1$x1),cn1$cn,threshold=2) plot(mon1,mondata1$x1) plot(mon1,mondata1$x1,met="greylevel",add.arr=FALSE,col="red",bwd=6,lty=2) # square in the middle load(system.file("files/mondata2.rda",package="adegenet")) cn2 <- chooseCN(mondata2$xy,type=1,ask=F) mon2 <- monmonier(mondata2$xy,dist(mondata2$x2),cn2$cn,threshold=2) plot(mon2,mondata2$x2,method="greylevel",add.arr=FALSE,bwd=6,col="red",csize=.5) ### interactive example # est-west separation xy <- matrix(runif(120,0,10), ncol=2) x1 <- rnorm(60) x1[xy[,1] > 5] <- x1[xy[,1] > 5]+4 cn1 <- chooseCN(xy,type=2,ask=F) mon1 <- optimize.monmonier(xy,dist(x1),cn1$cn,ntry=6) # graphics plot(mon1,x1) plot(mon1,x1,met="greylevel") # square in the middle x2 <- rnorm(60) sel <- (xy[,1]>3.5 & xy[,2]>3.5 & xy[,1]<6.5 & xy[,2]<6.5) x2[sel] <- x2[sel]+4 cn2 <- chooseCN(xy,type=1,ask=F) mon2 <- optimize.monmonier(xy,dist(x2),cn2$cn,ntry=6) # graphics plot(mon2,x2,method="greylevel",add.arr=F,bwd=6,col="red",csize=.5) ## End(Not run)