Learn R Programming

smnet (version 2.1.2)

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 be in the form of a SpatialStreamNetwork object as used by the SSN package (Ver Hoef et al., 2012). Smoothness of covariate effects is represented via a penalised B-spline basis (P-splines) and parameter estimates are obtained using penalised least-squares. Optimal smoothness is achieved by optimization of AIC, GCV or AICC. The formula interpreter used for penalised additive components is modelled on the code found in the package mgcv.

Usage

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

Arguments

formula

A formula statement similar to those used by lm and mgcv:::gam. Smooth functions are represented with m(..., k = 20) function, up to 2d smooth interactions are currently supported. Spatial network components are specified using network(...) function. Further details can be found in m and network and the examples below.

data.object

An object of class SpatialStreamNetwork.

netID

Integer indicating the particular stream network to model, generally only user-specified when multiple networks are contained within data.object, default is 1.

method

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

control

A list of options that control smoothness selection via optimisation. See 'Details'.

Value

Object of class smnet with components

  • fitted.valuesvector of fitted values

  • residualsvector of residuals: response minus fitted values

  • coefficientsvector of parameter estimates

  • R2R^2 statistic

  • R2.adjadjusted R^2 statistic

  • df.residualresidual degrees of freedom

  • ssn.objectunchanged SSN input data object

  • internalsmodel objects for internal use by other functions

Details

control is a list whose elements control smoothness selection: maxit limits the number of iterations made by the optimiser (default = 500). approx, positive integer, if specified indicates the number of Monte-Carlo samples to collect using an approximate version of performance criterion when direct evaluation is slow - this may be much faster if the network has a large number of segments or the data is large, for example approx = 100 often works well (defaults to NULL). checks, logical, specifies whether additivity checks should be performed on the input weights default = TRUE. trace, default = 0, if set to 1, optim will print progress. tol, the relative tolerance of optim. optim.method, the optimiser - default is "Nelder-Mead" see ?optim for details.

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/

See Also

get_adjacency, plot.smnet

Examples

Run this code
# NOT RUN {
  
# As an example, create a simulated SSN object
# Save the object to a temporary location
set.seed(12)
ssn_path <- paste(tempdir(), "/example_network", sep = "")

# If example network doesn't already exist, then attempt to create it
# Otherwise, read from the temporary directory
example_network <- try(importSSN(ssn_path, predpts = 'preds', o.write = TRUE), silent = TRUE)
if('try-error' %in% class(example_network)){
example_network <- createSSN(
      n            = 50,
      obsDesign    = binomialDesign(200), 
      predDesign   = binomialDesign(50),
      importToR    = TRUE, 
      path         = ssn_path,
      treeFunction = iterativeTreeLayout
  )
}

# plot the simulated network structure with prediction locations
# plot(example_network, bty = "n", xlab = "x-coord", ylab? = "y-coord")

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

## extract the observed and predicted data frames
observed_data            <- getSSNdata.frame(example_network, "Obs")
prediction_data          <- getSSNdata.frame(example_network, "preds")

## associate continuous covariates with the observation locations
#  data generated from a normal distribution
obs                      <- rnorm(200)
observed_data[,"X"]      <- obs
observed_data[,"X2"]     <- obs^2

## associate continuous covariates with the prediction locations
#  data generated from a normal distribution
pred                     <- rnorm(50) 
prediction_data[,"X"]    <- pred
prediction_data[,"X2"]   <- pred^2

## simulate some Gaussian data that follows a 'tail-up' spatial process
sims <- SimulateOnSSN(
  ssn.object      = example_network, 
  ObsSimDF        = observed_data, 
  PredSimDF       = prediction_data,  
  PredID          = "preds",  
  formula         = ~ 1 + X,
  coefficients    = c(1, 10),
  CorModels       = c("Exponential.tailup"), 
  use.nugget      = TRUE,
  CorParms        = c(10, 5, 0.1),
  addfunccol      = "addfunccol")$ssn.object


## extract the observed and predicted data frames, now with simulated values
sim1DFpred         <- getSSNdata.frame(sims, "preds")
sim1preds          <- sim1DFpred[,"Sim_Values"]
sim1DFpred[,"Sim_Values"] <- NA
sims               <- putSSNdata.frame(sim1DFpred, sims, "preds")

# create the adjacency matrix for use with smnet
adjacency    <- get_adjacency(
  ssn_path, 
  net = 1
)

# not run - plot the adjacency matrix
# display(adjacency[[1]])

# sometimes it is useful to see which variables are valid network weights 
# in the data contained within the SSN object
show_weights(sims, adjacency)

# fit a penalised spatial model to the stream network data
# Sim_Values are quadratic in the X covariate.  To highlight 
# the fitting of smooth terms, this is treated as non-linear 
# and unknown using m().
mod_smn       <- smnet(formula = Sim_Values ~ m(X) + m(X2) + 
                       network(adjacency = adjacency, weight = "shreve"), 
                       data.object = sims, netID = 1)

# not run - plot different summaries of the model
plot(mod_smn, type = "network-covariates")
plot(mod_smn, type = "network-segments", weight = 4, shadow = 2)
plot(mod_smn, type = "network-full", weight = 4, shadow = 2)

# obtain predictions at the prediction locations and plot 
# against true values
preds <- predict(mod_smn, newdata = getSSNdata.frame(sims, "preds"))
plot(preds$predictions, sim1preds)

# obtain summary of the fitted model
summary(mod_smn)

# delete the simulated data
unlink(ssn_path, recursive = TRUE)
# }

Run the code above in your browser using DataLab