cartoGRAPHs__QuickstartNotebook.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "positive-supervision",
   "metadata": {},
   "source": [
    "-----\n",
    "# cartoGRAPHs | Quickstarter notebook\n",
    "- A Notebook to produce 2D and 3D network layouts from any Graph,\n",
    "including interactive visualization (html files) and export functions \n",
    "to import into the VRNetzer analytics platform by Pirch et al.\n",
    "-----"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "95b121ec",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Collecting cartoGRAPHs==2.0.1\n",
      "  Downloading cartoGRAPHs-2.0.1-py3-none-any.whl (27 kB)\n",
      "Collecting pynndescent==0.5.8\n",
      "  Using cached pynndescent-0.5.8-py3-none-any.whl\n",
      "Requirement already satisfied: matplotlib in /Users/chris/opt/anaconda3/envs/myenv/lib/python3.8/site-packages (from cartoGRAPHs==2.0.1) (3.5.1)\n",
      "Requirement already satisfied: plotly in /Users/chris/opt/anaconda3/envs/myenv/lib/python3.8/site-packages (from cartoGRAPHs==2.0.1) (5.5.0)\n",
      "Requirement already satisfied: shapely in /Users/chris/opt/anaconda3/envs/myenv/lib/python3.8/site-packages (from cartoGRAPHs==2.0.1) (2.0.3)\n",
      "Requirement already satisfied: pandas in /Users/chris/opt/anaconda3/envs/myenv/lib/python3.8/site-packages (from cartoGRAPHs==2.0.1) (2.0.3)\n",
      "Requirement already satisfied: colormath in /Users/chris/opt/anaconda3/envs/myenv/lib/python3.8/site-packages (from cartoGRAPHs==2.0.1) (3.0.0)\n",
      "Requirement already satisfied: scikit-learn in /Users/chris/opt/anaconda3/envs/myenv/lib/python3.8/site-packages (from cartoGRAPHs==2.0.1) (1.0.1)\n",
      "Requirement already satisfied: numba in /Users/chris/opt/anaconda3/envs/myenv/lib/python3.8/site-packages (from cartoGRAPHs==2.0.1) (0.54.1)\n",
      "Requirement already satisfied: seaborn in /Users/chris/opt/anaconda3/envs/myenv/lib/python3.8/site-packages (from cartoGRAPHs==2.0.1) (0.11.2)\n",
      "Requirement already satisfied: umap-learn in /Users/chris/opt/anaconda3/envs/myenv/lib/python3.8/site-packages (from cartoGRAPHs==2.0.1) (0.5.2)\n",
      "Requirement already satisfied: networkx in /Users/chris/opt/anaconda3/envs/myenv/lib/python3.8/site-packages (from cartoGRAPHs==2.0.1) (3.1)\n",
      "Requirement already satisfied: numpy in /Users/chris/opt/anaconda3/envs/myenv/lib/python3.8/site-packages (from cartoGRAPHs==2.0.1) (1.20.3)\n",
      "Requirement already satisfied: scipy in /Users/chris/opt/anaconda3/envs/myenv/lib/python3.8/site-packages (from cartoGRAPHs==2.0.1) (1.10.1)\n",
      "Requirement already satisfied: joblib>=0.11 in /Users/chris/opt/anaconda3/envs/myenv/lib/python3.8/site-packages (from pynndescent==0.5.8->cartoGRAPHs==2.0.1) (1.1.0)\n",
      "Requirement already satisfied: llvmlite>=0.30 in /Users/chris/opt/anaconda3/envs/myenv/lib/python3.8/site-packages (from pynndescent==0.5.8->cartoGRAPHs==2.0.1) (0.37.0)\n",
      "Requirement already satisfied: setuptools in /Users/chris/opt/anaconda3/envs/myenv/lib/python3.8/site-packages (from numba->cartoGRAPHs==2.0.1) (58.0.4)\n",
      "Requirement already satisfied: threadpoolctl>=2.0.0 in /Users/chris/opt/anaconda3/envs/myenv/lib/python3.8/site-packages (from scikit-learn->cartoGRAPHs==2.0.1) (3.0.0)\n",
      "Requirement already satisfied: pyparsing>=2.2.1 in /Users/chris/opt/anaconda3/envs/myenv/lib/python3.8/site-packages (from matplotlib->cartoGRAPHs==2.0.1) (2.4.7)\n",
      "Requirement already satisfied: fonttools>=4.22.0 in /Users/chris/opt/anaconda3/envs/myenv/lib/python3.8/site-packages (from matplotlib->cartoGRAPHs==2.0.1) (4.29.1)\n",
      "Requirement already satisfied: cycler>=0.10 in /Users/chris/opt/anaconda3/envs/myenv/lib/python3.8/site-packages (from matplotlib->cartoGRAPHs==2.0.1) (0.11.0)\n",
      "Requirement already satisfied: python-dateutil>=2.7 in /Users/chris/opt/anaconda3/envs/myenv/lib/python3.8/site-packages (from matplotlib->cartoGRAPHs==2.0.1) (2.8.2)\n",
      "Requirement already satisfied: pillow>=6.2.0 in /Users/chris/opt/anaconda3/envs/myenv/lib/python3.8/site-packages (from matplotlib->cartoGRAPHs==2.0.1) (10.2.0)\n",
      "Requirement already satisfied: packaging>=20.0 in /Users/chris/opt/anaconda3/envs/myenv/lib/python3.8/site-packages (from matplotlib->cartoGRAPHs==2.0.1) (24.0)\n",
      "Requirement already satisfied: kiwisolver>=1.0.1 in /Users/chris/opt/anaconda3/envs/myenv/lib/python3.8/site-packages (from matplotlib->cartoGRAPHs==2.0.1) (1.3.2)\n",
      "Requirement already satisfied: six>=1.5 in /Users/chris/opt/anaconda3/envs/myenv/lib/python3.8/site-packages (from python-dateutil>=2.7->matplotlib->cartoGRAPHs==2.0.1) (1.15.0)\n",
      "Requirement already satisfied: pytz>=2020.1 in /Users/chris/opt/anaconda3/envs/myenv/lib/python3.8/site-packages (from pandas->cartoGRAPHs==2.0.1) (2021.1)\n",
      "Requirement already satisfied: tzdata>=2022.1 in /Users/chris/opt/anaconda3/envs/myenv/lib/python3.8/site-packages (from pandas->cartoGRAPHs==2.0.1) (2024.1)\n",
      "Requirement already satisfied: tenacity>=6.2.0 in /Users/chris/opt/anaconda3/envs/myenv/lib/python3.8/site-packages (from plotly->cartoGRAPHs==2.0.1) (8.0.1)\n",
      "Requirement already satisfied: tqdm in /Users/chris/opt/anaconda3/envs/myenv/lib/python3.8/site-packages (from umap-learn->cartoGRAPHs==2.0.1) (4.62.3)\n",
      "Installing collected packages: pynndescent, cartoGRAPHs\n",
      "  Attempting uninstall: pynndescent\n",
      "    Found existing installation: pynndescent 0.5.5\n",
      "    Uninstalling pynndescent-0.5.5:\n",
      "      Successfully uninstalled pynndescent-0.5.5\n",
      "  Attempting uninstall: cartoGRAPHs\n",
      "    Found existing installation: cartoGRAPHs 2.0.0\n",
      "    Uninstalling cartoGRAPHs-2.0.0:\n",
      "      Successfully uninstalled cartoGRAPHs-2.0.0\n",
      "Successfully installed cartoGRAPHs-2.0.1 pynndescent-0.5.8\n"
     ]
    }
   ],
   "source": [
    "!pip install cartoGRAPHs==2.0.1"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "b8138ad1-376f-47a4-b422-cd55943b30d4",
   "metadata": {},
   "outputs": [],
   "source": [
    "from cartoGRAPHs import *"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "living-russell",
   "metadata": {},
   "source": [
    "### DEFINE A NETWORK"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "blocked-journalism",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "G = nx.scale_free_graph(n=100)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2c432e56",
   "metadata": {},
   "source": [
    "### Layout: \"FORCE-DIRECTED method\"\n",
    "using the networkx package"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "1341a2a8",
   "metadata": {},
   "outputs": [],
   "source": [
    "pos = nx.spring_layout(G, dim = 3, iterations=50) # \"spring_layout\" can be replaced with almost any layout from networkx\n",
    "coords = [i.tolist() for i in list(pos.values())]\n",
    "posG3D_spring = dict(zip(pos.keys(),coords))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "id": "f546d10e",
   "metadata": {},
   "outputs": [],
   "source": [
    "d_nodecolors = dict(zip(list(G.nodes()),['#0000FF']*len(list(G.nodes()))))\n",
    "d_linkcolors = dict(zip(list(G.edges()),['#0000FF']*len(list(G.edges()))))\n",
    "\n",
    "d_deg=dict(G.degree())\n",
    "l_annotations_csv = ['Node: '+str(i)+'; Node: '+str(j) for i,j in zip(list(G.nodes()), d_deg.values())]\n",
    "l_annotations_json = [list((\"Node: \"+str(i),\"Node: \"+str(j))) for i,j in zip(list(G.nodes()), d_deg.values())]\n",
    "d_annotations_csv = dict(zip(list(G.nodes()),l_annotations_csv))\n",
    "d_annotations_json = dict(zip(list(G.nodes()),l_annotations_json))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "id": "750a42d3",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Export done.\n"
     ]
    }
   ],
   "source": [
    "plot_3Dfigure(G, posG3D_spring, \n",
    "              d_features = None, \n",
    "              d_colors = d_nodecolors, \n",
    "              d_size = None, \n",
    "              d_legend = None, \n",
    "              path = '', \n",
    "              fname = 'Spring_3D', \n",
    "              scheme = 'dark',\n",
    "              #with_edges = False\n",
    "             )\n",
    "\n",
    "exportVR_CSV('Spring_3D', G, posG3D_spring, d_nodecolors, d_annotations_csv, d_linkcolors)\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b1f07e30-41b7-4ad2-875a-c22a4f320720",
   "metadata": {},
   "source": [
    "#### Layout: \"PORTRAIT\"\n",
    "this layout type is basically a 2D or 3D representation of a network. The layout is based on \n",
    "layout method (parameter) which determines the structural or functional characteristics emphasized in the layout."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "id": "f7dac009-f8cc-4705-8608-22eee785e233",
   "metadata": {},
   "outputs": [],
   "source": [
    "posG2D = generate_layout(G, \n",
    "                        dim = 2, \n",
    "                        layoutmethod = 'global',\n",
    "                        dimred_method='umap',\n",
    "                        )\n",
    "\n",
    "posG3D = generate_layout(G, \n",
    "                        dim = 3, \n",
    "                        layoutmethod = 'global',\n",
    "                        dimred_method='umap'\n",
    "                        )"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "id": "4df461bd-874e-403b-9b79-d227439804d6",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Export done.\n"
     ]
    }
   ],
   "source": [
    "plot_2Dfigure(G, posG2D, \n",
    "              d_features = None, \n",
    "              d_colors = d_nodecolors,\n",
    "              d_size = None, \n",
    "              d_legend = None, \n",
    "              path = '', \n",
    "              fname = 'Portrait_2D', \n",
    "              scheme = 'dark',\n",
    "              #with_edges = False\n",
    "             )\n",
    "\n",
    "exportVR_CSV('Portrait_2D', G, posG2D, d_nodecolors, d_annotations_csv, d_linkcolors)\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "id": "81114f28-9d9d-4157-9ead-6d252d42f956",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Export done.\n"
     ]
    }
   ],
   "source": [
    "plot_3Dfigure(G, posG3D, \n",
    "              d_features = None, \n",
    "              d_colors = d_nodecolors,\n",
    "              d_size = None, \n",
    "              d_legend = None, \n",
    "              path = '', \n",
    "              fname = 'Portrait_3D', \n",
    "              scheme = 'dark',\n",
    "              #with_edges = False\n",
    "             )\n",
    "\n",
    "exportVR_CSV('Portrait_3D', G, posG3D, d_nodecolors, d_annotations_csv, d_linkcolors)\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "indie-vienna",
   "metadata": {
    "tags": []
   },
   "source": [
    "#### Layout: \"TOPOGRAPHIC MAP\"\n",
    "this layout generates a topographical map visualization. It starts with a 2D embedding and introduces a z-parameter to layer nodes in 3D space like geographical layers."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "id": "respective-plumbing",
   "metadata": {
    "tags": []
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Export done.\n"
     ]
    }
   ],
   "source": [
    "# d_z = a dictionary with keys=G.nodes and values=any int/float assigned to a node\n",
    "d_deg = dict(nx.degree_centrality(G))\n",
    "\n",
    "z_list = list(d_deg.values())\n",
    "d_z = dict(zip(list(G.nodes()),z_list))\n",
    "posG_topographic = layout_topographic(posG2D, d_z)\n",
    "\n",
    "plot_3Dfigure(G, posG_topographic, \n",
    "              d_features = None, \n",
    "              d_colors = d_nodecolors,\n",
    "              d_size = None, \n",
    "              d_legend = None, \n",
    "              path = '', \n",
    "              fname = 'Topographic',\n",
    "              scheme = 'dark'\n",
    "             )\n",
    "\n",
    "exportVR_CSV('Topographic', G, posG_topographic, d_nodecolors, d_annotations_csv, d_linkcolors)\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "advanced-subcommittee",
   "metadata": {},
   "source": [
    "#### Layout: \"GEODESIC MAP\"\n",
    "this layout embeds nodes on a sphere and splits the sphere embedding based on a radius parameter to generate shells of spheres, where each node has a specific position on a specific shell given the input. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "id": "noted-thompson",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Export done.\n"
     ]
    }
   ],
   "source": [
    "# d_rad = a dictionary with keys=G.nodes and values=any radius assigned to each node\n",
    "\n",
    "rad_list = list([(1-i) for i in d_deg.values()])\n",
    "d_rad = dict(zip(list(G.nodes()), rad_list))\n",
    "posG_geodesic = layout_geodesic(G, d_rad)\n",
    "\n",
    "plot_3Dfigure(G, posG_geodesic, \n",
    "              d_features = None, \n",
    "              d_colors = None, \n",
    "              d_size = None, \n",
    "              d_legend = None,  \n",
    "              path = '', \n",
    "              fname = 'Geodesic', \n",
    "              scheme = 'dark'\n",
    "             )\n",
    "\n",
    "exportVR_CSV('Geodesic', G, posG_geodesic, d_nodecolors, d_annotations_csv, d_linkcolors)\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f7068290-7cdf-4d2b-ad04-4c44651f9b85",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "b2632e51",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ddd83787",
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": ".venv",
   "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.8.2"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}