10_pathpy.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# 10 - Representing networks with `pathpy`\n",
    "\n",
    "*September 20 2022*\n",
    "\n",
    "We have covered the basics of data science with `python`. With this out of the way, we now introduce `pathpy`, a network analysis and visualization package that is being actively developed at my chair. If you are interested to participate in the development of this OpenSource project, you are welcome to contact me!\n",
    "\n",
    "Apart from being developed in our group `pathpy` has a couple of advantages compared to many other network analysis packages. First, it is easy to install as it has no dependencies that are not included in a default `anaconda` installation and it is a pure `python` package that does not require compilation. Second, `pathpy` has a user-friendly API that makes it easy to handle directed and undirected networks, networks with single and multiple edges, multi-layer networks, temporal networks, as well as networks with arbitrary node, edge or graph-level attributes. Third, it provides interactive HTML visualizations that can be directly displayed inside `jupyter` notebooks, making it particularly suitable for educational settings like this summer school. And finally, different from other packages it directly supports the analysis and visualization of time series data on networked systems, such as time-stamped edges or data on paths in networks.\n",
    "\n",
    "To get started, we first import `pathpy` and assign the local alias `pp`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "\n",
       "    <script charset=\"utf-8\">\n",
       "    // Load via requireJS if available (jupyter notebook environment)\n",
       "    try {\n",
       "    require.config({\n",
       "    paths: {\n",
       "    d3: \"https://d3js.org/d3.v5.min.js\".replace(\".js\", \"\")\n",
       "    }\n",
       "    });\n",
       "    console.log(\"OKAY: requireJS was detected\");\n",
       "    }\n",
       "    catch(err){\n",
       "    console.log(err);\n",
       "    console.log(\"ERROR: NO requireJS was detected\");\n",
       "    };\n",
       "    require(['d3'], function(d3){\n",
       "    console.log(\"OKAY: d3js was detected\");\n",
       "    });\n",
       "    </script>\n",
       "    "
      ],
      "text/plain": [
       "<IPython.core.display.HTML object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "import pathpy as pp\n",
    "import numpy as np"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If the `import` statement completes without error message, the installation was successful and we can now use `pathpy` to generate, analyse, and visualise networks. \n",
    "\n",
    "## Creating networks\n",
    "\n",
    "For this purpose `pathpy` provides the `Network` class. Calling the constructor will return an instance that represents an empty network with no nodes and no links. By default, networks in `pathpy` are directed. If you want to create an undirected network you can pass the parameter `directed=False` in the constructor. \n",
    "\n",
    "Printing the `Network` object will give a short string summary which tells whether the network is directed or undirected, as well as the number of unique nodes and links."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Uid:\t\t\t0x7fd940332400\n",
      "Type:\t\t\tNetwork\n",
      "Directed:\t\tTrue\n",
      "Multi-Edges:\t\tFalse\n",
      "Number of nodes:\t0\n",
      "Number of edges:\t0\n"
     ]
    }
   ],
   "source": [
    "n1 = pp.Network()\n",
    "print(n1)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A network is directed by default, but we can create an undirected network by passing the parameter `directed=False`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Uid:\t\t\t0x7fd9403324f0\n",
      "Type:\t\t\tNetwork\n",
      "Directed:\t\tFalse\n",
      "Multi-Edges:\t\tFalse\n",
      "Number of nodes:\t0\n",
      "Number of edges:\t0\n"
     ]
    }
   ],
   "source": [
    "n2 = pp.Network(directed=False)\n",
    "print(n2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The examples above show that each network has a unique identifier. By default, this unique ID is derived from the hash value of the underlying python object, which allows you to quickly check whether two variables actually refer to the same underlying object instance. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Uid:\t\t\t0x7fd9403324f0\n",
      "Type:\t\t\tNetwork\n",
      "Directed:\t\tFalse\n",
      "Multi-Edges:\t\tFalse\n",
      "Number of nodes:\t0\n",
      "Number of edges:\t0\n",
      "Uid:\t\t\t0x7fd940332760\n",
      "Type:\t\t\tNetwork\n",
      "Directed:\t\tFalse\n",
      "Multi-Edges:\t\tFalse\n",
      "Number of nodes:\t0\n",
      "Number of edges:\t0\n"
     ]
    }
   ],
   "source": [
    "n3=n2\n",
    "print(n3)\n",
    "\n",
    "n4 = pp.Network(directed=False)\n",
    "print(n4)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If you prefer to manage your own UIDs that are easier to remember, you can assign custom IDs by explicitly passing a uid property:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Uid:\t\t\tMyUndirectedNetwork\n",
      "Type:\t\t\tNetwork\n",
      "Directed:\t\tFalse\n",
      "Multi-Edges:\t\tFalse\n",
      "Number of nodes:\t0\n",
      "Number of edges:\t0\n"
     ]
    }
   ],
   "source": [
    "n = pp.Network(directed=False, uid='MyUndirectedNetwork')\n",
    "print(n)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The simplest way to add nodes and edges is to call the functions `add_node` and `add_edge`. In both cases, we can simply pass unique string identifiers of nodes, which will then be used as UIDs of the underlying node objects. To create an undirected network with three nodes and two edges, we can write: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Uid:\t\t\tExampleNetwork\n",
      "Type:\t\t\tNetwork\n",
      "Directed:\t\tFalse\n",
      "Multi-Edges:\t\tTrue\n",
      "Number of nodes:\t3\n",
      "Number of edges:\t2\n"
     ]
    }
   ],
   "source": [
    "n = pp.Network(directed=False, multiedges=True, uid='ExampleNetwork')\n",
    "n.add_node('a')\n",
    "n.add_node('b')\n",
    "n.add_node('c')\n",
    "n.add_edge('a', 'b')\n",
    "n.add_edge('b', 'c')\n",
    "print(n)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Unless we want to explicitly add isolated nodes with no incident edges, we can omit the explicit call of the `add_node` function. If we add edges any node that does not exist already will be created and added automatically. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Uid:\t\t\tExampleNetwork\n",
      "Type:\t\t\tNetwork\n",
      "Directed:\t\tFalse\n",
      "Multi-Edges:\t\tTrue\n",
      "Number of nodes:\t3\n",
      "Number of edges:\t2\n"
     ]
    }
   ],
   "source": [
    "n = pp.Network(directed=False, multiedges=True, uid='ExampleNetwork')\n",
    "n.add_edge('a', 'b')\n",
    "n.add_edge('b', 'c')\n",
    "print(n)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If we want to check explicitly whether a node exists before creating and edge, we can test this with the `in` operator on the set of node UIDS available via `Network.nodes.uids`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "False\n"
     ]
    }
   ],
   "source": [
    "print('d' in n.nodes.uids)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The following code will implicitly add a new node `d`, along with a new edge from `d` to `a`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Uid:\t\t\tExampleNetwork\n",
      "Type:\t\t\tNetwork\n",
      "Directed:\t\tFalse\n",
      "Multi-Edges:\t\tTrue\n",
      "Number of nodes:\t4\n",
      "Number of edges:\t4\n"
     ]
    }
   ],
   "source": [
    "n.add_edge('c', 'd')\n",
    "n.add_edge('d', 'a')\n",
    "print(n)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "True\n"
     ]
    }
   ],
   "source": [
    "print('d' in n.nodes.uids)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To count the number of nodes and edges in a network we can use the `number_of_nodes` and `number_of_edges` functions, or we could can compute `len` of `Network.nodes` and `Network.edges`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Network has 4 nodes and 4 edges\n",
      "Number of nodes: 4\n",
      "Number of edges: 4\n"
     ]
    }
   ],
   "source": [
    "print('Network has {0} nodes and {1} edges'.format(n.number_of_nodes(), n.number_of_edges()))\n",
    "print('Number of nodes: {0}'.format(len(n.nodes)))\n",
    "print('Number of edges: {0}'.format(len(n.edges)))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Node and Edge objects\n",
    "\n",
    "In the simple example above, we generated nodes and edges by calling the `add_node` and `add_edge` function of the network instance. Internally, nodes and edges are represented as objects of type `Node` and `Edge` that can be referenced by one or more instances of type `Network`. Just like a `Network`, each instance of a `Node` and `Edge` has a UID. In the example above, `pathpy` has automatically created `Node` and `Edge` instances and has assigned the UIDs `a`, `b`, `c`, and `d` to those nodes. We can access those node objects via the node container `Network.nodes`. We can iterate through this dictionary to print a summary of all node objects referenced with a network object:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Uid:\t\ta\n",
      "Type:\t\tNode\n",
      "\n",
      "Uid:\t\tb\n",
      "Type:\t\tNode\n",
      "\n",
      "Uid:\t\tc\n",
      "Type:\t\tNode\n",
      "\n",
      "Uid:\t\td\n",
      "Type:\t\tNode\n",
      "\n"
     ]
    }
   ],
   "source": [
    "for v in n.nodes:\n",
    "    print(v)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can also use the uid of a node to access a specific node object in a network by using the uid as an index to the `nodes` container:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Uid:\t\ta\n",
      "Type:\t\tNode\n",
      "\n"
     ]
    }
   ],
   "source": [
    "print(n.nodes['a'])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Importantly, the same node object can be added to multiple networks (which comes in handy if, for instance, we want to store that the same set of nodes is connected via different network topologies). Above, we have created a second (so far empty) undirected network. We can now add the node object with uid `a` to this network as follows:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Uid:\t\t\t0x7fd9403324f0\n",
      "Type:\t\t\tNetwork\n",
      "Directed:\t\tFalse\n",
      "Multi-Edges:\t\tFalse\n",
      "Number of nodes:\t1\n",
      "Number of edges:\t0\n"
     ]
    }
   ],
   "source": [
    "n2.add_node(n.nodes['a'])\n",
    "print(n2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "While a node object can be added to multiple network objects, each network can contain only a single node with a given uid. If we add another node with a previously existing uid, no new new is added."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Uid:\t\ta\n",
      "Type:\t\tNode\n",
      "\n",
      "Uid:\t\tb\n",
      "Type:\t\tNode\n",
      "\n",
      "Uid:\t\tc\n",
      "Type:\t\tNode\n",
      "\n",
      "Uid:\t\td\n",
      "Type:\t\tNode\n",
      "\n"
     ]
    }
   ],
   "source": [
    "n.add_node('a')\n",
    "for v in n.nodes:\n",
    "    print(v)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Similar to `nodes`, the `edges` container of the network contains all edges of a network and each edge is actually stored as an `Edge` object. Let us iterate through the edges container of network `n` to better understand this:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "---\n",
      "Uid:\t\t0x7fd940332430\n",
      "Type:\t\tEdge\n",
      "Directed:\tFalse\n",
      "Nodes:\t\t|'a', 'b'|\n",
      "\n",
      "---\n",
      "Uid:\t\t0x7fd940332bb0\n",
      "Type:\t\tEdge\n",
      "Directed:\tFalse\n",
      "Nodes:\t\t|'b', 'c'|\n",
      "\n",
      "---\n",
      "Uid:\t\t0x7fd940332610\n",
      "Type:\t\tEdge\n",
      "Directed:\tFalse\n",
      "Nodes:\t\t|'c', 'd'|\n",
      "\n",
      "---\n",
      "Uid:\t\t0x7fd9403325e0\n",
      "Type:\t\tEdge\n",
      "Directed:\tFalse\n",
      "Nodes:\t\t|'d', 'a'|\n",
      "\n"
     ]
    }
   ],
   "source": [
    "for e in n.edges:\n",
    "    print('---')\n",
    "    print(e)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We see that the edge container contains one `Edge` object instance for each edge that we added before. Each `Edge` has again a unique identifier, which has been automatically created in our example above. Since we have created the network as an undirected network, the edges are undirected as well. This is indicated in the property `Directed` as well as with the notation `|'a', 'b'|`. Just like for `Node` or `Network` objects, we can manually create a directed edge object with a custom UID that connects the two nodes `a` and `b` as follows:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Uid:\t\tMyEdge\n",
      "Type:\t\tEdge\n",
      "Directed:\tFalse\n",
      "Nodes:\t\t|'a', 'b'|\n",
      "\n"
     ]
    }
   ],
   "source": [
    "edge = pp.Edge(v=n.nodes['a'], w=n.nodes['b'], uid='MyEdge', directed=False)\n",
    "print(edge)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This `Edge` object has a different UID than the existing edge betwee node `a` and `b`, which is why we can add it to (multi-edge) network `n` even though this network already contains an edge (with a different UID) between nodes `a` and `b`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Uid:\t\t\tExampleNetwork\n",
      "Type:\t\t\tNetwork\n",
      "Directed:\t\tFalse\n",
      "Multi-Edges:\t\tTrue\n",
      "Number of nodes:\t4\n",
      "Number of edges:\t5\n"
     ]
    }
   ],
   "source": [
    "n.add_edge(edge)\n",
    "print(n)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The summary of the network confirms that the network now contains five edges (between four pairs of nodes). This native support for multi-edge networks that can include both directed and undirected edges is an important feature of `pathpy`. It also means that every pair of nodes can be connected by more than one edge. We can access those edges via the `Network.edges` container in multiple ways. First, we can simply iterate through the edge objects as shown before. Second, we can directly access an `Edge` with a given UID as follows:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Uid:\t\tMyEdge\n",
      "Type:\t\tEdge\n",
      "Directed:\tFalse\n",
      "Nodes:\t\t|'a', 'b'|\n",
      "\n"
     ]
    }
   ],
   "source": [
    "print(n.edges['MyEdge'])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Finally, we often want to access those edges that connect a specific pair of nodes. We can thus alternatively pass a pair of node uids as index to `Network.edges`. Since multiple edges between the same pair of nodes are possible, this generally returns a list of Edge objects, which - in the case of the node pair `a` and `b` - contains two different edge objects with different UIDs."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{Edge |'a', 'b'|, Edge MyEdge}\n"
     ]
    }
   ],
   "source": [
    "print(n.edges['a', 'b'])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can access the degrees of nodes, i.e. the number of other nodes to which a node is connected, via the `degrees()` function of the Network. The degrees() function gives the undirected degree (i.e. irrespective of the directionality of an edge), while the `indegrees()` and `outdegrees()` functions give the degrees in a directed network (i.e. to how many other nodes the edges of a node point of from how many other nodes edges point to the given node).\n",
    "\n",
    "All of those functions return a dictionary that can be indexed via the unique node ids. In the case of a multi-edge network, the degree counts multiple edges to the same neighbor, which is why the degree of node `a` in the network above is 3:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "3"
      ]
     },
     "execution_count": 21,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "n.degrees()['a']"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can also remove nodes or edges. A network can contain isolated nodes (i.e. nodes with no incident edges), while it can (obviously) only contain edges between nodes that exist in the network. \n",
    "\n",
    "To ensure this constraint, a call to `remove_node` will also remove all edges that are incident to the removed node, i.e. if we remove node `a` the `Edge` object with uid `MyEdge` will be removed from the network (along with two additional edges (a,b) and (a,d)):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "False\n",
      "Uid:\t\t\tExampleNetwork\n",
      "Type:\t\t\tNetwork\n",
      "Directed:\t\tFalse\n",
      "Multi-Edges:\t\tTrue\n",
      "Number of nodes:\t3\n",
      "Number of edges:\t2\n"
     ]
    }
   ],
   "source": [
    "n.remove_node('a')\n",
    "print('MyEdge' in n.edges.uids)\n",
    "print(n)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A call to `remove_edge` on the other hand does not remove the nodes incident to the removed edge, thus possibly leaving isolated nodes. If we remove the edge from `b` to `c` this will leave an isolated node `b`, which is still in the network:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 23,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "True\n",
      "Uid:\t\tb\n",
      "Type:\t\tNode\n",
      "\n",
      "Uid:\t\t\tExampleNetwork\n",
      "Type:\t\t\tNetwork\n",
      "Directed:\t\tFalse\n",
      "Multi-Edges:\t\tTrue\n",
      "Number of nodes:\t3\n",
      "Number of edges:\t1\n"
     ]
    }
   ],
   "source": [
    "n.remove_edge('b', 'c')\n",
    "print('b' in n.nodes.uids)\n",
    "print(n.nodes['b'])\n",
    "print(n)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note that we can either remove a specific edge between a pair of nodes or all edges between a pair of nodes. To better understand this, let us create three different edges between two nodes 'x' and 'y' and add them to a network. To simplify the construction of networks, we can use the functions `add_nodes` and `add_edges` which add multiple nodes and edges at a time:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 112,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Uid:\t\t\t0x7fb9f81654f0\n",
      "Type:\t\t\tNetwork\n",
      "Directed:\t\tTrue\n",
      "Multi-Edges:\t\tTrue\n",
      "Number of nodes:\t2\n",
      "Number of edges:\t3\n"
     ]
    }
   ],
   "source": [
    "n3 = pp.Network(multiedges=True)\n",
    "n3.add_nodes('x', 'y')\n",
    "e1 = pp.Edge(n3.nodes['x'], n3.nodes['y'], uid='edge1')\n",
    "e2 = pp.Edge(n3.nodes['x'], n3.nodes['y'], uid='edge2')\n",
    "e3 = pp.Edge(n3.nodes['x'], n3.nodes['y'], uid='edge3')\n",
    "n3.add_edges(e1, e2, e3)\n",
    "print(n3)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If we only remove the single edge with uid `edge2` between `x` and `y`, we can call:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 113,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{Edge edge1, Edge edge3}\n"
     ]
    }
   ],
   "source": [
    "n3.remove_edge('edge2')\n",
    "print(n3.edges['x', 'y'])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "At the same time, we can remove all edges between `x` and `y` by calling:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 114,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "set()\n"
     ]
    }
   ],
   "source": [
    "n3.remove_edge('x', 'y')\n",
    "print(n3.edges['x', 'y'])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Networks, Nodes and Edges with attributes\n",
    "\n",
    "You may wonder why `pathpy` stores nodes and edges as objects rather than as simple strings or numbers. The reason is that we often want to use networks to model relational data that contain additional information on nodes, edges, or networks. To support this, all `pathpy` objects can store arbitrary key-value data in the form of attributes. Let's explore this in a toy example for a social network:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 24,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Uid:\t\t\tTrolls\n",
      "Type:\t\t\tNetwork\n",
      "Directed:\t\tTrue\n",
      "Multi-Edges:\t\tFalse\n",
      "Number of nodes:\t3\n",
      "Number of edges:\t2\n"
     ]
    }
   ],
   "source": [
    "trolls = pp.Network(uid='Trolls')\n",
    "trolls.add_node('t')\n",
    "trolls.add_node('b')\n",
    "trolls.add_node('w')\n",
    "trolls.add_edge('t', 'b', uid='t-b')\n",
    "trolls.add_edge('t', 'w', uid='t-w')\n",
    "print(trolls)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": []
  },
  {
   "cell_type": "code",
   "execution_count": 25,
   "metadata": {},
   "outputs": [],
   "source": [
    "trolls.nodes['t']['name'] = 'Tom'\n",
    "trolls.nodes['t']['age'] = 156\n",
    "\n",
    "trolls.nodes['b']['name'] = 'Bert'\n",
    "trolls.nodes['b']['age'] = 96\n",
    "\n",
    "trolls.nodes['w']['name'] = 'William'\n",
    "trolls.nodes['w']['age'] = 323"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Just like nodes, `Edge` objects can store arbitrary attributes that we can read and write via the `edges` dictionary in the `Network` class. We can store attributes as follows:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 26,
   "metadata": {},
   "outputs": [],
   "source": [
    "trolls.edges['t-b']['strength'] = 2.0\n",
    "trolls.edges['t-b']['type'] = 'like'\n",
    "\n",
    "trolls.edges['t-w']['strength'] = 5.0\n",
    "trolls.edges['t-w']['type'] = 'dislike'"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 27,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{'strength': 2.0, 'type': 'like'}\n",
      "{'strength': 5.0, 'type': 'dislike'}\n"
     ]
    }
   ],
   "source": [
    "print(trolls.edges['t-b'].attributes)\n",
    "print(trolls.edges['t-w'].attributes)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Numerical properties of edges are often used to store the strength or weight of interactions in a system. Such numerical properties can also be considered in the degree calculation. Above, we have a directed network, so we can use the `indegrees()` and `outdegrees()` function to access the directed degrees of nodes. In our example, Tom has an outdegree of two since there are two directed edges to Bert and William:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 28,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "2"
      ]
     },
     "execution_count": 28,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "trolls.outdegrees()['t']"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 29,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "0"
      ]
     },
     "execution_count": 29,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "trolls.outdegrees()['b']"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To additionally consider numerical attributes in the degree calculation, we can use the weight parameter of the degrees(), indegrees() or outdegrees() functions. To calculate the total strength of all outgoing edges from Tom we can write:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 30,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "7.0"
      ]
     },
     "execution_count": 30,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "trolls.outdegrees(weight='strength')['t']"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Finally, we can also store attributes at the network-level:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 31,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{'chapter': 'Roast Mutton'}\n"
     ]
    }
   ],
   "source": [
    "trolls['chapter'] = 'Roast Mutton'\n",
    "print(trolls.attributes)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Apart from using the attribute dictionary, we can directly assign attributes when we create nodes, edges, or networks. Simply pass key/value parameters to the constructor of the corresponding objects or to the `add_node` and `add_edge` functions. An equivalent way to create the network above would thus be:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 32,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "---\n",
      "Network attributes\n",
      "{'name': 'Trolls', 'chapter': 'Roast Mutton'}\n",
      "---\n",
      "Node attributes\n",
      "Uid:\t\tt\n",
      "Type:\t\tNode\n",
      " {'name': 'Tom', 'age': 156}\n",
      "Uid:\t\tb\n",
      "Type:\t\tNode\n",
      " {'name': 'Bert', 'age': 96}\n",
      "Uid:\t\tw\n",
      "Type:\t\tNode\n",
      " {'name': 'William', 'age': 323}\n",
      "---\n",
      "Edge attributes\n",
      "Uid:\t\t0x7fd95080c610\n",
      "Type:\t\tEdge\n",
      "Directed:\tTrue\n",
      "Nodes:\t\t('t', 'b')\n",
      " {'type': 'like', 'strength': 2.0, 'uid': None}\n",
      "Uid:\t\t0x7fd95080cbe0\n",
      "Type:\t\tEdge\n",
      "Directed:\tTrue\n",
      "Nodes:\t\t('t', 'w')\n",
      " {'type': 'dislike', 'strength': 5.0, 'uid': None}\n"
     ]
    }
   ],
   "source": [
    "trolls = pp.Network(multiedges=True,name='Trolls', chapter='Roast Mutton')\n",
    "tom = pp.Node(uid='t', name='Tom', age=156)\n",
    "bert = pp.Node(uid='b', name='Bert', age=96)\n",
    "william = pp.Node(uid='w', name='William', age=323)\n",
    "e1 = pp.Edge(tom, bert, type='like', strength=2.0)\n",
    "e2 = pp.Edge(tom, william, type='dislike', strength=5.0)\n",
    "trolls.add_edge(e1)\n",
    "trolls.add_edge(e2)\n",
    "print('---\\nNetwork attributes')\n",
    "print(trolls.attributes)\n",
    "print('---\\nNode attributes')\n",
    "for v in trolls.nodes:\n",
    "    print(v, v.attributes)\n",
    "print('---\\nEdge attributes')\n",
    "for e in trolls.edges:\n",
    "    print(e, e.attributes)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Adjacency matrices\n",
    "\n",
    "Adjacency matrices are an important mathematical representation of graphs and networks. The topology of a graph can be represented in the entries of a matrix $A$, where an entry $A[i,j]=1$ indicates that an edge exists from the i-th to the j-th node of the network. The absence of edges is encoded by zero entries. The size of an adjacency matrix representation of a network with n nodes is generally $n^2$, which is not suitable for networks with thousands or millions of nodes. `pathpy` nevertheless supports efficient adjacency matrix calculation for *sparse* networks, i.e. networks where the majority of node pairs are not connected by an edge. Instead of a fully populated matrix, a call to `Network.adjacency_matrix()` returns a *sparse matrix object*, which is essentially an efficient adjacency-list representation capturing the indices and values of non-zero entries:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 33,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "  (0, 1)\t1.0\n",
      "  (0, 2)\t1.0\n"
     ]
    }
   ],
   "source": [
    "print(trolls.adjacency_matrix())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`pathpy` internally uses the `csr_matrix` class from the sparse linear algebra module that is contained in `scipy`. This enables us to directly apply matrix algebra operations to sparse matrices. If we instead want a dense matrix that includes zero entries, we can write:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 34,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[[0. 1. 1.]\n",
      " [0. 0. 0.]\n",
      " [0. 0. 0.]]\n"
     ]
    }
   ],
   "source": [
    "print(trolls.adjacency_matrix().todense())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The adjacency matrix entries above shows that two edges from Tom to Bert and from Tom to William exist. Moreover, the fact that the matrix is assymetric tells us that this is a directed network. By default, a binary matrix representation is returned where entries store the presence or absence of edges as 0 or 1 entries. If we want to use numerical attributes of edges instead, we can again pass the name of a numerical attribute that should be used as edge `weight`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 35,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[[0. 2. 5.]\n",
      " [0. 0. 0.]\n",
      " [0. 0. 0.]]\n"
     ]
    }
   ],
   "source": [
    "print(trolls.adjacency_matrix(weight='strength').todense())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "How does `pathpy` populate adjaecency matrices if the network contains multiple edges between the same pair of nodes? Let's try this by creating another edge between Tom and Bert, and let's further add a strength attribute:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 36,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Uid:\t\t\t0x7fd95083fb50\n",
      "Type:\t\t\tNetwork\n",
      "Directed:\t\tTrue\n",
      "Multi-Edges:\t\tTrue\n",
      "Number of nodes:\t3\n",
      "Number of edges:\t3\n",
      "\n",
      "Network attributes\n",
      "------------------\n",
      "name:\tTrolls\n",
      "chapter:\tRoast Mutton\n",
      "\n"
     ]
    }
   ],
   "source": [
    "e3 = pp.Edge(tom, bert, type='sibling', strength=42.0)\n",
    "trolls.add_edge(e3)\n",
    "print(trolls)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If we now generate an adjacency matrix, the entries contain the *number of different edge objects* between pairs of nodes:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 37,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "matrix([[0., 2., 1.],\n",
       "        [0., 0., 0.],\n",
       "        [0., 0., 0.]])"
      ]
     },
     "execution_count": 37,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "trolls.adjacency_matrix().todense()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If we use a numerical attribute to calculate the matrix entries in such a network, the attributes of all edges between the same pair of nodes is automatically summed:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 136,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "matrix([[ 0., 44.,  5.],\n",
       "        [ 0.,  0.,  0.],\n",
       "        [ 0.,  0.,  0.]])"
      ]
     },
     "execution_count": 136,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "trolls.adjacency_matrix(weight='strength').todense()"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3.7.3 ('base')",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.7.3"
  },
  "vscode": {
   "interpreter": {
    "hash": "7636f2d114212ae27b52622e6b89e09cf504cf8142b2110d22f6f70e26cfddd4"
   }
  }
 },
 "nbformat": 4,
 "nbformat_minor": 1
}