createSSN: Create an SpatialStreamnetwork Object

Description

Generates a random tree structure, with observed and prediction locations, and stores as an object of class SpatialStreamNetwork-class.

Usage

createSSN(n, obsDesign, predDesign = noPoints, path, importToR = FALSE, treeFunction = igraphKamadaKawai)

Arguments

A numeric vector, where the generated SpatialStreamNetwork object will consist of length(n) distinct random tree structures, with the ith tree structure consisting of n[i] straight line segments.

obsDesign

A function representing a sampling strategy. It is used to select observation points on the network. Input obsDesign is required and cannot have value noPoints, as there must be at least one observed point generated. At present the only implemented designs are binomialDesign, systematicDesign, systematicDesign, poissonDesign and hardCoreDesign. For further details, which will allow users to to write your their own design function, please see the design functions.

predDesign

A function having the same signature as the obsDesign input, but this time the function generates the prediction points. This defaults to noPoints, which generates no prediction points. Otherwise any of the design functions which can be used for input obsDesign can also be used for input predDesign.

path

The path where the new .ssn directory is to be stored.

importToR

If TRUE then a call to importSSN is made immediately and the imported SpatialStreamNetwork object is returned. If FALSE then no value is returned.

treeFunction

An input function that is used to generate the tree structure. This function must have the signature

			function(n)

Where n is the desired number of edges for the generated network. This function must return a list with four entries. Entry graph must be an igraph object representing the generated network. Entry locations must be a numeric matrix giving the locations of all the points, in order. That is, the first row contains the coordinates for point 0, the second the coordinates for point 1, etc. Entry initialPoint gives the number of the inital point in that network. The two possible values for this input are iterativeTreeLayout and igraphKamadaKawai. igraphKamadaKawai is the default and uses the graph.tree function from the igraph package, with the Kamada-Kawai layout function. iterativeTreeLayout generates more natural looking tree structures but is slower and can fail to function.

Value

An SpatialStreamNetwork object if importToR is TRUE, otherwise NULL.

Details

This function generates random tree structure using the igraph package and then turns these into an SpatialStreamNetwork object with prediction and observation sites generated by the obsDesign and predDesign functions. The main difficulty is assigning locations to the vertices of the random trees, in such a way that the result has the sort of layout that we want. This is a graph layout / embedding problem, more specifically a tree layout problem. For now we are using the layout.kamada.kawai function of the igraph package to construct this layout. Unlike some of the other layouts available, it still gives interesting layouts when applied to trees (some of the others tend to give highly structured layouts for such a simple graph. The downside is that it the resulting layout can have self intersections, and often does.

Examples

Run this code


library(SSN)
#Simulate three networks, the first consisting of ten straight line segments,
#the second of 20 and the third of 30. There are two observed points on the first
#network, four on the second and six on the third. All the observed points are
#distributed uniformly. The default for prediction points is no prediction points.
ssn1 <- createSSN(c(10, 20, 30), obsDesign = binomialDesign(c(2,4,6)),
  path=paste(tempdir(),"/simulated1.ssn", sep = ""), importToR = TRUE)
#NOT RUN plot(ssn1)

#Same as above, but using iterativeTreeLayout
set.seed(5)
ssn2 <- createSSN(c(10, 20, 30), obsDesign = binomialDesign(c(2,4,6)),
  path=paste(tempdir(),"/simulated2.ssn", sep = ""), importToR = TRUE, 
  treeFunction = iterativeTreeLayout)
#NOT RUN plot(ssn2)

#Simulate the same number of line segments per network, but this time the observed
#points have the distribution of a Poisson process with rates 2, 1 and 0.5
#respectively. Again there are no prediction points.
ssn3 <- createSSN(c(10, 20, 30), obsDesign = poissonDesign(c(2,1,0.5)),
  path=paste(tempdir(),"/simulated3.ssn", sep = ""), importToR = TRUE)
#NOT RUN plot(ssn3)

#Simulate the same number of line segments per network, but this time the observed
#points have a hard-core process distribution. Two hundred points are placed on
#every network according to the binomial process, and then points are removed
#until every poir of points is at least a distance 0.5 apart on the first network,
#0.25 on the second and 0.1 on the third. Again there are no prediction points.
ssn4 <- createSSN(c(10, 20, 30), obsDesign = hardCoreDesign(200, c(0.5, 0.25, 0.1)),
  path=paste(tempdir(),"/simulated4.ssn", sep = ""), importToR = TRUE)
#NOT RUN plot(ssn4)

#This time there are the same number of observed points on each of the networks,
#but there are ten prediction sites on each network.
ssn5 <- createSSN(c(10, 20, 30), obsDesign = binomialDesign(c(2, 4, 6)),
  predDesign = binomialDesign(c(10, 10, 10)), 
  path=paste(tempdir(),"/simulated5.ssn", sep = ""),
  importToR = TRUE)
#NOT RUN plot(ssn5)

#This time the observed and prediction points are a regular grid, spacing 0.5
ssn6 <- createSSN(c(10, 20, 30), obsDesign = systematicDesign(0.5),
  predDesign = systematicDesign(0.5), 
  path=paste(tempdir(),"/simulated6.ssn", sep = ""),
  importToR = TRUE)
#NOT RUN plot(ssn6)

#Same as example number 5, but this time the observed (but not predicted) points
#are replicated twice with different time values
ssn7 <- createSSN(c(10, 20, 30), obsDesign = binomialDesign(c(2, 4, 6), 
  replications=2),
  predDesign = binomialDesign(c(10, 10, 10)), 
	path=paste(tempdir(),"/simulated7.ssn", sep = ""),
  importToR = TRUE)
#NOT RUN plot(ssn7)

ssn7@obspoints@SSNPoints[[1]]@point.data
ssn5@obspoints@SSNPoints[[1]]@point.data

Run the code above in your browser using DataLab