radfit                 package:vegan                 R Documentation

_R_a_n_k - _A_b_u_n_d_a_n_c_e _o_r _D_o_m_i_n_a_n_c_e / _D_i_v_e_r_s_i_t_y _M_o_d_e_l_s

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

     Functions construct rank - abundance or dominance / diversity or
     Whittaker plots and fit pre-emption, log-Normal, veiled
     log-Normal, Zipf and Zipf - Mandelbrot models of species
     abundance.

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

     ## S3 method for class 'data.frame':
     radfit(df, ...)
     ## S3 method for class 'radfit.frame':
     plot(x, order.by, BIC = FALSE, model, legend = TRUE,
          as.table = TRUE, ...)
     ## Default S3 method:
     radfit(x, ...)
     ## S3 method for class 'radfit':
     plot(x, BIC = FALSE, legend = TRUE, ...)  
     rad.preempt(x, family = poisson, ...)
     rad.lognormal(x, family = poisson, ...)
     rad.veil(x, family = poisson, ...)
     rad.zipf(x, family = poisson, ...)
     rad.zipfbrot(x, family = poisson, ...)
     ## S3 method for class 'radline':
     plot(x, xlab = "Rank", ylab = "Abundance", type = "b", ...)
     ## S3 method for class 'radline':
     lines(x, ...)
     ## S3 method for class 'radline':
     points(x, ...)
     as.rad(x)
     ## S3 method for class 'rad':
     plot(x, xlab = "Rank", ylab = "Abundance", ...)

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

      df: Data frame where sites are rows and species are columns.

       x: A vector giving species abundances in a site, or an object to
          be plotted.

order.by: A vector used for ordering sites in plots.

     BIC: Use Bayesian Information Criterion, BIC, instead of Akaike's
          AIC. The penalty for a parameter is k = log(S) where S is the
          number of species, whereas AIC uses k = 2.

   model: Show only the specified model. If missing, AIC is used to
          select the model. The model names (which can be abbreviated)
          are 'Preemption', 'Lognormal', 'Veiled.LN', 'Zipf',
          'Mandelbrot'. 

  legend: Add legend of line colours.

as.table: Arrange panels starting from upper left corner (passed to
          'xyplot').

  family: Error distribution (passed to 'glm'). All alternatives
          accepting 'link = "log"' in 'family' can be used, although
          not all make sense.

xlab,ylab: Labels for 'x' and 'y' axes.

    type: Type of the plot, '"b"' for plotting both observed points and
          fitted lines, '"p"' for only points, '"l"' for only fitted
          lines, and '"n"' for only setting the frame. 

     ...: Other parameters to functions. 

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

     Rank - Abundance Dominance (RAD) or Dominance/Diversity plots
     (Whittaker 1965) display logarithmic species abundances against
     species rank order in the community. These plots are supposed to
     be effective in analysing types of abundance distributions in
     communities. These functions fit some of the most popular models
     following Wilson (1991). Function 'as.rad' constructs observed RAD
     data. Functions 'rad.XXXX' (where 'XXXX' is a name) fit the
     individual models, and function 'radfit' fits all models.  The
     argument of the function 'radfit' can be either a vector for a
     single community or a data frame where each row represents a
     distinct community. All these functions have their own 'plot'
     functions. When the argument is a data frame, 'plot' uses
     'Lattice' graphics, and other functions use ordinary graphics. The
     ordinary graphics functions return invisibly an 'ordiplot' object
     for observed points, and function 'identify.ordiplot' can be used
     to label selected species. The most complete control of graphics
     can be achieved with 'rad.XXXX' methods which have 'points' and
     'lines' functions to add observed values and fitted models into
     existing graphs.  

     Function 'rad.preempt' fits the niche preemption model, a.k.a.
     geometric series or Motomura model, where the expected abundance a
     of species at rank r is a[r] = J*alpha*(1-alpha)^(r-1). The only
     estimated parameter is the preemption coefficient alpha which
     gives the decay rate of abundance per rank. In addition there is a
     fixed scaling parameter J which is the total abundance.  The niche
     preemption model is a straight line in a RAD plot. Function
     'rad.lognormal' fits a log-Normal model which assumes that the
     logarithmic abundances are distributed Normally, or a[r] =
     exp(log(mu) + log(sigma) * N), where N is a Normal deviate. 
     Function 'rad.veil' is similar, but it assumes that only a
     proportion 'veil' of most common species were observed in the
     community, the rest being too rare or scanty to occur in a sample
     plot of this size (but would occur in a larger plot). Function
     'rad.zipf' fits the Zipf model a[r] = J*p1*r^gamma where p1 is the
     fitted proportion of the most abundant species, and gamma is a
     decay coefficient. The Zipf - Mandelbrot  model ('rad.zipfbrot')
     adds one parameter: a[r] = J*c*(r+beta)^gamma after which p1 of
     the Zipf model changes into a meaningless scaling constant c.
     There are great histories about ecological mechanisms behind each
     model (Wilson 1991), but several alternative and contrasting
     mechanisms can produce similar models and a good fit does not
     imply a specific mechanism.

     Log-Normal and Zipf models are generalized linear models ('glm')
     with logarithmic link function. Veiled log-Normal and Zipf -
     Mandelbrot add one nonlinear parameter, and these two models are
     fitted using 'nlm' for the nonlinear parameter and estimating
     other parameters and log-Likelihood with 'glm'. Pre-emption model
     is fitted as purely nonlinear model.  The default 'family' is
     'poisson' which is appropriate only for genuine counts (integers),
     but other families that accept 'link = "log"' can be used. Family
     'Gamma' may be appropriate for abundance data, such as cover. The
     ``best'' model is selected by 'AIC'. Therefore ``quasi'' families
     such as 'quasipoisson' cannot be used: they do not have 'AIC' nor
     log-Likelihood needed in non-linear models.

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

     Function 'rad.XXXX' will return an object of class 'radline',
     which is constructed to resemble results of 'glm' and has many
     (but not all) of its components, even when only 'nlm' was used in
     fitting. At least the following 'glm' methods can be applied to
     the result: 'fitted', 'residuals.glm'  with alternatives
     '"deviance"' (default), '"pearson"', '"response"', function
     'coef', 'AIC', 'extractAIC', and 'deviance'. Function 'radfit'
     applied to a vector will return an object of class 'radfit' with
     item 'y' for the constructed RAD, item 'family' for the error
     distribution, and item 'models' containing each 'radline' object
     as an item. In addition, there are special 'AIC', 'coef' and
     'fitted' implementations for 'radfit' results.  When applied to a
     data frame 'radfit' will return an object of class 'radfit.frame'
     which is a list of 'radfit' objects. The functions are still
     preliminary, and the items in the 'radline' objects may change.

_N_o_t_e:

     The RAD models are usually fitted for proportions instead of
     original abundances. However, nothing in these models seems to
     require division of abundances by site totals, and original
     observations are used in these functions. If you wish to use
     proportions, you must standardize your data by site totals, e.g.
     with 'decostand' and use appropriate 'family' such as 'Gamma'.

     The lognormal model is fitted in a standard way, but I do think
     this is not quite correct - at least it is not equivalent to
     fitting Normal density to log abundances like originally suggested
     (Preston 1948). 

     Some models may fail. In particular, 'rad.veil' often tends to
     'veil = 0' meaning that none of the community is present, and the
     function prints an error message 'Error: NA/NaN/Inf in foreign
     function call (arg 1)'. The error is caught and 'NA' are returned.

     Wilson (1991) defined preemption model as a[r] = J*p1*(1 -
     alpha)^(r-1), where p1 is the fitted proportion of the first
     species. However, parameter p1 is completely defined by alpha
     since the fitted proportions must add to one, and therefore I
     handle preemption as a one-parameter model.

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

     Jari Oksanen

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

     Preston, F.W. (1948) The commonness and rarity of species.
     _Ecology_ 29, 254-283.

     Whittaker, R. H. (1965) Dominance and diversity in plant
     communities. _Science_ 147, 250-260.

     Wilson, J. B. (1991) Methods for fitting dominance/diversity
     curves. _Journal of Vegetation Science_ 2, 35-46.

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

     'fisherfit' and 'prestonfit'. An alternative approach is to use
     'qqnorm' or  'qqplot' with any distribution. For controlling
     graphics: 'Lattice', 'xyplot', 'lset'.

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

     data(BCI)
     mod <- rad.veil(BCI[1,])
     mod
     plot(mod)
     mod <- radfit(BCI[1,])
     plot(mod)
     # Take a subset of BCI to save time and nerves
     mod <- radfit(BCI[2:5,])
     mod
     plot(mod, pch=".")

