smnet: Additive Modelling for Stream Networks

Description

Fits (Gaussian) additive models to river network data based on the flexible modelling framework described in O'Donnell et al. (2014). Data must either be in the form of an object of class SpatialStreamNetwork as used by the R package SSN (Ver Hoef et al., 2012) or in the form of a data.frame. Smoothness of covariate effects is represented by transforming data onto a uniformly spaced B-spline basis; parameter estimates are obtained by penalized least-squares. Optimal smoothness is achieved by using a numerical optimization of AIC, GCV or AICC.

Care is taken to exploit the sparse matrix properties of model objects using the optimized storage and algebra routines in the R packages spam (Furrer and Sain, 2010). This allows faster fitting and lower memory footprint.

The formula interpreter used for penalised additive components is modelled on the code found in the package mgcv.

Usage

smnet(formula, data.object, control = NULL, method = "AICC")

Arguments

formula

A formula similar to those as used in by the gam function in the package mgcv. Smooth functions based on P-splines with m(..., k=20) function, up to 2-dimensional interactions currently supported. At present, only k

data.object

Either an object of class "SpatialStreamNetwork" or a data.frame containing response variable and covariates

control

A list of options passed to the optimiser. maxit, default = 500, sets an upper limit of iterations made by the optimiser. approx = NULL, positive integer specifying the number samples to collect using a Monte-Carlo method to a

method

Character string determining the performance criterion for choosing optimal smoothness, options are "AICC" or "GCV".

Value

Object of class smnet with components
1Original SSN object used provided as data.object, unchanged
2List; model output including fitted values (fit), effective dimension (ED), residual variance (sigma.sq), sparse matrices involved in model fit etc.

References

Ver Hoef, J.M., Peterson, E.E., Clifford, D., Shah, R. (2012) SSN: An R Package for Spatial Statistical Modeling on Stream Networks

O' Donnell, D., Rushworth, A.M., Bowman, A.W., Scott, E.M., Hallard, M. (2014) Flexible regression models over river networks. Journal of the Royal Statistical Society: Series C (Applied Statistics). 63(1) 47--63.

Reinhard Furrer, Stephan R. Sain (2010). spam: A Sparse Matrix R Package with Emphasis on MCMC Methods for Gaussian Markov Random Fields. Journal of Statistical Software, 36(10), 1-25. URL: http://www.jstatsoft.org/v36/i10/

Examples

Run this code

# Set up an SSN object; this part is taken from the SSN:::SimulateOnSSN help file
set.seed(101)
## simulate a SpatialStreamNetwork object
raw1.ssn <- createSSN(n = 100,
    obsDesign = binomialDesign(50), predDesign = binomialDesign(50),
  importToR = TRUE, path = paste(tempdir(),"/sim1", sep = ""))

## create distance matrices, including between predicted and observed
createDistMat(raw1.ssn, "preds", o.write=TRUE, amongpred = TRUE)

## extract the observed and predicted data frames
raw1DFobs <- getSSNdata.frame(raw1.ssn, "Obs")
raw1DFpred <- getSSNdata.frame(raw1.ssn, "preds")

## add a continuous covariate randomly
raw1DFobs[,"X1"] <- rnorm(length(raw1DFobs[,1]))
raw1DFpred[,"X1"] <- rnorm(length(raw1DFpred[,1]))

## add a categorical covariate randomly
raw1DFobs[,"F1"] <- as.factor(sample.int(3,length(raw1DFobs[,1]), replace = TRUE))
raw1DFpred[,"F1"] <- as.factor(sample.int(3,length(raw1DFpred[,1]), replace = TRUE))

## simulate Gaussian data
sim1.out <- SimulateOnSSN(raw1.ssn,
	ObsSimDF = raw1DFobs,
	PredSimDF = raw1DFpred,
	PredID = "preds",
	formula = ~ X1 + F1,
	coefficients = c(1, .5, -1, 1),
	CorModels = c("Exponential.tailup", "Exponential.taildown"),
	use.nugget = TRUE,
	use.anisotropy = FALSE,
	CorParms = c(2, 5, 2, 5, 0.1),
	addfunccol = "addfunccol")

## extract the ssn.object
sim1.ssn <- sim1.out$ssn.object

## extract the observed and predicted data frames, now with simulated values
sim1DFobs <- getSSNdata.frame(sim1.ssn, "Obs")
sim1DFpred <- getSSNdata.frame(sim1.ssn, "preds")

## store simulated prediction values, and then create NAs in their place
sim1preds <- sim1DFpred[,"Sim_Values"]
sim1DFpred[,"Sim_Values"] <- NA
sim1.ssn <- putSSNdata.frame(sim1DFpred, sim1.ssn, "preds")

# create the adjacency matrix for use with SmoothNetwork
adjacency<-get_adjacency(paste(tempdir(),"/sim1", sep = ""))

lmP<-smnet(formula = Sim_Values~1 + m(NEAR_X)+
          network(adjacency = adjacency, weight = "addfunccol", netID = 1), 
          data.object = sim1.ssn)
          
plot(lmP, type = "covariates")
plot(lmP, type = "nodes")