ppmlasso: Fit point process models with LASSO penalties
In ppmlasso: Point Process Models with LASSO-Type Penalties

View source: R/ppmlasso/R/ppmlasso_functions.R View source: R/ppmlasso_functions.R

ppmlasso

R Documentation

Fit point process models with LASSO penalties

Description

The ppmlasso function fits point process models (either Poisson or area-interaction models) with a sequence of LASSO, adaptive LASSO or elastic net penalties (a "regularisation path").

Usage

ppmlasso(formula, sp.xy, env.grid, sp.scale, coord = c("X", "Y"), 
data = ppmdat(sp.xy = sp.xy, sp.scale = sp.scale, back.xy = env.grid, coord = c("X","Y"),
sp.file = NA, quad.file = NA, datfilename = "PPMDat", writefile = writefile), lamb = NA,
n.fits = 200, ob.wt = NA, criterion = "bic", alpha = 1, family = "poisson", tol = 1.e-9, 
gamma = 0, init.coef = NA, mu.min = 1.e-16, mu.max = 1/mu.min, r = NA, interactions = NA, 
availability = NA, max.it = 25, min.lamb = -10, standardise = TRUE, n.blocks = NA, 
block.size = sp.scale*100, seed = 1, writefile = TRUE)

Arguments

`formula`	The formula of the fitted model. For a point process model, the correct form is `~ variables`.
`sp.xy`	A matrix of species locations containing at least one column representing longitude and one column representing latitude. Environmental variables are interpolated to the locations of `sp.xy` using the `getEnvVar` function, unless the `data` argument is supplied.
`env.grid`	The geo-referenced matrix of environmental grids. This matrix is used to generate quadrature points using the `sampleQuad` function, interpolate environmental data to the species locations of `sp.xy` using the `getEnvVar` function, and calculate observation weights using the `ppmdat` function, unless the `data` argument is supplied. This creates a data matrix `data` which provides the variables for the `formula` argument.
`sp.scale`	The spatial resolution at which to define the regular grid of quadrature points. `sampleQuad` will subsample from the rows of `data` that coincide with a regular grid at a resolution of `sp.scale`.
`coord`	A vector containing the names of the longitude and latitude coordinates.
`data`	An optional data matrix generated from the `ppmdat` function. Supplying a matrix to `data` is an alternative way of providing the environmental variables used in the `formula` argument, instead of specifying `sp.xy` and `env.grid`.
`lamb`	A vector of penalty values that will be used to create the regularisation path. If `lamb = NA`, the penalty values are automatically generated from the `data` and the `n.fits` argument.
`n.fits`	The number of models fitted in the regularisation path. If `lamb = NA`, the `n.fits` penalty values will be equally spaced on a logarithmic scale from `e^{-10}` to `\lambda_{max}`, the smallest penalty that shrinks all parameter coefficients to zero.
`ob.wt`	Quadrature weights, usually inherited from the `ppmdat` function.
`criterion`	The penalisation criteria to be optimised by the regularisation path. The options include `"aic"`, `"bic"`, `"blockCV"`, `"hqc"`, `"gcv"`, `"nlgcv"` and `"msi"`.
`alpha`	The elastic net parameter. The form of the penalty is `\alpha\lambda\sum_{j = 1}^p \|\beta_j\| + (1 - \alpha)\lambda\sum_{j = 1}^p (\beta_j)^2.` The default value `alpha = 1` corresponds to a LASSO penalty, while `alpha = 0` corresponds to a ridge regression penalty.
`family`	The family of models to be fitted – `family = "poisson"` for Poisson point process models or `family = "area.inter"` for area-interaction models.
`tol`	The convergence threshold for the descent algorithm. The algorithm continues for a maximum of `max.it` iterations until the difference in likelihood between successive fits falls below `tol`.
`gamma`	The exponent of the adaptive weights for the adaptive LASSO penalty. The default value `gamma = 0` corresponds to a normal LASSO penalty.
`init.coef`	The initial coefficients used for an adaptive LASSO penalty.
`mu.min`	The threshold for small fitted values. Any fitted value less than the threshold is set to `mu.min`.
`mu.max`	The threshold for large fitted values. Any fitted value larger than the threshold will be set to `mu.max`.
`r`	The radius of point interactions, required if `family = "area.inter"`.
`interactions`	A vector of point interactions calculated from the `pointInteractions` function necessary for fitting area-interaction models. If `interactions = NA` and `family = "area.inter"`, point interactions will be automatically calculated for radius `r` to the locations of `data`.
`availability`	An optional binary matrix used in calculating point interactions indicating whether locations are available (1) or not (0). See `pointInteractions` for more details.
`max.it`	The maximum number of iterations of the descent algorithm for fitting the model.
`min.lamb`	The power `x` of smallest penalty `e^x` among the `n.fits` models.
`standardise`	A logical argument indicating whether the environmental variables should be standardised to have mean 0 and variance 1. It is recommended that variables are standardised for analysis.
`n.blocks`	This argument controls the number of cross validation groups into which the spatial blocks are divided if the `criterion` argument is set to `"blockCV"`. See details.
`block.size`	The length of the edges for the spatial blocks created if the `criterion` argument is set to `"blockCV"`. Only square spatial blocks are currently supported. See details.
`seed`	The random seed used for controlling the allocation of spatial blocks to cross validation groups if the `criterion` argument is set to `"blockCV"`.
`writefile`	A logical argument passed to the `ppmdat` function to determine whether its output should be written to a file or not, set to `TRUE` by default. See the documentation for `ppmdat` for details.

Details

This function fits a regularisation path of point process models provided a list of species locations and a geo-referenced grid of environmental data. It is assumed that Poisson point process models (Warton & Shepherd, 2010) fit intensity as a log-linear model of environmental covariates, and that area-interaction models (Widom & Rowlinson, 1970; Baddeley & van Lieshout, 1995) fit conditional intensity as a log-linear model of environmental covariates and point interactions. Parameter coefficients are estimated by maximum likelihood for Poisson point process models and by maximum pseudolikelihood (Besag, 1977) for area-interaction models. The expressions for both the likelihood and pseudolikelihood involve an intractable integral which is approximated using a quadrature scheme (Berman & Turner, 1992).

Each model in the regularisation path is fitted by extending the Osborne descent algorithm (Osborne, 2000) to generalised linear models with penalised iteratively reweighted least squares.

Three classes of penalty p(\beta) are available for the vector of parameter coefficients \beta:

For the LASSO (Tibshirani, 1996), p(\beta) = \lambda*\sum_{j = 1}^p |\beta_j|

For the adaptive LASSO (Zou, 2006), p(\beta) = \lambda*\sum_{j = 1}^p w_j*|\beta_j|, where w_j = 1/|\hat{\beta}_{init, j}|^\gamma for some initial estimate of parameters \hat{\beta}_{init}.

For the elastic net (Zou & Hastie, 2005), \alpha*\lambda*\sum_{j = 1}^p |\beta_j| + (1 - \alpha)*\lambda*\sum_{j = 1}^p (\beta_j)^2. Note that this form of the penalty is a restricted case of the general elastic net penalty.

There are various criteria available for managing the bias-variance tradeoff (Renner, 2013). The default choice is BIC, the Bayesian Information Criterion, which has been shown to have good performance.

An alternative criterion useful when data are sparse is MSI, the maximum score of the intercept model (Renner, in prep). For a set of m presence locations, the MSI penalty is \lambda_{MSI} = \lambda_{max}/\sqrt{m}, where \lambda_{max} is the smallest penalty that shrinks all environmental coefficients to zero. The MSI penalty differs from the other criteria in that does not require an entire regularisation path to be fitted.

It is also possible to control the magnitude of the penalty by spatial cross validation by setting the criterion argument to "blockCV". The study region is then divided into square blocks with edge lengths controlled by the block.size argument, which are assigned to one of a number of cross validation groups controlled by the n.groups argument. The penalty which maximises the predicted log-likelihood is chosen.

Value

An object of class "ppmlasso", with elements:

`betas`	A matrix of fitted coefficients of the `n.fits` models.
`lambdas`	A vector containing the `n.fits` penalty values.
`likelihoods`	A vector containing the likelihood of `n.fits` fitted models.
`pen.likelihoods`	A vector containing the penalised likelihood of `n.fits` fitted models.
`beta`	A vector containing the coefficients of the model that optimises the specified `criterion`.
`lambda`	The penalty value of the model that optimises the specified `criterion`.
`mu`	A vector of fitted values from the model that optimises the specified `criterion`.
`likelihood`	The likelihood of the model that optimises the specified `criterion`.
`criterion`	The specified `criterion` of the function call.
`family`	The specified `family` of the function call.
`gamma`	The specified `gamma` of the function call.
`alpha`	The specified `alpha` of the function call.
`init.coef`	The specified `init.coef` of the function call.
`criterion.matrix`	A matrix with `n.fits` rows corresponding to the observed values of AIC, BIC, HQC, GCV, and non-linear GCV.
`data`	The design matrix. For the point process models fitted with this function, `mu = e^{data*beta}`.
`pt.interactions`	The calculated point interactions.
`wt`	The vector of quadrature weights.
`pres`	A vector indicating presence (1) or quadrature point (0).
`x`	A vector of point longitudes.
`y`	A vector of point latitudes.
`r`	The radius of point interactions.
`call`	The function call.
`formula`	The `formula` argument.
`s.means`	If `standardise = TRUE`, the means of each column of `data` prior to standardisation.
`s.sds`	If `standardise = TRUE`, the standard deviations of each column of `data` prior to standardisation.
`cv.group`	The cross validation group associated with each point in the data set.
`n.blocks`	The number of cross validation groups specified.

Author(s)

Ian W. Renner

References

Baddeley, A.J. & van Lieshout, M.N.M. (1995). Area-interaction point processes. Annals of the Institute of Statistical Mathematics 47, 601-619.

Berman, M. & Turner, T.R. (1992). Approximating point process likelihoods with GLIM. Journal of the Royal Statistics Society, Series C 41, 31-38.

Besag, J. (1977). Some methods of statistical analysis for spatial data. Bulletin of the International Statistical Institute 47, 77-91.

Osborne, M.R., Presnell, B., & Turlach, B.A. (2000). On the lasso and its dual. Journal of Computational and Graphical Statistics 9, 319-337.

Renner, I.W. & Warton, D.I. (2013). Equivalence of MAXENT and Poisson point process models for species distribution modeling in ecology. Biometrics 69, 274-281.

Renner, I.W. (2013). Advances in presence-only methods in ecology. https://unsworks.unsw.edu.au/fapi/datastream/unsworks:11510/SOURCE01

Tibshirani, R. (1996). Regression shrinkage and selection via the lasso. Journal of the Royal Statistical Society, Series B 58, 267-288.

Warton, D.I. & Shepherd, L.C. (2010). Poisson point process models solve the "pseudo-absence problem" for presence-only data in ecology. Annals of Applied Statistics 4, 1383-1402.

Widom, B. & Rowlinson, J.S. (1970). New model for the study of liquid-vapor phase transitions. The Journal of Chemical Physics 52, 1670-1684.

Zou, H. (2006). The adaptive lasso and its oracle properties. Journal of the American Statistical Association 101, 1418-1429.

Zou, H. & Hastie, T. (2005). Regularization and variable selection via the elastic net. Journal of the Royal Statistical Society, Series B 67, 301-320.

Examples

# Fit a regularisation path of Poisson point process models
data(BlueMountains)
sub.env = BlueMountains$env[BlueMountains$env$Y > 6270 & BlueMountains$env$X > 300,]
sub.euc = BlueMountains$eucalypt[BlueMountains$eucalypt$Y > 6270 & BlueMountains$eucalypt$X > 300,]
ppm.form = ~ poly(FC, TMP_MIN, TMP_MAX, RAIN_ANN, degree = 2)
ppm.fit  = ppmlasso(ppm.form, sp.xy = sub.euc, env.grid = sub.env, sp.scale = 1, n.fits = 20,
writefile = FALSE)

#Fit a regularisation path of area-interaction models
data(BlueMountains)
ai.form  = ~ poly(FC, TMP_MIN, TMP_MAX, RAIN_ANN, degree = 2)
ai.fit   = ppmlasso(ai.form, sp.xy = sub.euc, env.grid = sub.env, sp.scale = 1, 
family = "area.inter", r = 2, availability = BlueMountains$availability, n.fits = 20,
writefile = FALSE)

ppmlasso documentation built on May 29, 2024, 7:12 a.m.