smnet: Additive Modelling for Stream Networks
In smnet: Smoothing for Stream Network Data

Description Usage Arguments Details Value Author(s) References See Also Examples

View source: R/smnet.R

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.

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

`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'.

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.

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

Alastair Rushworth

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/

get_adjacency, plot.smnet

  
# 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)