add examples to docs

Author: arashbm

docs/examples/index.rst

@@ -5,4 +5,8 @@ Examples
    :maxdepth: 1
 
    isotropic
+   static_network_basics
+   static_hypergraph_basics
+   network_manipulation
+   temporal_network_basics
    temporal_network

docs/examples/network_manipulation.rst

@@ -0,0 +1,74 @@
+Modifying networks the immutable way
+====================================
+
+All Reticula networks are immutable.  Instead of changing a graph in place,
+operations like adding or removing edges return a new object. This tutorial
+demonstrates the basic ``with_*`` and ``without_*`` functions.
+
+Adding edges
+------------
+
+Start with a simple cycle and add a few new links::
+
+   >>> import reticula as ret
+   >>> g = ret.cycle_graph[ret.int64](size=8)
+   >>> extra = [(0, 5), (1, 6)]
+   >>> g2 = ret.with_edges(g, extra)
+   >>> len(g.edges()), len(g2.edges())
+   (8, 10)
+
+Because ``g`` is unchanged we can safely reuse it elsewhere.
+
+Removing vertices
+-----------------
+
+Vertices can be removed in a similar fashion::
+
+   >>> g3 = ret.without_vertices(g2, [0, 1])
+   >>> len(g3.vertices())
+   6
+
+Any edges incident to the removed vertices disappear automatically.
+
+Adding and removing multiple items at once is more efficient than
+repeatedly calling these functions in a loop, so try to batch your
+operations when possible.
+
+
+Induced subgraphs
+-----------------
+
+A subset of a network can be created by selecting a set of vertices or edges,
+using :py:func:`vertex_induced_subgraph` or :py:func:`edge_induced_subgraph`.
+For example, to create a subgraph of the first five vertices::
+
+   >>> g4 = ret.vertex_induced_subgraph(g, [0, 1, 2, 3, 4])
+   >>> len(g4.vertices()), len(g4.edges())
+   (5, 4)
+
+
+Vertex and edge occupation
+--------------------------
+
+Another way to create a subset of the network is to prbabilistically keep a
+fraction of the vertices or edges. This is useful for sampling large networks.
+Inspired by the percolation literature, Reticula calls this process occupation.
+
+Vertex or edge occupation is done with a uniform probability, using :py:func:`uniformly_occupy_edges` and :py:func:`uniformly_occupy_edges`::
+
+   >>> gen = ret.mersenne_twister(42)
+   >>> g5 = ret.uniformly_occupy_vertices(
+   ...   g, occupation_prob=0.5, random_state=gen)
+   >>> g5
+   <undirected_network[int64] with 5 verts and 2 edges>
+
+Similarly, the probability of keeping edges can be determined using a lambda
+function. Here for example we set the odd vertices to be kept (occupied) at a
+higher probability::
+
+   >>> gen = ret.mersenne_twister(42)
+   >>> g6 = ret.occupy_vertices(g,
+   ...   lambda x: 0.3 if x%2 == 0 else 0.7,
+   ...   random_state=gen)
+   >>> g6
+   <undirected_network[int64] with 5 verts and 3 edges>

docs/examples/static_hypergraph_basics.rst

@@ -0,0 +1,104 @@
+Getting started with hypergraphs
+================================
+
+Hypergraphs generalise standard graphs by allowing edges to contain any number
+of vertices.  Reticula provides simple ways of generating and inspecting them.
+Reticula provides both directed and undirected hypergraphs. Make sure you have
+installed the library with ``pip install reticula`` and imported it as ``ret``::
+
+   >>> import reticula as ret
+
+Creating a random hypergraph
+----------------------------
+
+Let's stat with a simple example of a random hypergraph. The function :py:func:`random_uniform_hypergraph` generates a hypergraph with a given number of vertices, edges, and edge degree, each edge existing independently with a given probability. It requires a pseudo random number generator, which we create here with :py:func:`mersenne_twister`::
+
+   >>> gen = ret.mersenne_twister(42)
+   >>> h = ret.random_uniform_hypergraph[ret.int64](
+   ...     size=100, edge_degree=3, edge_prob=0.01, random_state=gen)
+   >>> h
+   <undirected_hypergraph[int64] with 100 verts and 1659 edges>
+
+Examining the structure
+-----------------------
+
+Edges and vertices are again simple Python lists::
+
+   >>> h.vertices()[:5]
+   [0, 1, 2, 3, 4]
+   >>> h.edges()[:2]
+   [undirected_hyperedge[int64]([0, 3, 96]), undirected_hyperedge[int64]([0, 4, 11])]
+   >>> len(h.edges())
+   1659
+
+Hypergraph degrees count how many hyperedges a vertex belongs to::
+
+   >>> ret.degree(h, 0)
+   3
+
+Since hypergraph h is undirected, the degree of a vertex is the same as its in- and
+out-degree::
+
+   >>> ret.in_degree(h, 0)
+   3
+   >>> ret.out_degree(h, 0)
+   3
+   >>> ret.incident_degree(h, 0)
+   3
+
+You can also probe each edge, for example to find out how many vertices it
+contains, using :py:func:`edge_degree`. This is also known as the edge degree
+or edge rank::
+
+  >>> e = h.edges()[0]
+  >>> e
+  undirected_hyperedge[int64]([0, 3, 96])
+  >>> ret.edge_degree(e)
+  3
+
+This also provices directed variants, but they are identical for undirected hypergraphs::
+  >>> ret.in_edge_degree(e)
+  3
+  >>> ret.out_edge_degree(e)
+  3
+
+Hyperedge mutators and mutated vertices work similarly to undirected edges in
+dyadic networks. The mutator vertices are those that can change the state of
+the other vertices through the hyperedge, while the mutated vertices are those
+whose state can change because of the mutators. For undirected hyperedges, all
+vertices incident to the hyperedge can act as mutators or mutated vertices::
+
+   >>> e.mutator_verts()
+   [0, 3, 96]
+   >>> e.mutated_verts()
+   [0, 3, 96]
+   >>> e.incident_verts()
+   [0, 3, 96]
+
+For directed hyperedges, the mutator and mutated vertices can be different::
+
+   >>> e = ret.directed_hyperedge[int64]([1, 2, 3], [4, 5, 6])
+   >>> e.mutator_verts()
+   [1, 2, 3]
+   >>> e.tails()
+   [1, 2, 3]
+
+   >>> e.mutated_verts()
+   [4, 5, 6]
+   >>> e.heads()
+   [4, 5, 6]
+
+   >>> e.incident_verts()
+   [1, 2, 3, 4, 5, 6]
+
+
+Connected components
+--------------------
+
+Connected components work exactly the same as for dyadic static graphs::
+
+   >>> comps = ret.connected_components(h)
+   >>> comps
+   [<component[int64] of 100 nodes: {99, 98, 97, 96, 95, ...})>]
+   >>> len(comps)
+   1

docs/examples/static_network_basics.rst

@@ -0,0 +1,145 @@
+Basic static network exploration
+================================
+
+This tutorial introduces a few simple functions for static undirected networks.
+All examples assume that you already installed Reticula with ``pip install
+reticula`` and have ``ret`` imported as the usual alias::
+
+   >>> import reticula as ret
+
+Generating a random network
+---------------------------
+
+We start by creating a random :math:`G(n,p)` network.  The function
+:py:func:`random_gnp_graph` requires a pseudo random number generator, created
+here with :py:func:`mersenne_twister`::
+
+   >>> gen = ret.mersenne_twister(42)
+   >>> g = ret.random_gnp_graph[ret.int64](n=100, p=0.02, random_state=gen)
+   >>> g
+   <undirected_network[int64] with 100 verts and 110 edges>
+
+Inspecting the network
+----------------------
+
+The vertices and edges can be retrieved as Python lists::
+
+   >>> g.vertices()[:5]
+   [0, 1, 2, 3, 4]
+   >>> g.edges()[:3]
+   [undirected_edge[int64](0, 16), undirected_edge[int64](0, 20), ...]
+
+Several helper functions report basic properties such as the number of vertices
+or edges and the network density::
+
+   >>> len(g.vertices())
+   100
+   >>> len(g.edges())
+   110
+   >>> ret.density(g)
+   0.022223
+
+You can probe the edges of the network, for example to find out how which nodes
+are connected by a specific edge.
+
+Mutator vertices are those vertices that can change the state of the other
+nodes through a specific edge, and mutated vertices are those whose internal
+state can change because of mutators. For undirected_network, all nodes
+incident to an edge can act as mutators or mutated vertices::
+
+   >>> e = g.edges()[0]
+   >>> e
+   undirected_edge[int64](0, 16)
+   >>> e.mutator_verts()
+   [0, 16]
+   >>> e.mutated_verts()
+   [0, 16]
+   >>> e.incident_verts()
+   [0, 16]
+
+This is not the case for directed networks, where the mutator and mutated
+vertices can be different.
+
+   >>> e = ret.directed_edge[int64](0, 16)
+   >>> e
+   directed_edge[int64](0, 16)
+   >>> e.mutator_verts()
+   [0]
+   >>> e.tail()
+   0
+   >>> e.mutated_verts()
+   [16]
+   >>> e.head()
+   16
+   >>> e.incident_verts()
+   [0, 16]
+
+
+Connected components
+--------------------
+
+The function :py:func:`connected_components` returns all components of an
+undirected network::
+
+   >>> comps = ret.connected_components(g)
+   >>> lcc = max(comps, key=len)
+   >>> lcc
+   <component[int64] of 93 nodes: {99, 96, 95, 94, 92, 91, 90, 89, 88, 87, ...})>
+   >>> len(lcc)
+   93
+
+If you are only interested in the largest component, you can directly use
+:py:func:`largest_connected_component`::
+
+  >> lcc = ret.largest_connected_component(g)
+  >> lcc
+  <component[int64] of 93 nodes: {99, 96, 95, 94, 92, 91, 90, 89, 88, 87, ...})>
+
+
+Degrees and neighbourhoods
+--------------------------
+
+Degree information for each vertex is accessible via :py:func:`degree`::
+
+   >>> ret.degree(g, 0)
+   4
+
+Since graph g is undirected, the degree of a vertex is the same as its in- and
+out-degree::
+
+   >>> ret.in_degree(g, 0)
+   4
+   >>> ret.out_degree(g, 0)
+   4
+   >>> ret.incident_degree(g, 0)
+   4
+
+You can also directly generate the degree sequence of the network, using
+:py:func:`degree_sequence`::
+
+   >>> ret.degree_sequence(g)
+   [4, 1, 0, 6, 1, 2, 1, 0, ...]
+   >>> ret.in_degree_sequence(g)
+   [4, 1, 0, 6, 1, 2, 1, 0, ...]
+   >>> ret.out_degree_sequence(g)
+   [4, 1, 0, 6, 1, 2, 1, 0, ...]
+   >>> ret.incident_degree_sequence(g)
+   [4, 1, 0, 6, 1, 2, 1, 0, ...]
+
+You can get a list of neighbours of a node::
+
+   >>> g.neighbours(0)
+   [20, 51, 31, 16]
+
+
+Similar to before, you can also get the successors and predecessors, the
+directed in- and out-neighbours, of a vertex::
+
+   >>> g.successors(0)
+   [20, 51, 31, 16]
+   >>> g.prdecessors(0)
+   [20, 51, 31, 16]
+
+
+These simple building blocks will let you start exploring static networks in
+Reticula.