betta: Modelling total diversity with betta

View source: R/model_betta.R

bettaR Documentation

Modelling total diversity with betta

Description

This function tests for heterogeneity of total diversity (observed plus unobserved) across multiple sites. It can account or test for fixed effects that may explain diversity. It returns the significance of the covariates in explaining diversity and a hypothesis test for heterogeneity.

Usage

betta(
  chats = NULL,
  ses,
  X = NULL,
  initial_est = NULL,
  formula = NULL,
  data = NULL,
  p.digits = 3
)

Arguments

chats

A vector of estimates of total diversity at different sampling locations. breakaway estimates are suggested in the high-diversity case but not enforced.

ses

The standard errors in chats, the diversity estimates. This can either be a vector of standard errors (with the arguments chats and X), or the name of the variable in the dataframe data that contains the standard errors (with the arguments formula and data).

X

A numeric matrix of covariates. If not supplied, an intercept-only model will be fit. This is optional with the chats argument.

initial_est

(Optional) A vector of length 1 + ncol(X) giving the starting values for the likelihood maximisation search. The first element is the starting estimate for sigma^2_u, and the remaining elements are the starting elements for beta. Defaults to NULL, in which case the starting values outlined in the paper are used.

formula

A formula object of the form y ~ x | group. Required with the data argument.

data

A dataframe containing the response, response standard errors, covariates, and grouping variable. Required with the formula argument.

p.digits

(Optional) A number that specifies the number of digits to which p-values will be rounded. The default value is 3 digits.

Value

table

A coefficient table for the model parameters. The columns give the parameter estimates, standard errors, and p-values, respectively. This model is only as effective as your diversity estimation procedure; for this reason please confirm that your estimates are appropriate and that your model is not misspecified. betta_pic may be useful for this purpose.

cov

Estimated covariance matrix of the parameter estimates.

ssq_u

The estimate of the heterogeneity variance.

homogeneity

The test statistic and p-value for the test of homogeneity.

global

The test statistic and p-value for the test of model explanatory power.

blups

The conditional expected values of the diversity estimates (conditional on the random effects). The authors propose that if the practitioner believes that information from one diversity estimator may inform the others, then using the condfits as estimators of total diversity rather than Chats may reduce variance of diversity estimates by “sharing strength” across the samples.

blupses

The estimated standard deviation (standard errors) in the blups.

loglikelihood

The log likelihood of the fitted model.

aic

The Akaike information criterion for the fitted model.

aicc

The finite sample correction of the Akaike information criterion for the fitted model.

r_squared_wls

The weighted R^2 statistic, appropriate for heteroskedastic linear models.

function.args

A list containing values initially passed to betta_random.

Note

Ecologists who are interested in the way species richness varies with covariate information often run a regression-type analysis on the observed diversity using their covariate information as predictors. However, in many settings (especially microbial), rare and unobserved taxa play a hugely important role in explaining the subtleties of the ecosystem, however, a regression analysis on the observed diversity level fails to account for these unobserved taxa. By predicting the total level of diversity (for example, via breakaway) and estimating the standard error in the estimate, one can take account of these unobserved, but important, taxa. In order to account for the estimated nature of the response, a mixed model approach is taken, whereby the varying levels of confidence in the estimates contributes to a diagonal but heteroscedastic covariance matrix. Given covariates constitute the fixed effects in the mixed model, and significance of the random effect term “sigsq_u” reflects heterogeneity in the sample, that is, variability that cannot be explained by only the covariates. The authors believe this to be the first attempt at modelling total diversity in a way that accounts for its estimated nature.

Author(s)

Amy Willis

References

Willis, A., Bunge, J., and Whitman, T. (2015). Inference for changes in biodiversity. arXiv preprint.

Willis, A. and Bunge, J. (2015). Estimating diversity via frequency ratios. Biometrics.

See Also

breakaway; breakaway_nof1; apples

Examples


















df <- data.frame(chats = c(2000, 3000, 4000, 3000), ses = c(100, 200, 150, 180),
                 Cont_var = c(100, 150, 100, 50))

# formula notation
betta(formula = chats ~ Cont_var, ses = ses, data = df)

# direct input
betta(c(2000, 3000, 4000, 3000), c(100, 200, 150, 180), cbind(1, c(100, 150, 100,
    50)))

## handles missing data
betta(c(2000, 3000, 4000, 3000), c(100, 200, 150, NA))

## A test for heterogeneity of apples diversity estimates vs butterfly estimates
betta(c(1552, 1500, 884), c(305, 675, 205), cbind(1, c(0, 0, 1)))























breakaway documentation built on Nov. 22, 2022, 5:08 p.m.