README.md 6.4 KB
Newer Older
francois's avatar
francois committed
1
# Public repository for  __spaMM__
francois's avatar
francois committed
2

francois's avatar
francois committed
3
4
5
[![CRAN](http://www.r-pkg.org/badges/version/spaMM)](https://cran.r-project.org/web/packages/spaMM)
[![CRAN RStudio mirror downloads](http://cranlogs.r-pkg.org/badges/grand-total/spaMM?color=brightgreen)](http://www.r-pkg.org/pkg/spaMM)
[![Rdoc](http://www.rdocumentation.org/badges/version/spaMM)](http://www.rdocumentation.org/packages/spaMM)
francois's avatar
francois committed
6

francois's avatar
francois committed
7
## What is spaMM ?
francois's avatar
francois committed
8

francois's avatar
francois committed
9
__spaMM__ is an R package originally designed for fitting ***spa***tial generalized linear ***M***ixed ***M***odels, particularly the so-called geostatistical model allowing prediction in continuous space. But it is now a more general-purpose package for fitting mixed models, spatial or not, and with efficient methods for both geostatistical and autoregressive models. Its latest major addition is the ability to fit multivariate-response models, including some of interest in quantitative genetics. 
francois's avatar
francois committed
10

francois's avatar
francois committed
11
## What to look for (or not) here ?
francois's avatar
francois committed
12
This repository provides whatever information I do not try to put into the R package, such as its vignette-like [gentle introduction](https://gitlab.mbb.univ-montp2.fr/francois/spamm-ref/-/blob/master/vignettePlus/spaMMintro.pdf) (latest version: 2021/09/13) and the [slides](https://gitlab.mbb.univ-montp2.fr/francois/spamm-ref/-/blob/master/vignettePlus/MixedModels_useR2021.pdf) from the presentation of spaMM at the [useR2021](https://user2021.r-project.org/) conference. 
francois's avatar
francois committed
13
14
15

It will also include a few selected versions of spaMM. However, use a CRAN repository for standard installation of the package, and see the (unofficial) [CRAN github repository](https://github.com/cran/spaMM) for an archive of sources for all versions of spaMM previously published on CRAN.

francois's avatar
francois committed
16
## General features of spaMM
francois's avatar
francois committed
17
18

<!-- https://gitlab.mbb.univ-montp2.fr/francois/spamm-distrib/master/non-package/images/image_intro-IsoriX.gif --> 
francois's avatar
francois committed
19
<img align="right" width="407" height="290" src="https://raw.githubusercontent.com/courtiol/IsoriX/master/image/image_intro-.gif">
francois's avatar
francois committed
20
21

The `spaMM` package was developed first to fit mixed-effect models with spatial correlations, which commonly occur in ecology., but it has since been developed as a more general package for inferences under models with or without spatially-correlated random effects. It can fit multivariate-response models (its latest major addition). Initial development drew inspiration from work by Lee and Nelder on $h$-likelihood (e.g. [Lee, Nelder & Pawitan](https://doi.org/10.1201/9781420011340), 2006; [Lee & Lee](http://dx.doi.org/10.1007/s11222-011-9265-9) 2012; see also [Molas and Lesaffre](http://dx.doi.org/10.1002/sim.3852), 2010), and it retains from that work several distinctive features, such as the ability to fit models with non-gaussian random effects (e.g., Beta- or Gamma-distributed), structured dispersion models (including residual dispersion models with random effects), and implementation of several variants of Laplace and PQL approximations. However, some of the computations considered in such works are expensive. Hence, to make `spaMM` competitive to fit large data sets, recent versions have increasingly relied on alternative algorithms when possible, without sacrificing any of its distinctive features. `spaMM` has distinct algorithms for three cases: sparse precision, sparse correlation, and dense correlation matrices, and is efficient to fit geostatistical, autoregressive, and other mixed models on large data sets. Notable features include: 
francois's avatar
francois committed
22

francois's avatar
francois committed
23
- Fitting geostatistical models with random-effect terms following the `Matern` as well as the much less known `Cauchy` correlation models, or autoregressive models described by an `adjacency` matrix or `AR1` model, or an arbitrary given precision or correlation matrix (`corrMatrix`). Conditional spatial effects can be fitted,  as in (say) `Matern(female|...) + Matern(male|...)` to fit distinct random effects for females and males (e.g., [Tonnabel et al., 2021](https://doi.org/10.1111/mec.15833)).
francois's avatar
francois committed
24
25
26
27
28
- A further class of spatial correlation models, "Interpolated Markov Random Fields" (`IMRF`) covers widely publicized approximations of Matérn models ([Lindgren et al. 2011](http://doi.org/10.1111/j.1467-9868.2011.00777.x)) and the multiresolution model of [Nychka et al. 2015](https://doi.org/10.1080/10618600.2014.914946). 
- Allowed response families include zero-truncated variants of the Poisson and negative binomial, and the Conway-Maxwell-Poisson (`COMPoisson`) family;
- All the above features combined in multivariate-response models. Previously, more experimental facilities have been available for handling multinomial data only;
- A replacement function for `glm`, useful when the latter (or even `glm2`) fails to fit a model;
- A syntax close to that of `glm` or [`g`]`lmer`. It includes a growing list of extractor methods similar to those in `stats` or `nlme`/`lmer`, and functions for inference beyond the fits, such as `confint()` for confidence intervals of fixed-effect parameters, `predict()` and related functions for point prediction and prediction variances, and compatibility with functions from other packages such as `multcomp::glht()` (see `help("post-fit")`); 
francois's avatar
francois committed
29
- Simple facilities for quickly drawing maps from model fits, using only base graphic functions. See [here](http://kimura.univ-montp2.fr/%7Erousset/spaMM/example_raster.html) for more elaborate examples of producing maps. The animated graphics on this page is from an application using the [`IsoriX` package](https://github.com/courtiol/IsoriX/blob/master/README.md). 
francois's avatar
francois committed
30

francois's avatar
francois committed
31
32
33
## References

The performance of Laplace approximations used by spaMM was assessed for spatial GLMMs in :
francois's avatar
francois committed
34
    Rousset F., Ferdy J.-B. (2014) [Testing environmental and genetic effects in the presence of spatial autocorrelation](http://onlinelibrary.wiley.com/doi/10.1111/ecog.00566/abstract). Ecography, 37: 781-790.
francois's avatar
francois committed
35
Also available here is the [Supplementary Appendix G](http://kimura.univ-montp2.fr/%7Erousset/spaMM/RoussetF14AppendixG.pdf) from that paper, including comparisons with a trick that ha been uncritically used to constrain the functions `lmer` and `glmmPQL` to analyse spatial models.
francois's avatar
francois committed
36
37
38
39
40

For some substantial use of various features of spaMM, see e.g. the [IsoriX project](https://github.com/courtiol/IsoriX), or a story about [social dominance in hyaenas](https://doi.org/10.1038/s41559-018-0718-9), or [yet another depressing story about climate change](https://doi.org/10.1038/s41467-019-10924-4). 

## Credits
Initial development was supported by a PEPS grant from the CNRS and University of Montpellier