tutorials/Tutorial 3 - Basic simplicial complex usage.ipynb

{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2022-04-15T12:40:43.984956Z",
     "start_time": "2022-04-15T12:40:43.404780Z"
    }
   },
   "outputs": [],
   "source": [
    "import xgi\n",
    "import random\n",
    "import pandas as pd\n",
    "import numpy as np"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2022-04-14T16:15:19.273272Z",
     "start_time": "2022-04-14T16:15:19.268293Z"
    }
   },
   "source": [
    "# Creating a Simplicial Complex \n",
    "\n",
    "Simplicial complexes can be created directly using the ``SimplicialComplex`` class. \n",
    "It inherits a number of properties from the ``Hypergraph`` one, but it has also some significant differences due to the closure property required for valid simplicial complexes. \n",
    "\n",
    "Let us illustrate these differences by comparing directly the construction of a simplicial complex and of a hypergraph containing the same hyperedges/simplices. \n",
    "We begin by creating a simplicial complex ``SC`` and a hypergraph ``H``. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2022-04-15T12:40:43.993935Z",
     "start_time": "2022-04-15T12:40:43.991496Z"
    }
   },
   "outputs": [],
   "source": [
    "SC = xgi.SimplicialComplex()\n",
    "H = xgi.Hypergraph()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We add to both of them 5 nodes"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2022-04-15T12:40:44.000054Z",
     "start_time": "2022-04-15T12:40:43.997820Z"
    }
   },
   "outputs": [],
   "source": [
    "SC.add_nodes_from(range(5))\n",
    "H.add_nodes_from(range(5))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2022-04-15T12:40:44.011249Z",
     "start_time": "2022-04-15T12:40:44.001746Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(NodeView((0, 1, 2, 3, 4)), NodeView((0, 1, 2, 3, 4)))"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "SC.nodes, H.nodes"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We then add the simplex ``[0,1,2]`` to the simplicial complex and the same (as hyperedge) to the hypergraph "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2022-04-15T12:40:44.016572Z",
     "start_time": "2022-04-15T12:40:44.014272Z"
    }
   },
   "outputs": [],
   "source": [
    "SC.add_simplex([0, 1, 2])\n",
    "H.add_edge([0, 1, 2])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2022-04-14T16:22:15.923541Z",
     "start_time": "2022-04-14T16:22:15.919405Z"
    }
   },
   "source": [
    "Note that if we try to use ``add_edge`` on the simplicial complex, it will not work. \n",
    "This is done in order to prevent the misuse of hyperedge addition that would not protect the closure property of simplicial complexes. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2022-04-15T12:40:44.021142Z",
     "start_time": "2022-04-15T12:40:44.019203Z"
    }
   },
   "outputs": [],
   "source": [
    "# SC.add_edge([0,1,2])      # try uncommenting and executing this cell"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now, what is this closure property we have mentioned? \n",
    "\n",
    "By definition, a simplicial complex $K$ is valid if for any simplex $\\sigma \\in K$, all faces $\\omega \\subset \\sigma$ are also $\\omega \\in K$. This implies that we must make sure that each face is properly added whenever we add a new simplex. \n",
    "The function ``SC.add_simplex`` and ``SC.add_simplices_from`` already take care of this directly. This does not happen instead when adding hyperedges to hypergraphs. \n",
    "\n",
    "We can check this easily by asking how many edges are present in the simplicial complex versus the hypergraph.\n",
    "Previously, we only added the simplex/hyperedge ``[0,1,2,3]``. The closure requires also the addition of the three edges (``[0,1], [0,2], [1,2]``), so there should be 4 simplices in `SC` and only one in `H`. \n",
    "Correctly, we find:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2022-04-15T12:40:44.025130Z",
     "start_time": "2022-04-15T12:40:44.022692Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "EdgeView((0, 1, 2, 3))"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "SC.edges"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2022-04-15T12:40:44.029171Z",
     "start_time": "2022-04-15T12:40:44.026551Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "EdgeView((0,))"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "H.edges"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can further check that this is correct by checking how many hyperedges of a certain dimension (\"order\") are present in the simplicial complex.\n",
    "We can do this using the ``order`` key as follows:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2022-04-15T12:40:44.036071Z",
     "start_time": "2022-04-15T12:40:44.030756Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "# edges in H at order 0 []\n",
      "# edges in SC at order 0 [] \n",
      "\n",
      "# edges in H at order 1 []\n",
      "# edges in SC at order 1 [1, 2, 3] \n",
      "\n",
      "# edges in H at order 2 [0]\n",
      "# edges in SC at order 2 [0] \n",
      "\n"
     ]
    }
   ],
   "source": [
    "for dim in [0, 1, 2]:\n",
    "    print(\"# edges in H at order\", dim, H.edges.filterby(\"order\", dim))\n",
    "    print(\"# edges in SC at order\", dim, SC.edges.filterby(\"order\", dim), \"\\n\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Finally, we can directly access the simplex composition by using the ``members`` function of ``edges``. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2022-04-15T12:40:44.041598Z",
     "start_time": "2022-04-15T12:40:44.038182Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Composition of simplices at order 0 [] \n",
      "\n",
      "Composition of simplices at order 1 [frozenset({0, 1}), frozenset({0, 2}), frozenset({1, 2})] \n",
      "\n",
      "Composition of simplices at order 2 [frozenset({0, 1, 2})] \n",
      "\n"
     ]
    }
   ],
   "source": [
    "for dim in [0, 1, 2]:\n",
    "    edge_sel = list(SC.edges.filterby(\"order\", dim))\n",
    "    print(\n",
    "        \"Composition of simplices at order\",\n",
    "        dim,\n",
    "        [SC.edges.members(x) for x in edge_sel],\n",
    "        \"\\n\",\n",
    "    )"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As opposed to what happens in the corresponding hypergraph"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2022-04-15T12:40:44.063857Z",
     "start_time": "2022-04-15T12:40:44.043104Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Composition of edges at order 0 [] \n",
      "\n",
      "Composition of edges at order 1 [] \n",
      "\n",
      "Composition of edges at order 2 [[0, 1, 2]] \n",
      "\n"
     ]
    }
   ],
   "source": [
    "for dim in [0, 1, 2]:\n",
    "    edge_sel = list(H.edges.filterby(\"order\", dim))\n",
    "    print(\n",
    "        \"Composition of edges at order\",\n",
    "        dim,\n",
    "        [H.edges.members(x) for x in edge_sel],\n",
    "        \"\\n\",\n",
    "    )"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Loading from a list of facets"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can also provide the ``SimplicialComplex`` class with a list of facets --maximal faces, that is, simplices that are not contained in any other simplices--. \n",
    "Note that if the list contains a simplex that it's not a facet, this will not throw an error but the simplex will simply become part of the closure of a larger one in the list. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2022-04-15T12:40:44.086542Z",
     "start_time": "2022-04-15T12:40:44.065901Z"
    }
   },
   "outputs": [],
   "source": [
    "facets = [[0, 1, 2], [0, 1, 3, 4]]\n",
    "SC1 = xgi.SimplicialComplex(facets)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2022-04-15T12:40:44.094584Z",
     "start_time": "2022-04-15T12:40:44.089313Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[frozenset({0, 1, 2}),\n",
       " frozenset({0, 1}),\n",
       " frozenset({0, 2}),\n",
       " frozenset({1, 2}),\n",
       " frozenset({0, 1, 3, 4}),\n",
       " frozenset({0, 1, 3}),\n",
       " frozenset({0, 3}),\n",
       " frozenset({1, 3}),\n",
       " frozenset({0, 1, 4}),\n",
       " frozenset({0, 4}),\n",
       " frozenset({1, 4}),\n",
       " frozenset({0, 3, 4}),\n",
       " frozenset({3, 4}),\n",
       " frozenset({1, 3, 4})]"
      ]
     },
     "execution_count": 13,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "SC1.edges.members()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2022-04-15T12:40:44.170851Z",
     "start_time": "2022-04-15T12:40:44.096913Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'Unnamed SimplicialComplex with 20 nodes and 156 simplices'"
      ]
     },
     "execution_count": 14,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "n = 20\n",
    "m = 40\n",
    "\n",
    "min_edge_size = 2\n",
    "max_edge_size = 4\n",
    "\n",
    "hyperedge_list = [\n",
    "    random.sample(range(n), random.choice(range(min_edge_size, max_edge_size + 1)))\n",
    "    for i in range(m)\n",
    "]\n",
    "SC_big = xgi.SimplicialComplex(hyperedge_list)\n",
    "str(SC_big)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2022-04-15T12:12:17.040756Z",
     "start_time": "2022-04-15T12:12:17.038265Z"
    }
   },
   "source": [
    "## Loading from a pandas DataFrame"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2022-04-15T12:40:44.197072Z",
     "start_time": "2022-04-15T12:40:44.172454Z"
    }
   },
   "outputs": [],
   "source": [
    "df = xgi.to_bipartite_pandas_dataframe(xgi.load_xgi_data(\"email-enron\"))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2022-04-15T12:11:12.037242Z",
     "start_time": "2022-04-15T12:11:12.035733Z"
    }
   },
   "source": [
    "When a user gives a Pandas dataframe, the system automatically imports the first two columns as lists of node and edge indices specifying a bipartite edge list. \n",
    "Below we compare the results of importing the dataframe as a hypergraph, in which all edges are retained just as they are in the dataframe, and as a simplicial complex, in which we cannot have repeated simplices. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2022-04-15T12:40:44.205858Z",
     "start_time": "2022-04-15T12:40:44.199053Z"
    },
    "scrolled": false
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "('Unnamed Hypergraph with 21 nodes and 182 hyperedges',\n",
       " [[1, 10, 12, 17, 25],\n",
       "  [1, 10, 12, 19, 23, 26],\n",
       "  [2, 12, 19, 20],\n",
       "  [2, 28],\n",
       "  [2, 10],\n",
       "  [2, 15, 18],\n",
       "  [2, 15, 19],\n",
       "  [2, 24],\n",
       "  [2],\n",
       "  [2],\n",
       "  [2, 12, 13, 18],\n",
       "  [2, 10, 12, 19],\n",
       "  [2, 14, 15, 19, 24, 25],\n",
       "  [2, 12, 19, 24],\n",
       "  [2, 19],\n",
       "  [2, 23],\n",
       "  [2, 12, 21],\n",
       "  [2],\n",
       "  [2],\n",
       "  [2],\n",
       "  [2, 17],\n",
       "  [2],\n",
       "  [2],\n",
       "  [2, 19, 27],\n",
       "  [2],\n",
       "  [2],\n",
       "  [2],\n",
       "  [9, 10],\n",
       "  [9, 10, 19, 28],\n",
       "  [9, 10, 26]])"
      ]
     },
     "execution_count": 16,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "H = xgi.Hypergraph(df[:300])\n",
    "str(H), H.edges.members()[:30]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2022-04-15T12:40:57.246712Z",
     "start_time": "2022-04-15T12:40:53.757479Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "The hypergraph has 21 nodes and 415 edges\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "[frozenset({1, 10, 12, 17, 25}),\n",
       " frozenset({1, 10, 12, 17}),\n",
       " frozenset({1, 10, 12}),\n",
       " frozenset({1, 10}),\n",
       " frozenset({1, 12}),\n",
       " frozenset({10, 12}),\n",
       " frozenset({1, 10, 17}),\n",
       " frozenset({1, 17}),\n",
       " frozenset({10, 17}),\n",
       " frozenset({1, 12, 17}),\n",
       " frozenset({12, 17}),\n",
       " frozenset({10, 12, 17}),\n",
       " frozenset({1, 10, 12, 25}),\n",
       " frozenset({1, 10, 25}),\n",
       " frozenset({1, 25}),\n",
       " frozenset({10, 25}),\n",
       " frozenset({1, 12, 25}),\n",
       " frozenset({12, 25}),\n",
       " frozenset({10, 12, 25}),\n",
       " frozenset({1, 10, 17, 25}),\n",
       " frozenset({1, 17, 25}),\n",
       " frozenset({17, 25}),\n",
       " frozenset({10, 17, 25}),\n",
       " frozenset({1, 12, 17, 25}),\n",
       " frozenset({12, 17, 25}),\n",
       " frozenset({10, 12, 17, 25}),\n",
       " frozenset({1, 10, 12, 19, 23, 26}),\n",
       " frozenset({1, 10, 12, 19, 23}),\n",
       " frozenset({1, 10, 12, 19}),\n",
       " frozenset({1, 10, 19})]"
      ]
     },
     "execution_count": 20,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "F = xgi.SimplicialComplex(df[:300])\n",
    "print(f\"The hypergraph has {F.num_nodes} nodes and {F.num_edges} edges\")\n",
    "F.edges.members()[:30]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In many cases we start from a list of facets that can include very large simplices. \n",
    "This however can become quickly very cumbersome because the number of subfaces scales factorially with the order of the facet. \n",
    "Moreover, even when we have large facets, we might be interested in quantities that are defined only on simplices of smaller dimension. \n",
    "One way to approach this is by reducing the maximum size of the simplices that are added to the``SimplicialComplex`` constructor. Alternatively, it is possible to provide to the ``add_simplices_from`` function a maximum order. In that case, any simplex with order larger than ``max_order`` will be substituted with its faces of order ``max_order`` (the closure property is automatically enforced by the function). \n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2022-04-15T12:40:57.332409Z",
     "start_time": "2022-04-15T12:40:57.249163Z"
    },
    "scrolled": false
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'Unnamed SimplicialComplex with 20 nodes and 156 simplices'"
      ]
     },
     "execution_count": 21,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "X = xgi.SimplicialComplex()\n",
    "X.add_simplices_from(hyperedge_list, max_order=4)\n",
    "str(X)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "and we can also check that this is the case explicitly closing the simplicial complex and checking that the size does not change. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2022-04-15T12:40:57.402192Z",
     "start_time": "2022-04-15T12:40:57.334830Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'Unnamed SimplicialComplex with 20 nodes and 156 simplices'"
      ]
     },
     "execution_count": 22,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "X.close()\n",
    "str(X)"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "hyper",
   "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.10.6 | packaged by conda-forge | (main, Aug 22 2022, 20:38:29) [Clang 13.0.1 ]"
  },
  "toc": {
   "base_numbering": 1,
   "nav_menu": {},
   "number_sections": true,
   "sideBar": true,
   "skip_h1_title": false,
   "title_cell": "Table of Contents",
   "title_sidebar": "Contents",
   "toc_cell": false,
   "toc_position": {},
   "toc_section_display": true,
   "toc_window_display": false
  },
  "vscode": {
   "interpreter": {
    "hash": "d499419bfd3ffc3e3fdefe0b9d84e10a93ca5c11fd9f2ad00edb8d726bc70f5f"
   }
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}