divcmax                 package:ade4                 R Documentation

_M_a_x_i_m_a_l _v_a_l_u_e _o_f _R_a_o'_s _d_i_v_e_r_s_i_t_y _c_o_e_f_f_i_c_i_e_n_t _a_l_s_o _c_a_l_l_e_d 
_q_u_a_d_r_a_t_i_c _e_n_t_r_o_p_y

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

     For a given dissimilarity matrix, this function calculates the 
     maximal value of Rao's diversity coefficient over all frequency 
     distribution. It uses an optimization technique based on Rosen's 
     projection gradient algorithm and is verified using the 
     Kuhn-Tucker conditions.

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

     divcmax(dis, epsilon, comment)

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

     dis: an object of class 'dist' containing distances  or
          dissimilarities among elements.

 epsilon: a tolerance threshold : a frequency is non null  if it is
          higher than epsilon.

 comment: a logical value indicating whether or not  comments on the
          optimization technique should be printed.

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

     Returns a list  

   value: the maximal value of Rao's diversity coefficient.

 vectors: a data frame containing four frequency  distributions : sim
          is a simple distribution which is equal  to D1/1^tD1, pro is
          equal to  z/1^tz1, where z is the nonnegative  eigenvector of
          the matrix containing the squared dissimilarities  among the
          elements, met is equal to z^2, num is a frequency  vector
          maximizing Rao's diversity coefficient.

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

     Stphane Champely Stephane.Champely@univ-lyon1.fr
      Sandrine Pavoine pavoine@biomserv.univ-lyon1.fr

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

     Rao, C.R. (1982) Diversity and dissimilarity coefficients:  a
     unified approach. _Theoretical Population Biology_,  *21*, 24-43.

     Gini, C. (1912) Variabilit e mutabilit.  _Universite di Cagliari
     III_, Parte II.

     Simpson, E.H. (1949) Measurement of diversity.  _Nature_, *163*,
     688.

     Champely, S. and Chessel, D. (2002) Measuring biological diversity
      using Euclidean metrics. _Environmental and Ecological
     Statistics_,  *9*, 167-177.

     Pavoine, S., Ollier, S. and Pontier, D. (in revision)  Measuring
     diversity from dissimilarities with Rao's quadratic entropy:  are
     any dissimilarities suitable? _Theoretical Population Biology_.

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

     par.safe <- par()$mar
     data(elec88)
     par(mar = c(0.1, 0.1, 0.1, 0.1))
     # Departments of France.
     area.plot(elec88$area)

     # Dissimilarity matrix.
     d0 <- dist(elec88$xy)

     # Frequency distribution maximizing spatial diversity in France
     # according to Rao's quadratic entropy.
     France.m <- divcmax(d0)
     w0 <- France.m$vectors$num
     v0 <- France.m$value
     (1:94) [w0 > 0]

     # Smallest circle including all the 94 departments.
     # The squared radius of that circle is the maximal value of the
     # spatial diversity.
     w1 = elec88$xy[c(6, 28, 66), ]
     w.c = apply(w1 * w0[c(6, 28, 66)], 2, sum)
     symbols(w.c[1], w.c[2], circles = sqrt(v0), inc = FALSE, add = TRUE)
     s.value(elec88$xy, w0, add.plot = TRUE)
     par(mar = par.safe)

     ## Not run: 
     # Maximisation of Rao's diversity coefficient
     # with ultrametric dissimilarities.
     data(microsatt)
     mic.genet <- count2genet(microsatt$tab)
     mic.dist <- dist.genet(mic.genet, 1)
     mic.phylog <- hclust2phylog(hclust(mic.dist))
     plot.phylog(mic.phylog)
     mic.maxpond <- divcmax(mic.phylog$Wdist)$vectors$num
     dotchart.phylog(mic.phylog, mic.maxpond)
     ## End(Not run)

