R: ML fitting of species rank-abundance distributions

fitrad {sads} | R Documentation

## ML fitting of species rank-abundance distributions

### Description

Fits probability distributions for abundance ranks of species in a sample or assemblage by maximum likelihood.

### Usage

    fitrad(x, rad =c("gs", "mand", "rbs", "zipf"), ...)
    fitgs(x, trunc, start.value, ...)
    fitmand(x, trunc, start.value, ...)
    fitrbs(x, trunc, ...)
    fitzipf(x, N, trunc, start.value, upper = 20, ...)

### Arguments

`x` | vector of (positive integer) quantiles or an object of `rad-class`. In the context of rads, the numerical vector contains abundances of species in a sample or ecological assemblage according to their abundance. The `rad-class` object contains ranked abundances of species in a sample or ecological assemblage.
`rad` | character; root name of community rad distribution to be fitted. `"gs"` for geometric series (not geometric distribution, `dgeom`), `"mand"` for Zipf-Mandelbrodt distribution, `"rbs"` for MacArthur's Broken-stick distribution, `"zipf"` for Zipf distribution.
`trunc` | non-negative integer, `trunc > min(x)`; truncation point to fit a truncated distribution.
`N` | positive integer, total number of individuals in the sample/assemblage.
`start.value` | numeric named vector; starting values of free parameters to be passed to `mle2`. Parameters should be named as in the corresponding density function, and in the same order.

`upper` | real positive; upper bound for the Brent's one-parameter optimization method (default), for fits that use this method by default. See details and `optim`.
`...` | in fitrad further arguments to be passed to the specific fitting function (most used are `trunc` and `start.value` ). In the specific fitting functions further arguments to be passed to `mle2`.

### Details

All these functions fit rank-abundance distributions (RAD) to a vector of abundances or a rank-abundance table of the `rad-class`. RADs assign probabilities p(i) to each rank i, which can be interpreted as the expected proportion of total individuals in the sample that are of the i-th species.

`fitrad` is simply a wrapper that calls the specific functions to fit the distribution chosen with the argument `rad`. Users can interchangeably use `fitrad` or the individual functions detailed below (e.g. `fitrad(x, sad="rbs", ...)` is the same as `fitrbs(x, ...)` and so on).

The distributions are fitted by the maximum likelihood method using numerical optimization, with `mle2`. The resulting object is of `fitrad-class` which can be handled with `mle2` methods for fitted models and has also some additional methods for RADs models (see `fitrad-class` and examples). By default, fitting to one-parameter distributions (`fitgs`, `fitzipf`) uses Brent's one-dimensional method of optimization (see `optim`).

`fitgs` fits Motomura's Geometric Series (Whittaker 1965, May 1975) to abundance ranks. This was the first model fitted to species abundance data (Motomura 1932, apud Doi and Mori 2012), which was subsequently described as the result of niche pre-emption at a constant rate (Numata et. al. 1953 apud Doi and Mori 2012). The initial guess for parameter `k` is given by the expression 1 - (nmin/nmax)^(1/(S-1)) (He & Tang, 2008).

`fitrbs` fits the Broken-stick distribution (MacArthur 1960) to abundance ranks. It is defined only by the observed number of elements `S` in the collection and collection size `N`. Therefore, once a sample is taken, the Broken-stick has no free parameters. Therefore, there is no actual fitting, but still the `fitrbs` calls `mle2` with fixed parameters N and S and `eval.only=TRUE` to return an object of `fitrad-class` to keep compatibility with other RAD models fitted to the same data. Therefore the resulting objects allows most of the operations with RAD models, such as comparison with other models through model selection, diagnostic plots and so on (see fitrad-class).

`fitzipf` and `fitmand` fit the Zipf distribution and its two-parameter generalization, the Zipf-Mandelbrodt distribution. Both are discrete power-law distributions commonly proposed as RAD models, though they in general provide poor fit to species abundances (Newman 2005).

### Value

An object of `fitrad-class` which inherits from `mle2-class` and thus has methods for handling results of maximum likelihood fits from `mle2` and also specific methods to handle rank-abundance models.

### Author(s)

Paulo I Prado prado@ib.usp.br, Andre Chalom and Murilo Dantas Miranda

### Source

all fitting functions builds on `mle2` and methods from 'bbmle' package (Bolker 2012), which in turn builds on `mle` function and associated classes and methods.

### References

Bolker, B. and R Development Core Team 2012. bbmle: Tools for general maximum likelihood estimation. R package version 1.0.5.2. http://CRAN.R-project.org/package=bbmle

Doi, H. and Mori, T. 2012. The discovery of species-abundance distribution in an ecological community. Oikos 122: 179–182.

He, F. and Tang, D. 2008. Estimating the niche preemption parameter of the geometric series. Acta Oecologica 33: 105–107.

MacArthur, R.H. 1960. On the relative abundance of species. Am Nat 94:25–36.

May, R.M. 1975. Patterns of Species Abundance and Diversity. In Cody, M.L. and Diamond, J.M. (Eds) Ecology and Evolution of Communities. Harvard University Press. pp 81–120.

Newman, M.E.J. 2005. Power laws, Pareto distributions and Zipf's law. Contemporary Physics, 46: 323–351.

Whittaker, R.H. 1965. Dominance and diversity in land plant communities. Science 147: 250–260.

### See Also

`dgs`, `dmand`, `drbs`, `dzipf`, for corresponding density functions created for fitting RADs; `fitrad-class`.

### Examples

    ## Figure 2 of Motomura (1932)
    data(okland)
    plot(rad(okland))
    ok.gs <- fitrad(okland, "gs")
    lines(radpred(ok.gs))

    ## Comparison with Zipf-Mandelbrodt
    ok.zm <- fitrad(okland, "mand")
    AICctab(ok.gs, ok.zm, nobs=length(okland))
    lines(radpred(ok.zm), col="red")

[Package sads version 0.4.2 Index]