examples/notebooks/Create and run embedding pipelines.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "7932000f",
   "metadata": {},
   "source": [
    "## Prerequisites and installation instructions\n",
    "\n",
    "This notebook uses `bluegraph.downstream.similarity` module for building similarity indices (on embedded nodes, for example). In order to run it the Facebook :code:`Faiss` library must be installed separately. Please, see [Faiss installation instructions](https://github.com/facebookresearch/faiss/blob/master/INSTALL.md).\n",
    "\n",
    "\n",
    "We recommend using `conda` for installing `faiss`. For example:\n",
    "\n",
    "```\n",
    "conda install -c conda-forge faiss\n",
    "```\n",
    "\n",
    "or as a part of a new `conda` environment:\n",
    "\n",
    "```\n",
    "conda create --name <your_environment> -c conda-forge faiss\n",
    "conda activate <your_environment>\n",
    "```\n",
    "\n",
    " \n",
    "This notebook illustrates some graph representation learning techniques and use `stellargraph` as a backend. BlueGraph and the set of dependecies supporting `stellargraph` can be installed using:\n",
    "\n",
    " ```\n",
    " pip install bluegraph[stellargraph]\n",
    " ```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b2613554",
   "metadata": {},
   "source": [
    "# Creating and running embedding pipelines\n",
    "\n",
    "`bluegraph` allows to create emebedding pipelines (using the `EmbeddingPipeline` class) that represent a useful wrapper around a sequence of steps necessary to produce embeddings and compute point similarities. In the example below we create a pipeline for producing `attri2vec` node embeddings and computing their cosine similarity."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "0b75b3b4",
   "metadata": {},
   "outputs": [],
   "source": [
    "from bluegraph.core import PandasPGFrame\n",
    "\n",
    "from bluegraph.preprocess.encoders import ScikitLearnPGEncoder\n",
    "from bluegraph.backends.stellargraph import StellarGraphNodeEmbedder\n",
    "from bluegraph.downstream.similarity import (SimilarityProcessor,\n",
    "                                             FaissSimilarityIndex,\n",
    "                                             ScikitLearnSimilarityIndex,\n",
    "                                             SimilarityIndex)\n",
    "from bluegraph.downstream import EmbeddingPipeline"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1be1543c",
   "metadata": {},
   "source": [
    "## Example 1: creating pipeline trainable with `run_fitting`"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3754e35f",
   "metadata": {},
   "source": [
    "We first create an encoder object that will be used in our pipeline to encode node property `definition` using a TfIdf encoder."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "5452e4ea",
   "metadata": {},
   "outputs": [],
   "source": [
    "definition_encoder = ScikitLearnPGEncoder(\n",
    "    node_properties=[\"definition\"],\n",
    "    text_encoding_max_dimension=512,\n",
    "    text_encoding=\"tfidf\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "43780a91",
   "metadata": {},
   "source": [
    "We then create an embedder object that can compute node embeddings for input graphs using `attri2vec` node embedding technique."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a1ff22fd",
   "metadata": {},
   "outputs": [],
   "source": [
    "D = 128\n",
    "params = {\n",
    "    \"length\": 5,\n",
    "    \"number_of_walks\": 10,\n",
    "    \"epochs\": 5,\n",
    "    \"embedding_dimension\": D\n",
    "}\n",
    "attri2vec_embedder = StellarGraphNodeEmbedder(\n",
    "    \"attri2vec\", feature_vector_prop=\"features\", edge_weight=\"npmi\", **params)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d0e2fb8d",
   "metadata": {},
   "source": [
    "Next, we create a similarity processor based of Faiss indices that allows us to perform fast search for nearest neighbors according to our embedding vectors. We set our similarity measure to _cosine similarity_.\n",
    "\n",
    "__Note:__ in the code below we use the `SimilarityProcessor` interface and not `NodeSimilarityProcessor`, as we have done it in previous tutorials. We use this lower abstraction level interface, because the `EmbeddingPipeline` is designed to work with any embedding models (not only node embedding models)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "5418d698",
   "metadata": {},
   "outputs": [],
   "source": [
    "similarity_processor = SimilarityProcessor(\n",
    "    FaissSimilarityIndex(\n",
    "        similarity=\"cosine\", dimension=D, n_segments=5))"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "30dcdea4",
   "metadata": {},
   "source": [
    "And finally we create a pipeline object that stacks all the above-mentioned elements."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "9dbd5995",
   "metadata": {},
   "outputs": [],
   "source": [
    "attri2vec_pipeline = EmbeddingPipeline(\n",
    "    preprocessor=definition_encoder,\n",
    "    embedder=attri2vec_embedder,\n",
    "    similarity_processor=similarity_processor)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9e6eeef3",
   "metadata": {},
   "source": [
    "Now, let us load the training graph from the provided example dataset."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "b8d12d69",
   "metadata": {},
   "outputs": [],
   "source": [
    "graph = PandasPGFrame.load_json(\"../data/cooccurrence_graph.json\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b0a3640f",
   "metadata": {},
   "source": [
    "We run the fitting process, which given the input data performs the following steps:\n",
    "1. fits the encoder\n",
    "2. transforms the data\n",
    "3. fits the embedder\n",
    "4. produces the embedding table\n",
    "5. fits the similarity index"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "c51767e0",
   "metadata": {},
   "outputs": [],
   "source": [
    "attri2vec_pipeline.run_fitting(graph)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d416dc1f",
   "metadata": {},
   "source": [
    "We can save our pipeline to the file system as follows:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "3fde8649",
   "metadata": {},
   "outputs": [],
   "source": [
    "attri2vec_pipeline.save(\n",
    "    \"../data/attri2vec_test_model\",\n",
    "    compress=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ca29c8b7",
   "metadata": {},
   "source": [
    "We can launch prediction of the unseen graph nodes using our pipeline as follows (in this case we use the same graph). As an output, we obtain embedding vectors produced by the model."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "4e70af9a",
   "metadata": {},
   "outputs": [],
   "source": [
    "vectors = attri2vec_pipeline.run_prediction(graph)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "22f26a2d",
   "metadata": {},
   "source": [
    "## Example 2: creating manually trained pipeline "
   ]
  },
  {
   "cell_type": "markdown",
   "id": "af3c1d95",
   "metadata": {},
   "source": [
    "In the previous example we used `FaissSimilarityIndex` and the backend for our nearest neighbors search. `Faiss` indices are updatable and allow us to add new points to the index at any point. Therefore, we were able to create an 'untrained' pipeline stacking preprocessor, embedder and empty similarity index. We then run all the training steps at once by using `run_fitting`. As the result, vectors output by the embedder were added to the index, once they were produced.\n",
    "\n",
    "However, in some cases, similarity indices are static and the set of vectors on which they are built must be provided at the creation time. Consider the following example.\n",
    "\n",
    "We would like to use [BallTree](https://scikit-learn.org/stable/modules/generated/sklearn.neighbors.BallTree.html) index implemented in `scikit-learn` and provided by `bluegraph`'s `ScikitLearnSimilarityIndex`. In the cell below we try to initialize this index without initial vectors on which it must be built."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "7dbf6ad7",
   "metadata": {},
   "outputs": [],
   "source": [
    "try:\n",
    "    sklearn_similarity_processor = SimilarityProcessor(\n",
    "        ScikitLearnSimilarityIndex(\n",
    "            similarity=\"poincare\", dimension=D,\n",
    "            index_type=\"ballktree\", leaf_size=10)\n",
    "    )\n",
    "except SimilarityIndex.SimilarityException as e:\n",
    "    print(\"Caught the following error: \")\n",
    "    print(e)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "060ddc92",
   "metadata": {},
   "source": [
    "This means that we cannot create an initially empty similarity index and let our pipeline fill it with vectors once the embedder has output the them. What we can do instead is run encoding and embedding manually, as follows:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ee7f27c6",
   "metadata": {},
   "outputs": [],
   "source": [
    "transformed_graph = definition_encoder.fit_transform(graph)\n",
    "embedding = attri2vec_embedder.fit_model(transformed_graph)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4f2f93b3",
   "metadata": {},
   "source": [
    "We now can create a similarity index on the produced embedding vectors."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "15569073",
   "metadata": {},
   "outputs": [],
   "source": [
    "sklearn_similarity_processor = SimilarityProcessor(\n",
    "    ScikitLearnSimilarityIndex(\n",
    "        similarity=\"poincare\", dimension=D,\n",
    "        initial_vectors=embedding[\"embedding\"].tolist(),\n",
    "        index_type=\"ballktree\", leaf_size=10))"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "640f6fcf",
   "metadata": {},
   "source": [
    "And, finally, stack our steps into a pipeline that can be dumped and re-used as in the previous example."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "7a44b26f",
   "metadata": {},
   "outputs": [],
   "source": [
    "attri2vec_sklearn_pipeline = EmbeddingPipeline(\n",
    "    preprocessor=definition_encoder,\n",
    "    embedder=attri2vec_embedder,\n",
    "    similarity_processor=sklearn_similarity_processor)"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "clean_bg",
   "language": "python",
   "name": "clean_bg"
  },
  "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": 5
}