Library to support processing of data associated with Network Planner. The core data structure is an igraph
NOTE: This library is no longer compatible with the latest version of igraph.
The last version of igraph that IS compatible is 0.7.1.
You can install igraph v0.7.1 via the following:
install.packages("http://igraph.org/nightly/get/r/igraph_0.7.1.tar.gz", repos=NULL, type="source")
Now you can install the rest:
install.packages('devtools')
library(devtools)
install_github("SEL-Columbia/networkplanner.R")
Windows Users: If you are using a PC, you MUST install Rtools from CRAN, otherwise non-cran packages wont install properly. Find a free copy of Rtools.exe appropriate for your system below:
http://cran.r-project.org/bin/windows/Rtools/
Build and sequence NetworkPlan
#Load the library first for custom functions
library(networkplanner)
# Set the directory containing the output of a Network Planner
# scenario. Assumes networkplanner directory is on local machine
base_dir <- "C:/Users/Downloads/2940"
# Generate NetworkPlan object with directed igraph of proposed network
# and nodes from Network Planner
np <- read_networkplan(base_dir)
# Sequence the NetworkPlan object via the 'mv_v_dmd_sequence_model'
np <- sequence_plan_far(np, sequence_model=mv_v_dmd_sequence_model)
# Write sequenced NetworkPlan to a directory as nodes (csv) and a network (shp)
write.NetworkPlan(np, base_dir)
Sample plotting code
# assumes np is a sequenced NetworkPlan object
# Setup graph for plotting by coloring roots red and labeling
# vertices by their Far.sighted.sequence value
V(np@network)[V(np@network)$Network..Is.root]$color <- "red"
vertex_labels <- get.vertex.attribute(np@network, "Sequence..Far.sighted.sequence")
plot(np@network, vertex.size=4, edge.arrow.size=1, vertex.label=vertex_labels)
And the plot
Notice how the "Sequence roots" in red are not necessarily the roots of their respective tree/subnetwork. This is the case when that subnetwork has a "Fake" root which models the closest connection to an existing grid and is NOT a settlement node.
The following are standard fields that are added to a NetworkPlan upon creation:
Vertex Attributes:
Network..Is.fake
: Whether this vertex is a "Fake" node
Edge Attributes:
FID
: The FID of the corresponding record in the original existing network
shapefile
distance
: The distance (in meters) between vertices that this edge spans
Directed NetworkPlan Vertex Attributes:
Network..Is.root
: Whether this vertex is a "Sequence root"
Sequenced NetworkPlan Vertex Attributes:
Sequence..Far.sighted.sequence
: The sequence associated with this vertex
calculated in a "far sighted" manner.
Custom model fields will vary with the model. A convention is to prefix the attribute name with "Sequence". If this is followed, some sample code to list these new attributes is:
# assumes np is a sequenced NetworkPlan object
vatts <- list.vertex.attributes(np@network)
vatts[grep("Sequence", vatts)]
A NetworkPlan represents a graph-oriented view of the scenario output of Network Planner. The edges of the graph are the segments connecting settlement nodes (the vertices).
The call read_networkplan(base_dir)
returns a NetworkPlan object with
an igraph object in the network slot (i.e. np@network
). The igraph returned
is an undirected graph with vertices representing settlements and edges
representing connections between.
In order to sequence this graph, it must be converted into a forest of
directed trees. You can do this explicitly via directed_networkplan
or
it will happen implicitly in the call to sequence_plan_far
.
Once you have a directed NetworkPlan, there are 2 possible starting vertices for each subcomponent of the graph:
"Fake" vertices:
Vertices that represent the shortest connection from a settlement to an existing network as created by Network Planner.
These vertices can be found via V(network)[V(network)$Network..Is.fake]
"Selected" vertices:
For trees (subcomponents) that are not connected to an existing network (i.e. have no "Fake" vertex), a root is selected which represents the node with maximal demand (or some custom root selection function)
"Network root" vertices can be found via V(network)[V(network)$Network..Is.root]
These are not necessarily the same as the roots of a tree/subnetwork since
"Fake" vertices are not considered true roots for sequencing purposes as
there is no settlement associated with a "Fake" vertex.
To create a "Far Sighted Sequence" of the vertices in a NetworkPlan, you can
call sequence_plan_far(np, sequence_model=mv_v_dmd_sequence_model)
. This
function takes a custom sequencing algorithm and works in 2 steps:
Accumulate (details in the accumulate
function in R/networkplanner.R):
Given an accumulate function, gather the necessary data associated with each vertex (either upstream or downstream as defined by the directionality of the graph) and attribute it back to the vertex.
Sequence (details in the sequence_plan
function in R/networkplanner.R):
Given a selector function, selects the next vertex in the "frontier" of a breadth-first-search of the graph in order to generate a sequencing of the nodes.
The accumulate and sequence functions can be customized by providing
accumulator
and selector
function definitions respectively. These are
members of the sequence_model
list parameter to the sequence_plan_far
function. There are several predefined functions in the R/sequence_models.R
file.
You can write out the NetworkPlan as nodes and segments via the write.Network
function. This outputs the nodes as a csv and segments as a shapefile. You
can also download a scenario and all its files for analysis via the
download_scenario
function.