highlight more prominently that GraphSpace != social network (#1156)

Author: Datseris

Project.toml

@@ -1,7 +1,7 @@
 name = "Agents"
 uuid = "46ada45e-f475-11e8-01d0-f70cc89e6671"
 authors = ["George Datseris", "Tim DuBois", "Aayush Sabharwal", "Ali Vahdati", "Adriano Meligrana"]
-version = "6.2.9"
+version = "6.2.10"
 
 [deps]
 CSV = "336ed68f-0bac-5ca0-87d4-7b16caf5d00b"

examples/schoolyard.jl

@@ -1,23 +1,25 @@
-# # Social networks with Graphs.jl
+# # [Social networks with Graphs.jl](@id social_networks)
 
 # ```@raw html
 # <video width="auto" controls autoplay loop>
 # <source src="../schoolyard.mp4" type="video/mp4">
 # </video>
 # ```
 
-# Many ABM frameworks provide graph infrastructure for analysing network properties of agents.
-# Agents.jl is no different in that aspect, we have [`GraphSpace`](@ref) for when spatial structure
-# is not important, but connections are.
+# Many ABM frameworks provide graph infrastructure for implementing network-based interactions
+# properties of agents. Agents.jl does not provide any graph infrastructure for network-based
+# interactions because it doesn't have to!
+# Since Agents.jl is implemented in Julia, it can integrate directly
+# with Julia's premier package for graphs, Graphs.jl.
 
-# What if you wish to model something a little more complex? Perhaps a school yard full of students
-# running around (in space), interacting via some social network. This is precisely the scenario that
-# the [MASON](https://cs.gmu.edu/~eclab/projects/mason/) ABM framework uses as an introductory example
-# in their [documentation](https://cs.gmu.edu/~eclab/projects/mason/manual.pdf).
+# _Note as mentioned in the documentation of [`GraphSpace`](@ref) that network-based
+# interactions should not be modeled as a space, even though other ABM frameworks
+# implement it as such as an only option!_
 
-# Rather than implementing an Agents.jl⸺specific graph structure, we can interface with
-# [Graphs.jl](https://github.com/JuliaGraphs/Graphs.jl): a high class library for managing
-# and implementing graphs, which can be re-used to establish social networks within existing spaces.
+# In this example we will model the situation where there is both a network structure
+# in agent interactions, but also a completely independent spatial structure in the model.
+# We will model a school yard full of students
+# running around (in space) _and_ interacting via some social network.
 
 # To begin, we load in some dependencies
 
@@ -47,21 +49,22 @@ const Student = ContinuousAgent{2,Float64}
 # ## Initialising the model
 
 function schoolyard(;
-    numStudents = 50,
-    teacher_attractor = 0.15,
-    noise = 0.1,
-    max_force = 1.7,
-    spacing = 4.0,
-    seed = 6998,
-    velocity = (0, 0),
-)
+        numStudents = 50,
+        teacher_attractor = 0.15,
+        noise = 0.1,
+        max_force = 1.7,
+        spacing = 4.0,
+        seed = 6998,
+        velocity = (0, 0),
+    )
     model = StandardABM(
         Student,
         ContinuousSpace((100, 100); spacing=spacing, periodic=false);
         agent_step!,
         properties = Dict(
             :teacher_attractor => teacher_attractor,
             :noise => noise,
+            ## This is the graph
             :buddies => SimpleWeightedDiGraph(numStudents),
             :max_force => max_force,
         ),
@@ -81,9 +84,10 @@ function schoolyard(;
     model
 end
 
-# Our model contains the `buddies` property, which is our Graphs.jl directed, weighted graph.
-# As we can see in the loop, we choose one `friend` and one `foe` at random for each `student` and
-# assign their relationship as a weighted edge on the graph.
+# Our model contains the `buddies` property, which is our Graphs.jl directed and weighted graph.
+# Here we chose one `friend` and one `foe` at random for each student` and assign their
+# relationship as a weighted edge on the graph.
+# By construction, the agent ID and graph node ID coincide.
 
 # ## Movement dynamics
 
@@ -132,7 +136,7 @@ end
 # that force should be in a positive or negative direction (*friend* or *foe*?).
 
 # The `findnz` function is something that may require some further explanation.
-# Graphs uses sparse vectors internally to efficiently represent data.
+# Graphs.jl uses sparse vectors internally to efficiently represent data.
 # When we find the `network` of our `student`, we want to convert the result to
 # a dense representation by **find**ing the **n**on-**z**ero (`findnz`) elements.
 

examples/sir.jl

@@ -1,12 +1,13 @@
-# # SIR model for the spread of COVID-19
+# # [SIR model for the spread of COVID-19](@id sir_graphspace)
 # ```@raw html
 # <video width="auto" controls autoplay loop>
 # <source src="../covid_evolution.mp4" type="video/mp4">
 # </video>
 # ```
 #
-# This example illustrates how to use `GraphSpace` and how to model agents on an graph
+# This example illustrates how to use [`GraphSpace`](@ref) and how to model agents moving on a graph
 # (network) where the transition probabilities between each node (position) is not constant.
+
 # ## SIR model
 
 # A SIR model tracks the ratio of Susceptible, Infected, and Recovered individuals within a population.

src/spaces/graph.jl

@@ -24,12 +24,20 @@ The underlying graph can be altered using [`add_vertex!`](@ref) and [`rem_vertex
 
 An example using `GraphSpace` is [SIR model for the spread of COVID-19](@ref).
 
-If you want to model social networks, where each agent is equivalent with a node of
-a graph, you're better of using `nothing` as the model space, and using
-a graph from Graphs.jl directly in the model parameters, as shown in the
-[Social networks with Graphs.jl](@ref) integration example.
+!!! note "Not for social networks!"
+    `GraphSpace` is not intended for "social-network-like" agent based
+    modelling, where each agent is equivalent with a node of a network/graph and
+    the graph represents connections between agents. Rather, `GraphSpace` is
+    suitable for when the coordinates of spatial locations are not as important as the
+    connections between them. `GraphSpace` is suited for e.g., modelling cities
+    where each can host many agents.
+
+    If you want to make a "social-network" like simulation, see [the integration with
+    Graphs.jl example](@ref social_networks). Typically you won't need a space structure at all!
+
 
 ## Distance specification
+
 In functions like [`nearby_ids`](@ref), distance for `GraphSpace` means
 the degree of neighbors in the graph (thus distance is always an integer).
 For example, for `r=2` includes first and second degree neighbors.