trim: Estimate TRIM model parameters.

Description

Given some count observations, estimate a TRIM model and use these to impute the data set if nescessary.

Usage

trim(object, ...)
# S3 method for data.frame
trim(
  object,
  count_col = "count",
  site_col = "site",
  year_col = "year",
  month_col = NULL,
  weights_col = NULL,
  covar_cols = NULL,
  model = 2,
  changepoints = ifelse(model == 2, 1L, integer(0)),
  overdisp = FALSE,
  serialcor = FALSE,
  autodelete = TRUE,
  stepwise = FALSE,
  covin = list(),
  ...
)
# S3 method for formula
trim(object, data = NULL, weights = NULL, ...)
# S3 method for trimcommand
trim(object, ...)

Arguments

object

Either a data.frame, a formula or a trimcommand. If object is a formula, the dependent variable (left-hand-side) is treated as the 'counts' variable. The first and second independent variable are treated as the 'site' and 'time' variable, in that specific order. All other variables are treated as covariates.

...

More parameters, see below in the details

count_col

[character] name of the column holding species counts

site_col

[character] name of the column holding the site id

year_col

[character] name of the column holding the time of counting

month_col

[character] optional name of the column holding the season of counting

weights_col

[numeric] Optional vector of site weights. The length of

covar_cols

[character] name(s) of column(s) holding covariates

model

[numeric] TRIM model type 1, 2, or 3.

changepoints

[numeric] Indices for changepoints (`Models').

overdisp

[logical] Take overdispersion into account (See `Estimation options').

serialcor

[logical] Take serial correlation into account (See `Estimation details')

autodelete

[logical] Auto-delete changepoints when number of observations is too small. (See `Demands on data').

stepwise

[logical] Perform stepwise refinement of changepoints.

covin

a list of variance-covariance matrices; one per pseudo-site.

data

[data.frame] Data frame containing at least counts, sites, and times

weights

[character] name of the column in data which respresents weights (optional)

Models

The purpose of trim is to estimate population totals over time, based on a set of counts $f_{i j}$ at sites $i = 1, 2, \dots, I$ and times $j = 1, 2, \dots, J$ . If no count data is available at site and time $(i, j)$ , a value $μ_{i j}$ will be imputed.

In Model 1, the imputed values are modeled as

$\ln μ_{i j} = α_{i},$

where $α_{i}$ is the site effect. This model implies that the counts vary accross sites, not over time. The model-based time totals are equal to each time point and the model-based indices are all equal to one.

In Model 2, the imputed values are modeled as

$\ln μ_{i j} = α_{i} + β \times (j - 1) .$

Here, $α_{i}$ is the log-count of site $i$ averaged over time and $β$ is the mean growth factor that is shared by all sites over all of time. The assumption of a constant growth rate may be relaxed by passing a number of changepoints that indicate at what times the growth rate is allowed to change. Using a wald test one can investigate whether the changes in slope at the changepoints are significant. Setting stepwise=TRUE makes trim automatically remove changepoints where the slope does not change significantly.

In Model 3, the imputed values are modeled as

$\ln μ_{i j} = α_{i} + β_{j}$ ,

where $β_{j}$ is the deviatiation of log-counts at time $j$ , averaged over all sites. To make this model identifiable, the value of $β_{1} = 0$ by definition. Model 3 can be shown to be equivalent to Model 2 with a changepoint at every time point. Using a wald test, one can estimate whether the collection of deviations $β_{i}$ make the model differ significantly from an overall linear trend (Model 2 without changepoints).

The parameters $α_{i}$ and $γ_{j}$ are referred to as the additive representation of the coefficients. Once computed, they can be represented and extracted in several representations, using the coefficients function. (See also the examples below).

Other model parameters can be extracted using functions such as gof (for goodness of fit), summary or totals. Refer to the `See also' section for an overview.

Using yearly and monthly counts

In many data sets will use use only yearly count data, in which case the time $j$ will reflect the year number. An extension of trim is to use monthly (or any other sub-yearly) count data, in combination with index computations on the yearly time scale.

In this case, counts are given as $f_{i, j, m}$ with $m = 1, 2, \dots, M$ the month number. As before, $μ_{i, j, m}$ will be imputed in case of missing counts.

The contibution of month factors to the model is always similar to the way year factors are used in Model 3, that is,

$\ln μ_{i, j, m} = α_{i} + β \times (j - 1) + γ_{m}$ for Model 2, and $\ln μ_{i, j, m} = α_{i} + β_{j} + γ_{m}$ for Model 3.

For the same reason why $β_{1} = 0$ for Model 3, $γ_{1} = 0$ in case of monthly parameters.

Using covariates

In the basic case of Models 2 and 3, the growth parameter $β$ does not vary accross sites. If auxiliary information is available (for instance a classification of the type of soil or vegetation), the effect of these variables on the per-site growth rate can be taken into account.

For Model 2 with covariates the growth factor $β$ is replaced with a factor

$β_{0} + \sum_{k = 1}^{K} z_{i j k} β_{k}$ .

Here, $β_{0}$ is referred to as the baseline and $z_{i j k}$ is a dummy variable that combines dummy variables for all covariates. Since a covariate with $L$ classes is modeled by $L - 1$ dummy variables, the value of $K$ is equal to the sum of the numbers of categories for all covariates minus the number of covariates. Observe that this model allows for a covariate to change over time at a certain sites. It is therefore possible to include situations for example where a site turns from farmland to rural area. The coefficients function will report every individual value of $β$ . With a wald test, the significance of contributions of covariates can be tested.

For Model 3 with covariates the parameter $β_{j}$ is replaced by

$β_{j 0} + \sum_{k = 1}^{K} z_{i j k} β_{j k} .$

Again, the $β_{j 0}$ are referred to as baseline parameters and the $β_{j k}$ record mean differences in log-counts within a set of sites with equal values for the covariates. All coefficients can be extracted with coefficients and the significance of covariates can be investigated with the wald test.

Estimation options

In the simplest case, the counts at different times and sites are considered independently Poisson distributed. The (often too strict) assumption that counts are independent over time may be dropped, so correlation between time points at a certain site can be taken into account. The assumption of being Poisson distributed can be relaxed as well. In general, the variance-covariance structure of counts $f_{i j}$ at site $i$ for time $j$ is modeled as

$var (f_{i j}) = σ^{2} μ_{i j}$
$cor (f_{i j}, f_{i, j + 1}) = ρ$ ,

where $σ$ is called the overdispersion, $μ_{i j}$ is the estimated count for site $i$ , time $j$ and $ρ$ is called the serial correlation.

If $σ = 1$ , a pure Poisson distribution is assumed to model the counts. Setting overdispersion = TRUE makes trim relax this condition. Setting serialcor=TRUE allows trim to assume a non-zero correlation between adjacent time points, thus relaxing the assumption of independence over time.

Demands on data

The data set must contain sufficient counts to be able to estimate the model. In particular

For model 2 without covariates there must be at least one observation for each time segment defined by the change points.
For model 2 with covariates there must be at least one observation for every value of each covariate, at each time segment defined by the change points.
For model 3 without covariates there must be at least one observation for each time point.
For model 3 with covariates there must be at least one observation for every value of each covariate, at each time point.
For montly data, there must be at least one observation for every month.

The function check_observations identifies cases where too few observations are present to compute a model. Setting the option autodelete=TRUE (Model 2 only) makes trim remove changepoints such that at each time piece sufficient counts are available to estimate the model.

Details

All versions of trim support additional 'experts only' arguments:

verbose

Logical switch to temporarily enable verbose output. (use option(trim_verbose=TRUE)) for permanent verbosity.

constrain_overdisp

Numerical value to control overdispersion.

A value in the range 0..1 uses a Chi-squared oulier detection method.
A value >1 uses Tukey's Fence.
A value of 1.0 (which is the default) results in unconstrained overdispersion.

See vigenette `Taming overdispersion' for more information.

conv_crit

Convergence criterion. Used within the iterative emodel estimation algorithm. The default value is 1e-5.). May be set to higher values in case models don't converge.

max_iter

Number of iterations. Default value is 200. May be set to higher values in case models don't converge.

premove

Probability of removal of changepoints (default value: 0.2). Parameter used in stepwise refinement of models. See the vignette 'Models and statistical methods in rtrim'.

penter

Probability of re-entering of changepoints (default value: 0.15). Similar use as premove.

Examples

Run this code

# NOT RUN {
data(skylark)
m <- trim(count ~ site + time, data=skylark, model=2)
summary(m)
coefficients(m)

# An example using weights
# set up some random weights (one for each site)
w <- runif(55, 0.1, 0.9)
# match weights to sites
skylark$weights <- w[skylark$site]
# run model
m <- trim(count ~ site + time, data=skylark, weights="weights", model=3)

# An example using change points, a covariate, and overdispersion
# 1 is added as cp automatically
cp <- c(2,6)
m <- trim(count ~ site + time + Habitat, data=skylark, model=2, changepoints=cp, overdisp=TRUE)
coefficients(m)
# check significance of changes in slope
wald(m)
plot(overall(m))
# }

Run the code above in your browser using DataLab

Get 50% off unlimited learning