add examples to docs

Author: arashbm

docs/algorithms/assortativity.rst

@@ -1,12 +1,22 @@
 Assortativity
 =============
 
-.. note::
-   The methods in this section rely on calculating the Pearson correlation
-   coefficient between pairs of value sequences. If the network is regular (i.e.
-   all vertices have equal degree or label) or if the network has fewer than two
-   pairs of interacting vertices, the result of calculating assortativity will
-   be :cpp:`NaN`.
+Assortativity is a measure of preference of nodes to attach to other nodes
+similar to themselves. In many cases, researchers are interested in degree
+assortaivity, which measures the correlation between the degrees of connected
+vertices. However, assortativity can also be calculated for other node attributes :cite:p:`newman2003mixing`.
+
+Reticula provides a set of functions to calculate assortativity in directed
+and undirected networks, either in terms of degree or other numerical node
+attributes.
+
+.. note ::
+
+  The methods in this section rely on calculating the Pearson correlation
+  coefficient between pairs of value sequences. If  all connected vertices
+  have equal degree or attribute, or if the network has fewer than two pairs
+  of interacting vertices, the result of calculating assortativity will be
+  :cpp:`NaN`.
 
 
 Degree assortativity
@@ -32,6 +42,13 @@ Calculates degree assortativity for undirected dyadic and hypergraph static
 networks. Assortativity is calculated through Pearson correlation coefficient
 over degrees of all pairs of interacting vertices.
 
+.. code-block:: pycon
+
+  >>> import reticula as ret
+  >>> gen = ret.mersenne_twister(42)
+  >>> net = ret.random_gnp_graph[ret.int64](n=128, p=0.05, random_state=gen)
+  >>> ret.degree_assortativity(net)
+  0.012174626999704952
 
 Directed networks
 ^^^^^^^^^^^^^^^^^
@@ -62,6 +79,17 @@ Calculates in-/out-degree assortativity for directed dyadic and hypergraph
 static networks. Assortativity is calculated through Pearson correlation
 coefficient over degrees of all pairs of interacting vertices.
 
+.. code-block:: pycon
+
+  >>> import reticula as ret
+  >>> gen = ret.mersenne_twister(42)
+  >>> net = ret.random_directed_gnp_graph[ret.int64](
+  ...             n=128, p=0.05, random_state=gen)
+  >>> ret.in_in_degree_assortativity(net)
+  -0.008986050522667814
+  >>> ret.in_out_degree_assortativity(net)
+  -0.05295305364798128
+
 Numerical attribute assortativity
 ---------------------------------
 
@@ -95,13 +123,25 @@ correlation coefficient over the value of the given function over all pairs of
 interacting vertices.
 
 
+.. code-block:: pycon
+
+  >>> import reticula as ret
+  >>> import math
+  >>> gen = ret.mersenne_twister(42)
+  >>> net = ret.random_gnp_graph[ret.int64](
+  ...       n=128, p=0.05, random_state=gen)
+  >>> ret.attribute_assortativity(net,
+  ...       lambda v: math.log(ret.degree(net, v)))
+  0.018211216997337246
+
+
 .. tab-set::
 
   .. tab-item:: Python
     :sync: python
 
     .. py:function:: attribute_assortativity(undirected_network, \
-        attribute_map: dict[network.edge_type(), float], \
+        attribute_map: dict[network.vertex_type(), float], \
         default_value : float) -> float
       :noindex:
 
@@ -110,17 +150,32 @@ interacting vertices.
 
     .. cpp:function:: template <\
         network_edge EdgeT, \
-        mapping<EdgeT, double> MapT> \
+        mapping<VertT, double> MapT> \
       double attribute_assortativity(\
           const network<EdgeT>& net, \
           const MapT& attribute_map, \
           double default_value)
 
 Calculates assortativity of the given mapping of vertices to floating-point
-(dictionary) for undirected dyadic and hypergraph static networks. Assortativity
-is calculated through Pearson correlation coefficient over the value of the
-given mapping over all pairs of interacting vertices. If a vertex is not present
-in the mapping, the value of the argument :cpp:`default_value` is used.
+(dictionary) for undirected dyadic and hypergraph static networks.
+Assortativity is calculated through Pearson correlation coefficient over the
+value of the given mapping over all pairs of interacting vertices. If a vertex
+is not present in the mapping, the value of the argument :cpp:`default_value`
+is used.
+
+
+.. code-block:: pycon
+
+  >>> import reticula as ret
+  >>> gen = ret.mersenne_twister(42)
+  >>> net = ret.random_gnp_graph[ret.int64](
+  ...       n=128, p=0.05, random_state=gen)
+  >>> attribute_map = {
+  ...       v: math.log(ret.degree(net, v))
+  ...       for v in net.vertices()}
+  >>> ret.attribute_assortativity(net, attribute_map, default_value=0.0)
+  0.018211216997337246
+
 
 
 Directed networks
@@ -132,8 +187,8 @@ Directed networks
     :sync: python
 
     .. py:function:: attribute_assortativity(directed_network, \
-        mutator_attribute_fun: Callable[[network.edge_type()], float], \
-        mutated_attribute_fun: Callable[[network.edge_type()], float]) -> float
+        mutator_attribute_fun: Callable[[network.vertex_type()], float], \
+        mutated_attribute_fun: Callable[[network.vertex_type()], float]) -> float
 
   .. tab-item:: C++
     :sync: cpp
@@ -162,6 +217,17 @@ representation of a directed link) is calculated from the function
 :cpp:`mutator_attribute_fun`, and the mutated vertex (head of the arrow) from
 :cpp:`mutated_attribute_fun`.
 
+.. code-block:: pycon
+
+   >>> import reticula as ret
+   >>> import math
+   >>> gen = ret.mersenne_twister(42)
+   >>> net = ret.random_directed_gnp_graph[ret.int64](
+   ...       n=128, p=0.05, random_state=gen)
+   >>> ret.attribute_assortativity(net,
+   ...       lambda tail: math.log(ret.in_degree(net, tail) + 1),
+   ...       lambda head: math.log(ret.out_degree(net, head) + 1))
+   -0.05753797100756569
 
 .. tab-set::
 
@@ -198,3 +264,19 @@ argument :cpp:`mutator_default_value` or :cpp:`mutated_attribute_fun` is used.
 The associated value of the mutator (tail of the arrow representation of a
 directed link) is calculated from the function :cpp:`mutator_attribute_fun`, and
 the mutated vertex (head of the arrow) from :cpp:`mutated_attribute_fun`.
+
+.. code-block:: pycon
+
+  >>> import reticula as ret
+  >>> gen = ret.mersenne_twister(42)
+  >>> net = ret.random_directed_gnp_graph[ret.int64](
+  ...       n=128, p=0.05, random_state=gen)
+  >>> mutator_map = {
+  ...       tail: math.log(ret.in_degree(net, tail) + 1)
+  ...       for tail in net.vertices()}
+  >>> mutated_map = {
+  ...       head: math.log(ret.out_degree(net, head) + 1)
+  ...       for head in net.vertices()}
+  >>> ret.attribute_assortativity(net, mutator_map, mutated_map,
+  ...       mutator_default_value=0.0, mutated_default_value=0.0)
+  -0.05753797100756569

docs/algorithms/edge_degrees.rst

@@ -4,8 +4,9 @@ Edge degrees (orders)
 Degree functions
 ----------------
 
-There are multiple ways of defining the degrees for (hyper-)edges depending on
-the type of edge. All edge types have the following degree functions defined:
+There are multiple ways of defining the degrees (orders) for (hyper-)edges
+depending on the type of edge. All edge types have the following degree
+functions defined:
 
 * **Edge in-degree** referes to the number of vertices that are in-incident to
   the edge, i.e., the cardinality of the set of mutator vertices of the edge.
@@ -17,7 +18,7 @@ the type of edge. All edge types have the following degree functions defined:
 .. note::
    Unlike :ref:`vertex degrees <algorithms/vertex_degrees:Vertex degrees>`, edge degree
    functions do not require a network to be passed as the first argument. This
-   is because the degree of an edge can be determined by the edge itself.
+   is because the degree of an edge can be determined from the edge itself.
 
 .. tab-set::
 
@@ -43,9 +44,29 @@ the type of edge. All edge types have the following degree functions defined:
         std::size_t edge_incident_degree(const EdgeT& edge)
 
 
-For undirected edges, **degree** of a edge referes to the incident-degree of
-that edge. For directed edges, the word degree on its own is vaguely-defined.
-In hypergraphs, this is commonly refered to as the *order* of the edge.
+.. code-block:: pycon
+
+  >>> import reticula as ret
+  >>> edge = ret.undirected_edge[ret.int64](0, 1)
+  >>> ret.edge_in_degree(edge)
+  2
+  >>> ret.edge_out_degree(edge)
+  2
+  >>> ret.edge_incident_degree(edge)
+  2
+  >>> hyperedge = ret.directed_hyperedge[ret.int64]([0, 1, 2], [2, 3])
+  >>> ret.edge_in_degree(hyperedge)
+  3
+  >>> ret.edge_out_degree(hyperedge)
+  2
+  >>> ret.edge_incident_degree(hyperedge)
+  4
+
+
+For undirected edges, **degree** of a (hyper)edge referes to the
+incident-degree of that edge. For directed edges, the word degree on its own is
+vaguely-defined. In hypergraphs, this is commonly refered to as the *order* of
+the edge.
 
 
 .. tab-set::
@@ -61,7 +82,15 @@ In hypergraphs, this is commonly refered to as the *order* of the edge.
     .. cpp:function:: template <undirected_network_edge EdgeT> \
         std::size_t edge_degree(const EdgeT& edge)
 
+.. code-block::
 
+  >>> import reticula as ret
+  >>> edge = ret.undirected_edge[ret.int64](0, 1)
+  >>> ret.edge_degree(edge)
+  2
+  >>> edge = ret.undirected_hyperedge[ret.int64]([0, 1, 2, 3])
+  >>> ret.edge_degree(edge)
+  4
 
 Edge degree sequences
 ---------------------
@@ -104,6 +133,24 @@ pair sequence is a sequence of tuples of in- and out-degrees of edges.
           edge_in_out_degree_pair_sequence(\
             const network<EdgeT>& net)
 
+.. code-block:: pycon
+
+  >>> import reticula as ret
+  >>> gen = ret.mersenne_twister(42)
+  >>> g = ret.random_directed_expected_degree_sequence_hypergraph[ret.int64](
+  ...            vertex_in_out_weight_sequence=[(2, 2), (2, 2), (1, 1), (1, 1)],
+  ...            edge_in_out_weight_sequence=[(2, 2), (2, 2), (1, 1), (1, 1)],
+  ...            random_state=gen)
+  >>> ret.edge_in_degree_sequence(g)
+  [0, 3, 4, 2]
+  >>> ret.edge_out_degree_sequence(g)
+  [2, 3, 2, 0]
+  >>> ret.edge_incident_degree_sequence(g)
+  [2, 4, 4, 2]
+  >>> ret.edge_in_out_degree_pair_sequence(g)
+  [(0, 2), (3, 3), (4, 2), (2, 0)]
+
+
 Similar to :cpp:func:`edge_degree`, edge degree sequence without a prefix is only defined
 for undirected networks.
 
@@ -119,3 +166,16 @@ for undirected networks.
 
     .. cpp:function:: template <undirected_network_edge EdgeT> \
         std::vector<std::size_t> edge_degree_sequence(const network<EdgeT>& net)
+
+.. code-block:: pycon
+
+  >>> import reticula as ret
+  >>> gen = ret.mersenne_twister(42)
+  >>> g = ret.random_expected_degree_sequence_hypergraph[ret.int64](
+  ...            vertex_weight_sequence=[2, 2, 1, 1],
+  ...            edge_weight_sequence=[2, 2, 1, 1],
+  ...            random_state=gen)
+  >>> g.edges()
+  [undirected_hyperedge[int64]([]), undirected_hyperedge[int64]([0, 1]), undirected_hyperedge[int64]([0, 1, 3])]
+  >>> ret.edge_degree_sequence(g)
+  [0, 2, 3]

docs/algorithms/graph_properties.rst

@@ -31,6 +31,14 @@ possible ordered pairs of distinct vertices.
 
 Note that in the presense of self-links, density might be higher than 1.
 
+.. code-block:: pycon
+
+  >>> import reticula as ret
+  >>> g = ret.cycle_graph[ret.int64](size=128)
+  >>> ret.density(g)
+  0.015748031496062992
+
+
 Temporal network observation window
 -----------------------------------
 

docs/algorithms/graphicallity.rst

@@ -22,6 +22,14 @@ Checks if the sequence can be the degree sequence of a valid undirected graph,
 containing no multi-edges or loops, based on the Erdős--Gallai algorithm
 :cite:p:`erdos1960graphs,choudum1986simple`.
 
+.. code-block:: pycon
+
+  >>> import reticula as ret
+  >>> ret.is_graphic([2, 2, 1, 1])
+  True
+  >>> ret.is_graphic([2, 2, 1, 2])
+  False
+
 
 Directed degree-pair sequence
 -----------------------------
@@ -49,3 +57,11 @@ and Wang :cite:p:`kleitman1973algorithms`.
 A degree pair sequence is a range (list) of pairs (2-tuples) of integers,
 where the first element of each item represents in-degree and the second item
 out-degree of one vertex.
+
+.. code-block:: pycon
+
+  >>> import reticula as ret
+  >>> ret.is_digraphic([(0, 1), (2, 0), (0, 1), (1, 1)])
+  True
+  >>> ret.is_digraphic([(0, 1), (2, 0), (0, 1), (1, 2)])
+  False

docs/algorithms/temporal_network_reachability.rst

@@ -26,6 +26,11 @@ one of those points, can spread to our target. The contrast between this and
 forward and backwards process is similar to the contrast between calculating in-
 and out-components on a directed acyclic graph.
 
+.. hint::
+
+   Check out a more in-depth :doc:`temporal network reachability example
+   </examples/temporal_network>` to learn more!
+
 From/to a single point
 ^^^^^^^^^^^^^^^^^^^^^^