man/mantel.test.Rd

   1 \name{mantel.test}
   2 \alias{mantel.test}
   3 \title{Mantel Test for Similarity of Two Matrices}
   4 \usage{
   5 mantel.test(m1, m2, nperm = 1000, graph = FALSE,
   6             alternative = "two.sided",  ...)
   7 }
   8 \arguments{
   9   \item{m1}{a numeric matrix giving a measure of pairwise distances,
  10     correlations, or similarities among observations.}
  11   \item{m2}{a second numeric matrix giving another measure of pairwise
  12     distances, correlations, or similarities among observations.}
  13   \item{nperm}{the number of times to permute the data.}
  14   \item{graph}{a logical indicating whether to produce a summary graph
  15     (by default the graph is not plotted).}
  16   \item{alternative}{a character string defining the alternative
  17     hypothesis:  \code{"two.sided"} (default),  \code{"less"},
  18     \code{"greater"}, or any unambiguous abbreviation of these.}
  19   \item{\dots}{further arguments to be passed to \code{plot()} (to add a
  20     title, change the axis labels, and so on).}
  21 }
  22 \description{
  23   This function computes Mantel's permutation test for similarity of two
  24   matrices. It permutes the rows and columns of the two matrices
  25   randomly and calculates a \eqn{Z}-statistic.
  26 }
  27 \details{
  28   The function calculates a \eqn{Z}-statistic for the Mantel test, equal to
  29   the sum of the  pairwise product of the lower triangles of the
  30   permuted matrices, for each permutation of rows and columns. It
  31   compares the permuted distribution with the \eqn{Z}-statistic observed
  32   for the actual data.
  33
  34   If \code{graph = TRUE}, the functions plots the density estimate of
  35   the permutation distribution along with the observed \eqn{Z}-statistic
  36   as a vertical line.
  37
  38   The \code{\dots} argument allows the user to give further options to
  39   the \code{plot} function: the title main be changed with \code{main=},
  40   the axis labels with \code{xlab =}, and \code{ylab =}, and so on.
  41 }
  42 \value{
  43   \item{z.stat}{the \eqn{Z}-statistic (sum of rows*columns of lower
  44     triangle) of the data matrices.}
  45   \item{p}{\eqn{P}-value (quantile of the observed \eqn{Z}-statistic in
  46     the permutation distribution).}
  47   \item{alternative}{the alternative hypothesis.}
  48 }
  49 \references{
  50   Mantel, N. (1967) The detection of disease clustering and a
  51   generalized regression approach. \emph{Cancer Research}, \bold{27},
  52   209--220.
  53
  54   Manly, B. F. J. (1986) \emph{Multivariate statistical methods: a primer.}
  55   London: Chapman & Hall.
  56 }
  57 \author{
  58   Original code in S by Ben Bolker \email{bolker@zoo.ufl.edu}, ported
  59   to \R by Julien Claude \email{claude@isem.univ-montp2.fr}
  60 }
  61 \examples{
  62 q1 <- matrix(runif(36), nrow = 6)
  63 q2 <- matrix(runif(36), nrow = 6)
  64 mantel.test(q1, q2, graph = TRUE,
  65             main = "Mantel test: a random example with 6 X 6 matrices",
  66             xlab = "z-statistic", ylab = "Density",
  67             sub = "The vertical line shows the observed z-statistic")
  68 }
  69 \keyword{multivariate}