Correlogram               package:ape               R Documentation

_C_o_m_p_u_t_e _a _c_o_r_r_e_l_o_g_r_a_m

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

     Compute a correlogram from taxonomic variables or from a
     phylogenetic tree with branch lengths. The first method relies on
     the 'dist.taxo' function, and the second relies on the
     'discrete.dist' function. Both methods send an object of class
     'correlogram' to be plotted by the 'plot.correlogram' method. For
     the 'correlogram.formula' function, if several 'y' are specified,
     an object of class 'correlogramList' (a list of 'correlogram'
     objects) is sent.

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

       correlogram.formula(formula, data = NULL, use="all.obs")
       correlogram.phylo(x, phy, nclass = NULL, breaks = NULL)

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

       x: a vector containing the data to plot

 formula: a formula of the kind 'y1+..+yn ~ g1/../gn', where 'y' are
          the data to plot and all 'g' are the nested levels.

    data: a dataframe containing all variables in the formula. If NULL,
          variables are taken from the environment.

     use: an optional character string giving a method for computing 
          Moran's indices in the presence of missing values.  This must
          be one of the strings '"all.obs"', '"complete.obs"' or
          '"pairwise.complete.obs"'. In the first case, 'NA' values
          produce an error. If the seond option is used, all lines
          including 'NA' will be ignored. In the later case, 'NA' will
          be removed separately for each correlogram. If only one 'y'
          is given in the formula, the two last options will send the
          same result. Finally, unless 'use' is set to '"all.obs'",
          lines width 'NA' values in grouping variables will be
          removed.

     phy: an object of class "phylo" width edge lengths

breaks,nclass: The class bounds or the number of classes to use. If
          both are NULL, compute Moran's I on the whole distance
          matrix.

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

     See example of the 'Moran.I' function to see how the
     'correlogram.formula' function works. To deal with phylogenies,
     the 'correlogram.phylo' function creates classes according to
     distances intervals. Such intervals may be specified using the
     'breaks' argument or by giving a number of classes ('nclass'
     argument).

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

     An object of class 'correlogram', containing: 

     obs: all measured Moran's I

p.values: the p-values of each I

  labels: the names of each level

     or an object of class 'correlogramList' containing a list of
     correlogram objects.

_W_a_r_n_i_n_g:

     'correlogram.phylo' will return NAs if void classes are used. This
     may happen if 'breaks' if not properly defined, or sometimes with
     the 'nclass=argument', depending on the tree used. Usually, you'll
     have to pull classes.

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

     Julien Dutheil julien.dutheil@univ-montp2.fr

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

     'plot.correlogram, plot.correlogramList'

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

       library(ape)
       data(carnivora)
       ### Using the formula interface:
       co <- correlogram.formula(
                             log10(SW) ~ Order/SuperFamily/Family/Genus,
                             data=carnivora)
       co
       plot(co)
             ### Several correlograms on the same plot:
       cos <- correlogram.formula(
                             log10(SW) + log10(FW) ~ Order/SuperFamily/Family/Genus,
                             data=carnivora)
       names(cos)
       plot(cos)

       ### Using the phylo interface:
       ### (the same analysis than in help(pic)...)

       cat("((((Homo:0.21,Pongo:0.21):0.28,",
          "Macaca:0.49):0.13,Ateles:0.62):0.38,Galago:1.00);",
          file = "ex.tre", sep = "\n")
       tree.primates <- read.tree("ex.tre")
       X <- c(4.09434, 3.61092, 2.37024, 2.02815, -1.46968)
       Y <- c(4.74493, 3.33220, 3.36730, 2.89037, 2.30259)
       ### Since this is a small tree, 2 classes is a reasonable number:
       coX <- correlogram.phylo(X, tree.primates, nclass=2)
       coY <- correlogram.phylo(Y, tree.primates, nclass=2)
       plot(coX)
       plot(coY)
       ### Nothing significant...
       ### Computing Moran's I on the whole matrix:
       coX2 <- correlogram.phylo(X, tree.primates); coX2
       ### Significant at the 5
       coY2 <- correlogram.phylo(Y, tree.primates); coY2
       ### Not significant
       unlink("ex.tre") # delete the file "ex.tre"   

