# [R] Mantel's randomization test

ben@zoo.ufl.edu ben at zoo.ufl.edu
Tue May 1 16:20:19 CEST 2001

 It's GPL.  I (Ben Bolker, bolker at zoo.ufl.edu) coded it from the
discussion in Manly's book in about 1992 or 1993.

However, it would be a really good idea if you, or I, or *somebody*,
tested it a bit more thoroughly before putting it in a public archive.

Here's a help file for it:

\name{mantel}
\alias{mantel}
\title{Mantel's permutation test}
\description{
Calculate Mantel's permutation test for similarity of two matrices.
Permutes the rows and columns of the two matrices randomly and
calculates a Z statistic.  If the number of samples requested is
greater than the total number of permutations, it enumerates
}
\usage{
mantel(m1, m2, nperm=250, graph=FALSE, rpt=FALSE)
}
\arguments{
\item{m1}{A numeric matrix representing distances, correlations, etc.}
\item{m2}{A second numeric matrix}
\item{nperm}{Number of permutations to sample}
\item{graph}{Produce a summary graph?}
\item{rpt}{Reporting frequency: if \code{rpt}<0, no reporting}
}
\details{
Calculates a Z-statistic for the Mantel test, equal to the sum of the
pairwise product of the lower triangles of the permuted matrices, for
each permutation of rows and columns.  Compares the permuted
distribution with the Z-statistic observed for the actual data.  If
the number of permutations requested is greater than the actual number
of possible permutations, this code enumerates all of the permutations

If \code{graph=TRUE}, plots the density estimate of the permutation
distribution along with the observed Z-statistic.
}
\value{
\item{z.stat}{the Z-statistic (sum of rows*columns of lower triangle)
of the data matrices}
\item{p}{p-value (quantile of the observed Z-statistic in the
permutation distribution)}
}
\references{
Bryan F.J. Manly, \emph{Multivariate statistical methods: a primer}
(Chapman & Hall, 1986)}
\author{Ben Bolker}
\note{TO DO:

\itemize{
\item{add normalized Z-stat (or option for it)}
\item{add asymptotic conf. limits/tests (Sokal and Rolf (\emph{Biometry}, 3d ed.) cite
Mantel (1967), "The detection of disease clustering ...",
\emph{Cancer Res.} 27:209-220, and suggest the asymptotic results should be OK
for matrices as small as 25x25)}
\item{add 3- or multi-way extensions of Mantel (S&R cite Smouse, Long, and
Sokal (1986) "Multiple regression and correlation extensions of the
Mantel test of matrix correspondence" \emph{Syst. Zool.} 35:627-632 and
Oden and Sokal (1992) "An investigation of three-matrix permutation
tests" \emph{J. Classif.} 9:275-290.)}}
}
\examples{
q1 <- matrix(runif(36),nrow=6)
q2 <- matrix(runif(36),nrow=6)
mantel(q1,q2,graph=TRUE,rpt=200)
}
\keyword{multivariate}

On Mon, 30 Apr 2001, Philippe Grosjean wrote:

> Hello,
>
>
> >  Years ago I coded this in S-PLUS ... I think it's been posted to the
> >S-news list before.  It seems to work just fine in R.  I have not tested
> >it at all, so it comes with the usual warranty (i.e., none).
>
> >  Just cut on the dotted lines and source() the file.
>
> >  One example (someday I'll package this all up and write a help file
> >etc.).
>
> >q1 _ matrix(runif(36),nrow=6)
> >q2 _ matrix(runif(36),nrow=6)
> >mantel(q1,q2,graph=TRUE,rpt=200)
>
>
> One of my jobs is to assemble a Splus/R library of statistical methods used
> in numerical oceanography. It will probably be distributed next year. I
> could be interested by inserting your Mantel test code if (1) it is public
> domain or GPL and (2) if you would like to give some indications of its
> origin (I mean, your name, email,...) which is not specified in the code you
> Sincerely,
>
> Philippe Grosjean
>
>
> ...........]<(({?<...............<?}))><...............................
>  ) ) ) ) )	 __               	 __
> ( ( ( ( ( 	|__)              	|  _
>  ) ) ) ) )	|   hilippe       	|__)rosjean
> ( ( ( ( ( 	Marine Biol. Lab., ULB, Belgium
>  ) ) ) ) )	                  	 __
> ( ( ( ( ( 	|\  /|            	|__)
>  ) ) ) ) )	| \/ |ariculture &	|__)iostatistics
> ( ( ( ( (
>  ) ) ) ) )	e-mail: phgrosje at ulb.ac.be or phgrosjean at sciviews.org
> ( ( ( ( ( 	SciViews project coordinator (http://www.sciviews.org)
>  ) ) ) ) )      tel: 00-32-2-650.29.70 (lab), 00-32-2-673.31.33 (home)
> ( ( ( ( (
>  ) ) ) ) )      "I'm 100% confident that p is between 0 and 1"
> ( ( ( ( (                                  L. Gonick & W. Smith (1993)
>  ) ) ) ) )
> .......................................................................
>
>
> -.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-
> r-help mailing list -- Read http://www.ci.tuwien.ac.at/~hornik/R/R-FAQ.html
> Send "info", "help", or "[un]subscribe"
> (in the "body", not the subject !)  To: r-help-request at stat.math.ethz.ch
> _._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._
>

--
318 Carr Hall                                bolker at zoo.ufl.edu
Zoology Department, University of Florida    http://www.zoo.ufl.edu/bolker
Box 118525                                   (ph)  352-392-5697
Gainesville, FL 32611-8525                   (fax) 352-392-3704

-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-
r-help mailing list -- Read http://www.ci.tuwien.ac.at/~hornik/R/R-FAQ.html
Send "info", "help", or "[un]subscribe"
(in the "body", not the subject !)  To: r-help-request at stat.math.ethz.ch
_._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._