Description Details Warnings Author(s) References See Also Examples

This help file provides more information regarding the distributions i.e., the `family`

argument, available in the boral package, to handle various responses types.

A variety of families are available in boral, designed to accommodate multivariate abundance data of varying response types. Please see the `family`

argument in the `boral`

which lists all distributions that are currently available.

For multivariate abundance data in ecology, species counts are often overdispersed. Using a negative binomial distribution (`family = "negative.binomial"`

) to model the counts usually helps to account for this overdispersion. Please note the variance for the negative binomial distribution is parameterized as *Var(y) = μ + φμ^2*, where *φ* is the dispersion parameter.

For non-negative continuous data such as biomass, the lognormal, Gamma, and tweedie distributions may be used (Foster and Bravington, 2013). For the gamma distribution, the variance is parameterized as *Var(y) = μ/φ* where *φ* is the column-specific rate (henceforth referred to also as dispersion parameter).

For the tweedie distribution, a common power parameter is across all columns with this family, because there is almost always insufficient information to model column-specific power parameters. Specifically, the variance is parameterized as *Var(y) = φ μ^p* where *φ* is the column-specific dispersion parameter and *p* is a power parameter common to all columns assumed to be tweedie, with *1 < p < 2*.

Normal responses are also implemented, just in case you encounter normal stuff in ecology (pun intended)! For the normal distribution, the variance is parameterized as *Var(y) = φ^2*, where *φ* is the column-specific standard deviation.

The beta distribution can be used to model data between values between but *not* including 0 and 1. In principle, this would make it useful for percent cover data in ecology, if it not were for the fact that percent cover is commonly characterized by having lots of zeros (which are not permitted for beta regression). An *ad-hoc* fix to this would be to add a very small value to shift the data away from exact zeros and/or ones. This is however heuristic, and pulls the model towards producing conservative results (see Smithson and Verkuilen, 2006, for a detailed discussion on beta regression, and Korhonen et al., 2007, for an example of an application to forest canopy cover data). Note the parameterization of the beta distribution used here is directly in terms of the mean *μ* and the dispersion parameter *φ* (more commonly know as the "sample size"). In terms of the two shape parameters, if we denote the two shape parameters as the vector *(a,b)*, his is equivalent to *a = μφ* and *b = (1-μ)φ*.

For ordinal response columns, cumulative probit regression is used (Agresti, 2010). boral assumes all ordinal columns are measured using the same scale i.e., all columns have the same number of theoretical levels, even though some levels for some species may not be observed. The number of levels is then assumed to be given by the maximum value from all the ordinal columns of `y`

. Because of this, all ordinal columns then assumed to have the *same* cutoffs, *\bm{τ}*, while the column-specific intercept, *β_{0j}*, allows for deviations away from these common cutoffs. That is,

*Φ(P(y_{ij} ≤ k)) = τ_k + β_{0j} + …,*

where *Φ(\cdot)* is the probit function, *P(y_{ij} ≤ k)* is the cumulative probability of element *y_{ij}* being less than or equal to level *k*, *τ_k* is the cutoff linking levels *k* and *k+1* (and which are increasing in *k*), *β_{0j}* are the column effects, and *…* denotes what else is included in the model, e.g. latent variables and related coefficients. To ensure model identifiability, and also because they are interpreted as column-specific deviations from the common cutoffs, the *β_{0j}*'s are treated as random effects and drawn from a normal distribution with mean zero and unknown standard deviation.

The parameterization above is useful for modeling ordinal in ecology. When ordinal responses are recorded, usually the same scale is applied to all species e.g., level 1 = not there, level 2 = a bit there, level 3 = lots there, level 4 = everywhere! The quantity *τ_k* can thus be interpreted as this common scale, while *β_{0j}* allows for deviations away from these to account for differences in species prevalence. Admittedly, the current implementation of boral for ordinal data can be quite slow.

Finally, in the event different responses are collected for different columns, e.g., some columns of `y`

are counts, while other columns are presence-absence, one can specify different distributions for each column. Aspects such as variable selection, residual analysis, and plotting of the latent variables are, in principle, not affected by having different distributions. Naturally though, one has to be more careful with interpretation of the row effects *α_i* and latent variables *\bm{z}_i*, as different link functions will be applied to each column of `y`

. A situation where different distributions may prove useful is when `y`

is a species–traits matrix, where each row is a species and each column a trait such as specific leaf area. In this case, traits could be of different response types, and the goal perhaps is to perform unconstrained ordination to look for patterns between species on an underlying trait surface e.g., a defense index for a species (Moles et al., 2013).

MCMC with lots of ordinal columns take an especially long time to run! Moreover, estimates for the cutoffs in cumulative probit regression may be poor for levels with little data. Major apologies for this advance =(

Francis K.C. Hui <[email protected]>, with contributions from Wade Blanchard <[email protected]>

Maintainer: Francis Hui <[email protected]>

Agresti, A. (2010). Analysis of Ordinal Categorical Data. Wiley.

Foster, S. D. and Bravington, M. V. (2013). A Poisson-Gamma model for analysis of ecological non-negative continuous data. Journal of Environmental and Ecological Statistics, 20, 533-552.

Korhonen, L., et al. (2007). Local models for forest canopy cover with beta regression. Silva Fennica, 41, 671-685.

Moles et al. (2013). Correlations between physical and chemical defences in plants: Trade-offs, syndromes, or just many different ways to skin a herbivorous cat? New Phytologist, 198, 252-263.

Smithson, M., and Verkuilen, J. (2006). A better lemon squeezer? Maximum-likelihood regression with beta-distributed dependent variables. Psychological methods, 11, 54-71.

`boral`

for the main boral fitting function.

1 | ```
## Please see main boral function for examples.
``` |

Embedding an R snippet on your website

Add the following code to your website.

For more information on customizing the embed code, read Embedding Snippets.