clean up dockstrings

Author: Vincent Landau

docs/src/userguide.md

@@ -3,7 +3,13 @@
 ## Building Graphs from Rasters
 
 SpatialGraphs.jl offers several functions for constructing graphs from raster
-data.
+data, which are detailed below. Once you have converted your data to an
+[`AbstractSpatialGraph`](@ref 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](@ref Examples) section for a detailed 
+demonstration of how this can be done.
 
 ### Simple Graphs
 ```@docs

src/rastergraphs.jl

@@ -2,11 +2,11 @@
     make_vertex_raster(A::Raster)
 
 Constuct a vertex raster (a raster where the value of each pixel corresponds
-to its ID in a graph, and 0s correspond to NoData). Returns a Raster. This 
+to its ID in a graph, and 0s correspond to NoData). Returns a `Raster``. This 
 function is recommended for internal use only.
 
 ## Parameters
-`A`: The Raster from which a graph will be built, which is used as the
+`A`: The `Raster`` from which a graph will be built, which is used as the
 reference for building the vertex raster. Pixels with NoData (`A.missingval`)
 are skipped (no vertex is assigned). Pixels with NoData will get a value of 0 in
 the vertex raster.
@@ -36,14 +36,14 @@ end
     )
 
 Construct a `WeightedRasterGraph` or `WeightedRasterDiGraph` (if 
-`directed = true`) from a raster dataset. The weight raster,  denotes
+`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 contained values that, where applicable 
-based on other arguments, determines which pixels to connect and the edge 
+`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). 
@@ -53,23 +53,23 @@ to its centroid).
 
 `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.
+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 with 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 (`condition_raster.missingval`) in `condition_raster`. Note that if using
+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), 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 `condition_raster`
-are within a certain distance of each other.
+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
@@ -86,7 +86,7 @@ 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.
+neighbors) of the weights in `weight_raster` is used.
 
 """
 function weightedrastergraph(
@@ -118,18 +118,18 @@ function weightedrastergraph(
 end
 
 """
-    RasterGraph(
+    rastergraph(
         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.
+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` 
+`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
@@ -156,9 +156,10 @@ 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.
+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.
 """
 function rastergraph(
         raster::Raster;
@@ -217,21 +218,25 @@ 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
+`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 `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.
+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
@@ -248,7 +253,7 @@ 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.
+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
@@ -292,8 +297,7 @@ end
         vertex_raster::Raster;
         directed::Bool = false,
         condition::Function = is_data,
-        cardinal_neighbors_only::Bool = false,
-        combine::Function = min
+        cardinal_neighbors_only::Bool = false
     )
 
 Construct a `SimpleGraph` or `SimpleDiGraph` (if `directed = true`) based on 
@@ -304,7 +308,7 @@ 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` 
+`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
@@ -316,60 +320,47 @@ 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 `condition_raster` for two
+`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 `condition_raster` (e.g. in the case of developing a hydrologic flow 
+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 (`condition_raster.missingval`) in `condition_raster`. Note that if using
+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 `condition_raster`
+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 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_raster_val`: `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 of the weights (adjusted for distance in the case of diagonal 
-neighbors) in `weight_raster` are 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.
+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.
 """
 function make_simple_raster_graph(
         raster::Raster,
         vertex_raster::Raster;
         directed::Bool = false,
         condition::Function = is_data,
-        cardinal_neighbors_only::Bool = false,
-        combine::Function = min
+        cardinal_neighbors_only::Bool = false
     )
+
+    # combine and connect_using_avg_weights don't matter for simple graphs,
+    # so use defaults
     g = make_raster_graph(
         raster,
         vertex_raster,
         directed = directed,
         weighted = false,
         condition_raster = raster,
         condition = condition,
-        cardinal_neighbors_only = cardinal_neighbors_only,
-        combine = combine
+        cardinal_neighbors_only = cardinal_neighbors_only
     )
 
     return g