User Guide
Building Graphs from Rasters
SpatialGraphs.jl offers several functions for constructing graphs from raster data, which are detailed below. Once you have converted your data to an AbstractSpatialGraph
, you can analyze the graph using funtions from Graphs.jl. Following you analysis, you can then use the spatial information stored in the AbstractSpatialGraph
to map values (such as betweenness or cost distance, for example) back to the appropriate points in space. See the Examples section for a detailed demonstration of how this can be done.
Simple Graphs
SpatialGraphs.rastergraph
— Functionrastergraph(
raster::Raster;
directed::Bool = true,
condition::Function = is_data,
cardinal_neighbors_only::Bool = false
)
Construct a RasterGraph
or RasterDiGraph
(if directed = true
) from a raster dataset.
Parameters
raster
: A Rasters.Raster
on which to base the graph. Any pixel in raster
with a value not equal to raster.missingval
will be assigned a vertex in the graph (corresponding to its centroid). The values in the raster can also be used to determine which vertices to connect. See condition
below for more information.
Arguments
directed
: A Bool
determining whether the graph should be directed.
condition
: A function that compares the values in raster
for two neighbors to determine if those neighbors should be connected. The function must compare two values and return either true
or false
. Useful functions to use here include <
, <=
, ==
, etc. The first argument to condition
corresponds to the source vertex, and the second argument corresponds to the destination vertex. So, if you only want to connect sources to destinations that have a lower value in raster
(e.g. in the case of developing a hydrologic flow graph based on elevation), then you would use >
for condition
. Defaults to is_data
, which results in neighbors being connected as long as they are not NoData (raster.missingval
). Note that if using an inequality function (or any function where the result depends on argument position), directed
should be set to true
. For undirected graphs, you can use either is_data
or ==
, or any other custom function where argument position doesn't matter, e.g. a function that determines whether the values in raster
are within a certain distance of each other.
cardinal_neighbors_only
: A Bool
stating whether only cardinal neighbors should be connected. By default, both cardinal and diagonal neighbors are connected. Note that this particular function does NOT account for the increased distance between diagonal neighbors (as compared to the distance between cardinal neighbors), since for a SimpleGraph
or SimpleDiGraph
, all weights are effectively set to 1.
SpatialGraphs.make_simple_raster_graph
— Functionmake_simple_raster_graph(
raster::Raster,
vertex_raster::Raster;
directed::Bool = false,
condition::Function = is_data,
cardinal_neighbors_only::Bool = false
)
Construct a SimpleGraph
or SimpleDiGraph
(if directed = true
) based on two rasters (raster
and vertex_raster
). This function is useful if you already have a custom vertex raster and don't want SpatialGraphs.jl to make one for you. The vertex raster denotes the spatial locations of each vertex in the graph, and raster
is used to construct the graph and determine which vertices to connect.
Parameters
raster
: A Rasters.Raster
on which to base the graph. Any pixel in raster
with a value not equal to raster.missingval
will be assigned a vertex in the graph (corresponding to its centroid). The values in the raster can also be used to determine which vertices to connect. See condition
below for more information.
vertex_raster
: A Rasters.Raster
with integer values ranging from 1:n, where n is the number of unique vertices in the graph.
Arguments
directed
: A Bool
determining whether the graph should be directed.
condition
: A function that compares the values in raster
for two neighbors to determine if those neighbors should be connected. The function must compare two values and return either true
or false
. Useful functions to use here include <
, <=
, ==
, etc. The first argument to condition
corresponds to the source vertex, and the second argument corresponds to the destination vertex. So, if you only want to connect sources to destinations with a lower value in raster
(e.g. in the case of developing a hydrologic flow graph based on elevation), then you would use >
for condition
. Defaults to is_data
, which results in neighbors being connected as long as they are not NoData in raster
(raster.missingval
). Note that if using an inequality function (or any function where the result depends on argument position), the graph must be directed. For undirected graphs, you can use either is_data
or ==
, or any other custom function where argument position doesn't matter, e.g. a function that determines whether the values in raster
are within a certain distance of each other.
cardinal_neighbors_only
: A Bool
stating whether only cardinal neighbors should be connected. By default, both cardinal and diagonal neighbors are connected. Note that this particular function does NOT account for the increased distance between diagonal neighbors (as compared to the distance between cardinal neighbors), since for a SimpleGraph
or SimpleDiGraph
, all weights are effectively set to 1.
Weighted Graphs
SpatialGraphs.weightedrastergraph
— Functionweightedrastergraph(
weight_raster::Raster;
directed::Bool = false,
condition_raster::Raster = weight_raster,
condition::Function = is_data,
cardinal_neighbors_only::Bool = false,
connect_using_avg_weights::Bool = true
)
Construct a WeightedRasterGraph
or WeightedRasterDiGraph
(if directed = true
) from a raster dataset. The weight raster denotes the edge weight correponding to each vertex. Since edges are between rather than on vertices, edge weights are calculated as the average of the weights for each vertex.
Parameters
weight_raster
: A Rasters.Raster
containing values that, where applicable based on other arguments, determine which pixels to connect and the edge weights between pixels. Any pixel in weight_raster
with a value not equal to weight_raster.missingval
will be assigned a vertex in the graph (corresponding to its centroid).
Arguments
directed
: A Bool
determining whether the graph should be directed.
condition_raster
: A raster with values that can be used to determine whether two neighboring pixels should be connected. For example, an elevation raster can be used to create a hydologic flow graph. Defaults to the weight_raster
.
condition
: A function that compares the values in condition_raster
for two neighbors to determine if those neighbors should be connected. The function must compare two values and return either true
or false
. Useful functions to use here include <
, <=
, ==
, etc. The first argument to condition
corresponds to the source vertex, and the second argument corresponds to the destination vertex. So, if you only want to connect sources to destinations that have a lower value in condition_raster
(e.g. in the case of developing a hydrologic flow graph based on elevation), then you would use >
for condition
. Defaults to is_data
, which results in neighbors being connected as long as they are not NoData in condition_raster
(condition_raster.missingval
). Note that if using an inequality function (or any function where the result depends on argument position), directed
should be set to true
. For undirected graphs, you can use either is_data
or ==
, or any other custom function where argument position doesn't matter, e.g. a function that determines whether the values in condition_raster
are within a certain distance of each other.
cardinal_neighbors_only
: A Bool
stating whether only cardinal neighbors should be connected. By default, both cardinal and diagonal neighbors are connected. Note that when determining weights between diagonal neighbors, the increased distance between them (as compared to the distance between cardinal neighbors) is accounted for.
connect_using_avg_weights
: Bool
. This is intended to offer methods that complement those used in Circuitscape.jl and Omniscape.jl. In this context, weights (the values in weight_raster
) are in units of electrical resistance. If false
, the weight between two nodes with resistances R1 and R2 is calculated by converting resistance to conductances, taking the average, then taking the inverse of the result to convert back to resistance: 1 / ((1/R1 + 1/R2) / 2)
. connect_using_avg_weights = false
corresponds to the default settings in Circuitscape. Defaults to true
, in which case the simple average (adjusted for distance in the case of diagonal neighbors) of the weights in weight_raster
is used.
SpatialGraphs.make_weighted_raster_graph
— Functionmake_weighted_raster_graph(
weight_raster::Raster,
vertex_raster::Raster;
directed::Bool = false,
condition_raster::Raster = weight_raster,
condition::Function = is_data,
cardinal_neighbors_only::Bool = false,
connect_using_avg_weights::Bool = true,
combine::Function = min
)
Construct a SimpleWeightedGraph
or SimpleWeightedDiGraph
(if directed = true
) based on vertex and weight rasters. This function is useful if you already have a custom vertex raster and don't want SpatialGraphs.jl to make one for you. The vertex raster denotes the spatial locations of each vertex in the graph, and the weight raster denotes the edge weight correponding to each vertex. Since edges are between rather than on vertices, edge weights are calculated as the average of the weights for each vertex being connected.
Parameters
weight_raster
: A Rasters.Raster
containing values that, where applicable based on other arguments, determine which pixels to connect and the edge weights between pixels. Any pixel in weight_raster
with a value not equal to weight_raster.missingval
will be assigned a vertex in the graph (corresponding to its centroid).
vertex_raster
: A Rasters.Raster
with integer values ranging from 1:n, where n is the number of unique vertices in the graph.
Arguments
directed
: A Bool
determining whether the graph should be directed.
condition_raster
: A raster with values that can be used to determine whether two neighboring pixels should be connected. For example, an elevation raster can be used to create a hydologic flow graph. Defaults to the weight_raster
.
condition
: A function that compares the values in condition_raster
for two neighbors to determine if those neighbors should be connected. The function must compare two values and return either true
or false
. Useful functions to use here include <
, <=
, ==
, etc. The first argument to condition
corresponds to the source vertex, and the second argument corresponds to the destination vertex. So, if you only want to connect sources to destinations that have a lower value in condition_raster
(e.g. in the case of developing a hydrologic flow graph based on elevation), then you would use >
for condition
. Defaults to is_data
, which results in neighbors being connected as long as they are not NoData in condition_raster
(condition_raster.missingval
). Note that if using an inequality function (or any function where the result depends on argument position), directed
should be set to true
. For undirected graphs, you can use either is_data
or ==
, or any other custom function where argument position doesn't matter, e.g. a function that determines whether the values in condition_raster
are within a certain distance of each other.
cardinal_neighbors_only
: A Bool
stating whether only cardinal neighbors should be connected. By default, both cardinal and diagonal neighbors are connected. Note that when determining weights between diagonal neighbors, the increased distance between them (as compared to the distance between cardinal neighbors) is accounted for.
connect_using_avg_weights
: Bool
. This is intended to offer methods that complement those used in Circuitscape.jl and Omniscape.jl. In this context, weights (the values in weight_raster
) are in units of electrical resistance. If false
, the weight between two nodes with resistances R1 and R2 is calculated by converting resistance to conductances, taking the average, then taking the inverse of the result to convert back to resistance: 1 / ((1/R1 + 1/R2) / 2)
. connect_using_avg_weights = false
correspondes to the default settings in Circuitscape. Defaults to true
, in which case the simple average (adjusted for distance in the case of diagonal neighbors) of the weights in weight_raster
is used.
combine
: In the case that there are multiple edges defined for a single pair of vertices, how should the weight be chosen? Defaults to min
. See the docs for SparseArrays.sparse()
for more information.