[R] Mantel's randomization test

[ben@zoo.ufl.edu]

 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
  permutations instead.
}
\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
  instead of taking a sample.

  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
> posted in your message.
> 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
_._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._