added getting started vignette

pkg/vignettes/Getting_started.Rmd

@@ -0,0 +1,87 @@
+---
+title: "Getting started"
+author: "Patrick Bogaart, Mark van der Loo and Jeroen Pannekoek"
+date: "`r Sys.Date()`"
+output: 
+  rmarkdown::html_vignette:
+    toc: true
+vignette: >
+  %\VignetteIndexEntry{Getting started}
+  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEncoding{UTF-8}
+---
+
+## Introduction
+
+The `rtrim` package is an complete reimplementation of the [original TRIM](https://www.cbs.nl/en-gb/society/nature-and-environment/indices-and-trends--trim--) software developed by Jeroen Pannekoek from the 1990's onwards. In this getting started manual the R-based workflow for computing TRIM models is demonstrated. To use legacy TRIM command files and TRIM data files, see the [vignette on tcf files]().
+
+TRIM was developed to estimate animal populations, based on repeated counts at various sites while counts may be missing for certain sites at certain times. Estimation is based on a model-based imputation method.
+
+We assume that the reader is already familiar with the methodology behind TRIM but in short, TRIM estimates a piecewise loglinear growth model to compute imputations. There are three variants of this model which differ by their basic assumptions.
+
+- **Model 1:** Populations vary accross sites, but not over time.
+- **Model 2:** Populations vary accross sites, but show the same growth everywhere
+- **Model 3:** Growth and population vary over sites and time.
+
+For each variant it is possible to include categorical covariates in the model. To keep computations tractable for large numbers of sites, the sites are treated as independent from each other so model parameters are estimated for each site separately.
+
+A detailed description of the methodology can be found in the [original TRIM3 manual](https://www.cbs.nl/-/media/imported/onze%20diensten/methoden/trim/documents/2006/13/trim3man.pdf).
+
+## Computing TRIM models
+
+We are going to use the `skylark` dataset, which is included with the package. 
+```{r}
+library(rtrim)
+data(skylark)
+# inspect the dataset
+head(skylark,3)
+```
+
+
+
+The central function for computing TRIM models is called `trim`. Calling this function is very similar to calling modeling functions like `lm`. Here, we compute TRIM model 2.
+
+```{r}
+m1 <- trim(count ~ time + site, data=skylark,model=2)
+```
+The result is an object of class `trim`. Just like with objects of class `lm`, its various components can be extracted using specialized functions. Here are some examples.
+```{r}
+# summarize the model
+summary(m1)
+# print goodness-of-fit
+gof(m1)
+# extract the coefficients
+coefficients(m1)
+# plot the overall slope
+plot(overall(m1))
+```
+
+## Model specification
+
+The names of variables in the dataset are not important and neither is their order. However, since TRIM models
+are designed to estimate the number of counts at counting sites, the formula specifying the model
+has to satisfy certain rules.
+
+- The single variable at the left-hand side must represent the number of counts.
+- The **first variable** on the right-hand side must represent the **time** variable.
+- The **second variable** on the right-hand side must represent the **site** identifier.
+- All other variables on the right-hand-side are interpreted as covariates.
+
+For example, to use the variable `Habitat` as covariate when analysing the `skylark` dataset (under model 2) one does the following.
+
+```{r}
+m2 <- trim(count ~ time + site + Habitat, data=skylark, model=2)
+```
+
+It is also possible to specify weights by passing `trim` a `weights` argument. The TRIM options `overdisp` (for overdispersion) and `serialcor` (for serial correlation) are simple `TRUE/FALSE` toggles. The breaks of the piecewise loglinear model can be specified with the `changepoints` option. See `?trim` for a precise description of all options.
+
+
+
+
+
+
+
+
+
+
+