{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Pyntacle\n",
    "\n",
    "This Jupyter notebook provides an example of using the Python packages [gravis](https://pypi.org/project/gravis) and [Pyntacle](http://pyntacle.css-mendel.it). The .ipynb file can be found [here](https://github.com/robert-haas/gravis/tree/master/examples).\n",
    "\n",
    "## References\n",
    "\n",
    "- [Pyntacle website](http://pyntacle.css-mendel.it)\n",
    "  - [Tutorials](http://pyntacle.css-mendel.it/#tutorials) (Case studies)\n",
    "  - [Documentation](http://pyntacle.css-mendel.it/#docs)\n",
    "\n",
    "Note: Pyntacle builds on top of **igraph**. It uses igraph Graph objects and the usual igraph methods are available for them."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Installation\n",
    "\n",
    "- With [pip](https://pypi.org/project/pyntacle/): `pip install pyntacle`\n",
    "- With [conda](https://anaconda.org/search?q=pyntacle): `conda install -c conda-forge -c bfxcss pyntacle`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Import"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import os\n",
    "import warnings\n",
    "warnings.simplefilter('ignore')  # ignore various CUDA warnings"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import igraph  # for graph generation\n",
    "import pyntacle\n",
    "import pyntacle.algorithms.local_topology\n",
    "import pyntacle.algorithms.global_topology\n",
    "import pyntacle.io_stream.generator\n",
    "import pyntacle.io_stream.importer\n",
    "\n",
    "import gravis as gv"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Quick start\n",
    "\n",
    "### Example 1"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def assign_properties(g):\n",
    "    # Pyntacle builds on top of igraph. The following calculations are provided by igraph!\n",
    "\n",
    "    # Centrality calculation\n",
    "    node_centralities = g.betweenness()\n",
    "    edge_centralities = g.edge_betweenness()\n",
    "    \n",
    "    # Community detection\n",
    "    communities = g.community_fastgreedy().as_clustering().membership\n",
    "\n",
    "    # Node properties: Size by centrality, color by community\n",
    "    colors = ['red', 'blue', 'green', 'orange', 'pink', 'brown', 'yellow', 'cyan', 'magenta', 'violet']\n",
    "    g.vs['size'] = [5.0 + val / 10.0 for val in node_centralities]\n",
    "    g.vs['color'] = [colors[community_index % len(colors)] for community_index in communities]\n",
    "    \n",
    "    # Edge properties: Size by centrality, color by community (within=community color, between=black)\n",
    "    g.es['size'] = [0.5 + val / 50.0 for val in edge_centralities]\n",
    "    g.es['color'] = [colors[communities[i] % len(colors)] if communities[i] == communities[j] else 'black'\n",
    "                     for i, j in g.get_edgelist()]\n",
    "    \n",
    "\n",
    "# Create a graph\n",
    "filepath = os.path.join('data', 'pyntacle_graph.adjm')\n",
    "g = pyntacle.io_stream.importer.PyntacleImporter.AdjacencyMatrix(\n",
    "    file=filepath, header = True, sep = \"\\t\")\n",
    "\n",
    "# Assign properties\n",
    "assign_properties(g)\n",
    "\n",
    "# Plot it\n",
    "gv.d3(g, zoom_factor=0.2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Graph construction\n",
    "\n",
    "- API reference: [pyntacle.io_stream](http://pyntacle.css-mendel.it/html/pyntacle.io_stream.html#)\n",
    "\n",
    "### 1) Manual graph construction"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# ~ Not supported by Pyntacle, possible via igraph ~"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 2) Algorithmic graph construction\n",
    "\n",
    "- API Reference: [pyntacle.io_stream.generator](http://pyntacle.css-mendel.it/html/pyntacle.io_stream.generator.html#module-pyntacle.io_stream.generator)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "generator = pyntacle.io_stream.generator.PyntacleGenerator\n",
    "num_nodes = 50\n",
    "\n",
    "\n",
    "# Erdos-Renyi model - arg1: number of nodes, arg2: number of edges (or rewiring probability)\n",
    "g = generator.Random([num_nodes, 80])\n",
    "\n",
    "# Barabasi-Albert model - arg1: number of nodes, arg2: average number of edges per node\n",
    "g = generator.ScaleFree([num_nodes, 2])\n",
    "\n",
    "# Watts-Strogatz model - arg1: dimension of the lattice, arg2: size of the lattice among all dimensions\n",
    "#                        arg3: distance k between nodes, arg4: node rewiring probability p\n",
    "g = generator.SmallWorld([2, 10, 1, 0.1])\n",
    "\n",
    "# Tree topology as in Wolfram alpha docs - arg1: number of nodes, arg2: number of children per node\n",
    "g = generator.Tree([num_nodes, 3])\n",
    "\n",
    "\n",
    "gv.d3(g)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 3) Graph loading from an internal collection"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# ~ Not supported by Pyntacle, possible via igraph ~"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 4) Graph import and export\n",
    "\n",
    "- API reference: [pyntacle.io_stream](http://pyntacle.css-mendel.it/html/pyntacle.io_stream.html)\n",
    "\n",
    "#### Import\n",
    "\n",
    "- API reference: [pyntacle.io_stream.importer](http://pyntacle.css-mendel.it/html/pyntacle.io_stream.importer.html#module-pyntacle.io_stream.importer)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "importer = pyntacle.io_stream.importer.PyntacleImporter\n",
    "\n",
    "filepath = os.path.join('data', 'pyntacle_graph.adjm')\n",
    "g = importer.AdjacencyMatrix(file=filepath, header=True, sep='\\t')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Export\n",
    "\n",
    "- API reference: [pyntacle.io_stream.exporter](http://pyntacle.css-mendel.it/html/pyntacle.io_stream.exporter.html#module-pyntacle.io_stream.exporter)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# TODO"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Basic graph inspection\n",
    "\n",
    "### 1) Graph and its properties"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(type(g))  # pyntacle uses igraph as basis"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 2) Nodes and their properties"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# TODO"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 3) Edges and their properties"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# TODO"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Calculating graph measures and metrics\n",
    "\n",
    "### 1) Quantitative measures\n",
    "\n",
    "- API reference: [pyntacle.algorithms](http://pyntacle.css-mendel.it/html/pyntacle.algorithms.html)\n",
    "\n",
    "#### 1.a) Graph properties\n",
    "\n",
    "- API reference: [Global topology](http://pyntacle.css-mendel.it/html/pyntacle.algorithms.global_topology.html#module-pyntacle.algorithms.global_topology)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "gt = pyntacle.algorithms.global_topology.GlobalTopology\n",
    "\n",
    "value = gt.average_closeness(g)\n",
    "value = gt.average_clustering_coefficient(g)\n",
    "value = gt.average_degree(g)\n",
    "value = gt.average_eccentricity(g)\n",
    "value = gt.average_radiality(g)\n",
    "value = gt.average_radiality_reach(g)\n",
    "value = gt.components(g)\n",
    "value = gt.density(g)\n",
    "value = gt.diameter(g)\n",
    "value = gt.pi(g)\n",
    "value = gt.radius(g)\n",
    "value = gt.weighted_clustering_coefficient(g)        "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### 1.b) Node properties\n",
    "\n",
    "- API reference: [Local topology](http://pyntacle.css-mendel.it/html/pyntacle.algorithms.local_topology.html#module-pyntacle.algorithms.local_topology)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "lt = pyntacle.algorithms.local_topology.LocalTopology\n",
    "\n",
    "values = lt.betweenness(g)\n",
    "values = lt.closeness(g)\n",
    "values = lt.clustering_coefficient(g)\n",
    "values = lt.degree(g)\n",
    "values = lt.eccentricity(g)\n",
    "# values = lt.eigenvector_centrality(g)  # fails\n",
    "values = lt.pagerank(g)\n",
    "values = lt.radiality(g)\n",
    "values = lt.radiality_reach(g)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### 1.c) Group properties\n",
    "\n",
    "- API reference: [Local topology](http://pyntacle.css-mendel.it/html/pyntacle.algorithms.local_topology.html#module-pyntacle.algorithms.local_topology)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "node_names = g.vs['name']\n",
    "used_node_names = node_names[:5]\n",
    "\n",
    "value = lt.group_betweenness(g, used_node_names)\n",
    "value = lt.group_closeness(g, used_node_names)\n",
    "value = lt.group_degree(g, used_node_names)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 2) Structure inference"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# TODO"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Graph visualization"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# TODO"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "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.12"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}