Moran.I                 package:ape                 R Documentation

_M_o_r_a_n'_s _I _A_u_t_o_c_o_r_r_e_l_a_t_i_o_n _I_n_d_e_x

_D_e_s_c_r_i_p_t_i_o_n:

     Computes Moran's I autocorrelation index of a given vector 'x'
     according to a distance weights matrix 'dist' using the method
     described by Gittleman and Kot (1990).

_U_s_a_g_e:

       Moran.I(x, dist, scaled = FALSE, na.rm = FALSE)

_A_r_g_u_m_e_n_t_s:

       x: a numeric vector.

    dist: a distance weigths matrix.

  scaled: logical, indicate whether the index should be scaled to allow
          comparisons between indices (default to 'FALSE').

   na.rm: a logical value indicating whether 'NA' values in 'x'  should
          be stripped before the computation proceeds.

_D_e_t_a_i_l_s:

     The 'dist' matrix is used as distance weights, and Moran's I
     indice is computed using the formula:

 'I = n/S0 * (sum{i=1..n} sum{j=1..n} wij(yi - ym))(yj - ym) / (sum{i=1..n} (yi - ym)^2)'

     with

        *  yi = observations

        *  wij = distance weight

        *  n = number of observations

        *  S0 = 'sum_{i=1..n} sum{j=1..n} wij'

     The value of I may be evaluated under two null hypotheses,
     normality and randomization. Only the randomization hypothesis is
     implemented for now.

     The 'na.rm' option is forwarded to all 'sd', 'sum' and 'mean'
     functions used in computations. Note that 'NA' values are allowed
     only in 'x' and not in 'dist'.

_V_a_l_u_e:

     A list containing the attributes: 

observed: Moran's I index of 'x'.

expected: Expected value of I under the null hypothesis.

      sd: The standard deviation of I under the null hypothesis.

 p.value: The p-value of having the observed value under the null
          hypothesis.

_A_u_t_h_o_r(_s):

     Julien Dutheil julien.dutheil@univ-montp2.fr

_R_e_f_e_r_e_n_c_e_s:

     Gittleman, J. L. and Kot, M. (1990) Adaptation: statistics and a
     null model for estimating phylogenetic effects. _Systematic
     Zoology_, *39*, 227-241.

_S_e_e _A_l_s_o:

     'dist.phylo', 'discrete.dist', 'dist.taxo'

_E_x_a_m_p_l_e_s:

     ### This will draw the correlogram from Gittleman and Kot 1990
     ### This is only for example, consider function plot.correlogram()
     ### to draw correlograms.
     library(ape)
     data(carnivora)
     attach(carnivora)
     # Compute distance matrix for each taxonomic level:
     dG  <- dist.taxo(Genus)
     dF  <- dist.taxo(Family)
     dSF <- dist.taxo(SuperFamily) 
     dO  <- dist.taxo(Order)
     # We draw the correlogram of average body weights, 
     # with log10-transformed variable:
     IG  <- Moran.I(log10(SW), dG        , scale=TRUE)
     IF  <- Moran.I(log10(SW), dF  & !dG , scale=TRUE)
     ISF <- Moran.I(log10(SW), dSF & !dF , scale=TRUE)
     IO  <- Moran.I(log10(SW), dO  & !dSF, scale=TRUE)
     # All Moran's I indices:
     i <- c(IG$obs, IF$obs, ISF$obs, IO$obs)
     # With their corresponding p-values:
     p <- c(IG$p.v, IF$p.v, ISF$p.v, IO$p.v)
     # Here's the legend:
     l <- c("G", "F", "SF", "O")
     # Draw the correlogram (using lattice library):
     library(lattice)
     # New Black & White device:
     trellis.device(device=X11, new=FALSE, color=FALSE)
     # Black circles are significant at the 5
     pch <- ifelse(p < 0.05, 19, 21)
     # Plot it!
     xyplot(i~ordered(l,levels=l), type="b", xlab="Rank", ylab="I / Imax",
         lty=2, lwd=2, cex=1.5, pch=pch, ylim=c(-0.75,0.75))

