notebooks/Style and Edit an NDEx Network.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Style and Edit an NDEx Network\n",
    "\n",
    "This Jupyter Notebook demonstrates how to download a NDEx network, perform two common operations, and upload the result using the ndex2 Python client and NiceCX object class. The notebook is composed of 5 sections that show how to complete the following tasks:\n",
    "\n",
    "    I    Load a network from NDEx\n",
    "    II   Copy and apply a visual style from an existing template in NDEx\n",
    "    III  Save (upload) the modified network to your NDEx account\n",
    "    IV   Apply a layout\n",
    "    V    Save (update) the modified network to your NDEx account\n",
    "    \n",
    "The two networks used in this notebook can be found in the **2021 NDEx Current Protocols** tutorial account at http://ndexbio.org/#/user/bcb8f35a-a7a2-11eb-9e72-0ac135e8bacf\n",
    "\n",
    "\n",
    "# Installation\n",
    "\n",
    "The NDEx2 Python Client module can be installed from the Python Package Index (PyPI) repository using PIP:\n",
    "```\n",
    "pip install ndex2\n",
    "```\n",
    "\n",
    "If you already have an older version of the ndex2 module installed, you can use this command instead:\n",
    "```\n",
    "pip install --upgrade ndex2\n",
    "```\n",
    "\n",
    "# Resources\n",
    "\n",
    "The Sphinx documentation for the ndex2 client package is at https://ndex2.readthedocs.io/en/latest/.\n",
    "\n",
    "This and additional Jupyter Notebook with more advanced examples are available at https://github.com/ndexbio/ndex-jupyter-notebooks.\n",
    "\n",
    "Examples for JavaScript and R can be found in the tutorial “Automation in the Cytoscape Ecosystem” available at https://github.com/cytoscape/cytoscape-ismb-2020/blob/master/README.md.\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "=================================================================================================================="
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "=================================================================================================================="
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Section I\n",
    "\n",
    "### Load Network from NDEx\n",
    "\n",
    "We will import a public network from NDEx into the python environment. Networks are provided a Universal Unique ID (UUID) by NDEx that can be used to reliably reference a particular network. We will load the network called \"Sonic hedgehog\" available here: http://ndexbio.org/viewer/networks/cfd3528f-a7a4-11eb-9e72-0ac135e8bacf. Please click the link to look at the network before we move forward with the next steps.\n",
    "\n",
    "**ndex2.create_nice_cx_from_server** makes the request to the NDEx server URL with the UUID of the network. The server returns the network in CX format which is used to create a NiceCX object."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import ndex2\n",
    "\n",
    "SERVER = 'http://ndexbio.org'\n",
    "NETWORK_UUID = 'cfd3528f-a7a4-11eb-9e72-0ac135e8bacf'\n",
    "\n",
    "#This is used to create clickable links to view the networks in NDEx\n",
    "NETWORK_BASE_URL = 'http://ndexbio.org/viewer/networks/'\n",
    "\n",
    "# Load a public network from NDEx\n",
    "nice_cx_network = ndex2.create_nice_cx_from_server(SERVER, uuid=NETWORK_UUID)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Use the \"print_summary()\" convenience function to get a summary of the imported network\n",
    "nice_cx_network.print_summary()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can also capitalize on the cyjupyter widget to display our network in the notebook using cytoscape.js"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from cyjupyter import Cytoscape\n",
    "\n",
    "# Convert the NiceCX object into a CX JSON object and visualize it with the CyJupyter widget\n",
    "nice_cx_network_viz = nice_cx_network.to_cx()\n",
    "Cytoscape(data=nice_cx_network_viz, format='cx')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Or simply generate a link to view our network in the browser:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Click this link to view the network you just imported from NDEx in your browser\n",
    "print(\"Network's URL (click to view!): \" + NETWORK_BASE_URL + NETWORK_UUID)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "=================================================================================================================="
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Section II\n",
    "\n",
    "### Copy Visual Style\n",
    "\n",
    "One of the easiest ways to apply a visual style to a network is to copy that style from another network. This allows you you work on the style of your network in Cytoscape using the interactive style editor, then save the network to NDEx for future use as a template. The NiceCX class provides a special method for this common operation, both downloading the template and copying the style to the target network.\n",
    "\n",
    "Here, we copy the visual style from this colorful template network in NDEx: http://www.ndexbio.org/#/network/b8ff8c89-a7b0-11eb-9e72-0ac135e8bacf and apply it to the 'Sonic Hedgehog' network we just imported from NDEx in the previous step:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "TEMPLATE_UUID = 'b8ff8c89-a7b0-11eb-9e72-0ac135e8bacf'\n",
    "\n",
    "# Copy the style from a template network in NDEx and apply it to our NiceCX network\n",
    "nice_cx_network.apply_template(SERVER, TEMPLATE_UUID)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "=================================================================================================================="
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Section III\n",
    "\n",
    "### Save Network to NDEx\n",
    "\n",
    "NiceCX networks have a convenient one-step upload method. Saving a network to your account requires you to provide your NDEx username and password. We will now save the 'Sonic Hedgehog' network with its colorful visual style to the NDEx account you created earlier on, in Protocol 1 of this paper. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# This is used to prompt users for NDEx credentials in this notebook\n",
    "import getpass"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# Watch out for typos and be sure to hit enter in the field to set the value!!!\n",
    "NDEXUSER = getpass.getpass()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Watch out for typos and be sure to hit enter in the field to set the value!!!\n",
    "NDEXPASSWORD = getpass.getpass()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Let's first rename our modified network\n",
    "nice_cx_network.set_name('Sonic Hedgehog colorful (ndex2)')\n",
    "\n",
    "# Then save it to NDEx and return the URL of the network's page as well as its UUID\n",
    "response = nice_cx_network.upload_to(SERVER, NDEXUSER, NDEXPASSWORD)\n",
    "my_network_uuid = response.split('/')[-1]\n",
    "\n",
    "print ('=' *15)\n",
    "print(\"Network's URL (click to view!): \" + NETWORK_BASE_URL + my_network_uuid)\n",
    "print(\"Network's UUID: \" + my_network_uuid)\n",
    "\n",
    "# Convert the NiceCX object into a CX JSON object and visualize it with the CyJupyter widget\n",
    "nice_cx_network_viz = nice_cx_network.to_cx()\n",
    "Cytoscape(data=nice_cx_network_viz, format='cx')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### You can now compare the visual style differences between the original 'Sonic Hedgehog' and your new 'Sonic Hedgehog colorful (ndex2)' networks."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "=================================================================================================================="
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Section IV\n",
    "\n",
    "### Apply a layout\n",
    "\n",
    "The ndex2 client and NiceCX class do not provide network manipulation functionalities; for such operations, the data must first be cast into a different data model, in this case a NetworkX object.\n",
    "\n",
    "In the python environment, we will start from our NiceCX network and generate a NetworkX object using the NiceCX **to_networkx** method and then use the NetworkX spiral_layout method to assign positions to the nodes.\n",
    "\n",
    "The result of the layout operation is a Python dictionary of positions keyed by nodes. We can display the network with the new layout using the NetworkX draw method, passing in the positions.\n",
    "\n",
    "Finally, to set the new layout in the NiceCX network, we need to transform the NetworkX positions into a CX cartesianLayout aspect."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import networkx as nx\n",
    "\n",
    "# Convert the network to a NetworkX object\n",
    "NX_NETWORK = nice_cx_network.to_networkx(mode='default')\n",
    "\n",
    "# Create layout and visualize it\n",
    "pos = nx.drawing.layout.spiral_layout(NX_NETWORK, scale=700)\n",
    "nx.draw(NX_NETWORK, pos)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Transfer new layout back to original network\n",
    "new_cart_layout = []\n",
    "for node_id, coordinates in pos.items():\n",
    "    new_cart_layout.append({\n",
    "        'node': node_id,\n",
    "        'x': coordinates[0],\n",
    "        'y': -coordinates[1]   # See note below!!!\n",
    "    })\n",
    "nice_cx_network.set_opaque_aspect(ndex2.constants.CARTESIAN_LAYOUT_ASPECT, new_cart_layout)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "***Note:***\n",
    "*The minus sign in front of the ‘y’ coordinates in line 7 in the block of code above is required to ensure that the layout of your NiceCX network will be identical to that you previewed when drawing the NetworkX network. The reason for this is that NetworkX uses one convention for the zero position of cartesian coordinates (zero at bottom left) while Cytoscape/cytoscape.js/CX use another (zero at top right).  So, omitting the minus sign in line 7 would result in a NiceCX network with a vertically flipped layout.*"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Save (Update) Network to NDEx\n",
    "\n",
    "NiceCX networks also have an **update_to** method to update an existing network instead of creating a new one; the target network to be updated is specified by its UUID and this **MUST** be the first argument passed in.\n",
    "We will now update the 'Sonic Hedgehog colorful (ndex2)' network we saved earlier on, with its updated version boasting the new spiral layout."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# First, let's rename our modified network\n",
    "nice_cx_network.set_name('Sonic Hedgehog colorful spiral (ndex2)')\n",
    "\n",
    "# Update existing network in NDEx and return the URL of the network's page\n",
    "# as well as its UUID\n",
    "nice_cx_network.update_to(my_network_uuid, SERVER, NDEXUSER, NDEXPASSWORD)\n",
    "\n",
    "print ('=' *15)\n",
    "print(\"Network's URL (click to view!): \" + NETWORK_BASE_URL + my_network_uuid)\n",
    "print(\"Network's UUID: \" + my_network_uuid)\n",
    "\n",
    "# Convert the NiceCX object into a CX JSON object and visualize it with the CyJupyter widget\n",
    "nice_cx_network_viz = nice_cx_network.to_cx()\n",
    "Cytoscape(data=nice_cx_network_viz, format='cx')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### You can now verify that the 'Sonic Hedgehog colorful (ndex2)' network in your account has been replaced (updated) by the latest version that contains the spiral layout we added using NetworkX."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "=================================================================================================================="
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "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.4"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}