examples/fastrp-and-knn.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "5cb64c55",
   "metadata": {},
   "source": [
    "# Product recommendations with kNN based on FastRP embeddings"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ff8330bd",
   "metadata": {
    "colab_type": "text"
   },
   "source": [
    "<a target=\"_blank\" href=\"https://colab.research.google.com/github/neo4j/graph-data-science-client/blob/main/examples/fastrp-and-knn.ipynb\">\n",
    "  <img src=\"https://colab.research.google.com/assets/colab-badge.svg\" alt=\"Open In Colab\"/>\n",
    "</a>"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a759796d",
   "metadata": {},
   "source": [
    "This Jupyter notebook is hosted [here](https://github.com/neo4j/graph-data-science-client/blob/main/examples/fastrp-and-knn.ipynb) in the Neo4j Graph Data Science Client Github repository.\n",
    "\n",
    "The notebook exemplifies how to use the `graphdatascience` Python library to operate Neo4j GDS.\n",
    "It shows an adapted version of the FastRP and kNN end-to-end example from the GDS Manual, found [here](https://neo4j.com/docs/graph-data-science/current/end-to-end-examples/fastrp-knn-example).\n",
    "\n",
    "We consider a graph of products and customers, and we want to find new products to recommend for each customer. We want to use [the K-Nearest Neighbors algorithm (kNN)](https://neo4j.com/docs/graph-data-science/current/algorithms/knn/) to identify similar customers and base our product recommendations on that. In order to be able to leverage topological information about the graph in kNN, we will first create node embeddings using [FastRP](https://neo4j.com/docs/graph-data-science/current/machine-learning/node-embeddings/fastrp/). These embeddings will be the input to the kNN algorithm.\n",
    "\n",
    "We will then use a Cypher query to generate recommendations for each pair of similar customers, where products that have been purchased by one of the customers will be recommended to the other."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c4596ec8",
   "metadata": {},
   "source": [
    "## Prerequisites\n",
    "\n",
    "Running this notebook requires a Neo4j server with a recent version (2.0+) of GDS installed.\n",
    "We recommend using Neo4j Desktop with GDS, or AuraDS.\n",
    "\n",
    "The `graphdatascience` Python library needs to be installed as well. See the examples in the Setup section below and in the [client installation instructions](https://neo4j.com/docs/graph-data-science-client/current/installation/)."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "39328998",
   "metadata": {},
   "source": [
    "## Setup\n",
    "\n",
    "We start by installing and importing our dependencies, and setting up our GDS client connection to the database."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "8fde45a7",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Install necessary dependencies\n",
    "%pip graphdatascience"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "44abe56c",
   "metadata": {},
   "outputs": [],
   "source": [
    "import os\n",
    "from graphdatascience import GraphDataScience\n",
    "\n",
    "# Get Neo4j DB URI and credentials from environment if applicable\n",
    "NEO4J_URI = os.environ.get(\"NEO4J_URI\", \"bolt://localhost:7687\")\n",
    "NEO4J_AUTH = None\n",
    "if os.environ.get(\"NEO4J_USER\") and os.environ.get(\"NEO4J_PASSWORD\"):\n",
    "    NEO4J_AUTH = (\n",
    "        os.environ.get(\"NEO4J_USER\"),\n",
    "        os.environ.get(\"NEO4J_PASSWORD\"),\n",
    "    )\n",
    "\n",
    "gds = GraphDataScience(NEO4J_URI, auth=NEO4J_AUTH)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0878b3e7",
   "metadata": {},
   "source": [
    "## Example graph creation\n",
    "\n",
    "We now create a graph of products and customers in the database. The `amount` relationship property represents the average weekly amount of money spent by a customer on a given product."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "1da893ee",
   "metadata": {},
   "outputs": [],
   "source": [
    "# The `run_cypher` method can be used to run arbitrary Cypher queries on the database.\n",
    "_ = gds.run_cypher(\n",
    "    \"\"\"\n",
    "        CREATE\n",
    "         (dan:Person {name: 'Dan'}),\n",
    "         (annie:Person {name: 'Annie'}),\n",
    "         (matt:Person {name: 'Matt'}),\n",
    "         (jeff:Person {name: 'Jeff'}),\n",
    "         (brie:Person {name: 'Brie'}),\n",
    "         (elsa:Person {name: 'Elsa'}),\n",
    "\n",
    "         (cookies:Product {name: 'Cookies'}),\n",
    "         (tomatoes:Product {name: 'Tomatoes'}),\n",
    "         (cucumber:Product {name: 'Cucumber'}),\n",
    "         (celery:Product {name: 'Celery'}),\n",
    "         (kale:Product {name: 'Kale'}),\n",
    "         (milk:Product {name: 'Milk'}),\n",
    "         (chocolate:Product {name: 'Chocolate'}),\n",
    "\n",
    "         (dan)-[:BUYS {amount: 1.2}]->(cookies),\n",
    "         (dan)-[:BUYS {amount: 3.2}]->(milk),\n",
    "         (dan)-[:BUYS {amount: 2.2}]->(chocolate),\n",
    "\n",
    "         (annie)-[:BUYS {amount: 1.2}]->(cucumber),\n",
    "         (annie)-[:BUYS {amount: 3.2}]->(milk),\n",
    "         (annie)-[:BUYS {amount: 3.2}]->(tomatoes),\n",
    "\n",
    "         (matt)-[:BUYS {amount: 3}]->(tomatoes),\n",
    "         (matt)-[:BUYS {amount: 2}]->(kale),\n",
    "         (matt)-[:BUYS {amount: 1}]->(cucumber),\n",
    "\n",
    "         (jeff)-[:BUYS {amount: 3}]->(cookies),\n",
    "         (jeff)-[:BUYS {amount: 2}]->(milk),\n",
    "\n",
    "         (brie)-[:BUYS {amount: 1}]->(tomatoes),\n",
    "         (brie)-[:BUYS {amount: 2}]->(milk),\n",
    "         (brie)-[:BUYS {amount: 2}]->(kale),\n",
    "         (brie)-[:BUYS {amount: 3}]->(cucumber),\n",
    "         (brie)-[:BUYS {amount: 0.3}]->(celery),\n",
    "\n",
    "         (elsa)-[:BUYS {amount: 3}]->(chocolate),\n",
    "         (elsa)-[:BUYS {amount: 3}]->(milk)\n",
    "    \"\"\"\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ebe0e20c",
   "metadata": {},
   "source": [
    "## Projecting into GDS\n",
    "\n",
    "In order to be able to analyze the data in our database, we proceed to projecting it into memory where GDS can operate on it."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a57cd9f6",
   "metadata": {},
   "outputs": [],
   "source": [
    "# We define how we want to project our database into GDS\n",
    "node_projection = [\"Person\", \"Product\"]\n",
    "relationship_projection = {\"BUYS\": {\"orientation\": \"UNDIRECTED\", \"properties\": \"amount\"}}\n",
    "\n",
    "# Before actually going through with the projection, let's check how much memory is required\n",
    "result = gds.graph.project.estimate(node_projection, relationship_projection)\n",
    "\n",
    "print(f\"Required memory for native loading: {result['requiredMemory']}\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "35c72bd4",
   "metadata": {},
   "outputs": [],
   "source": [
    "# For this small graph memory requirement is low. Let us go through with the projection\n",
    "G, result = gds.graph.project(\"purchases\", node_projection, relationship_projection)\n",
    "\n",
    "print(f\"The projection took {result['projectMillis']} ms\")\n",
    "\n",
    "# We can use convenience methods on `G` to check if the projection looks correct\n",
    "print(f\"Graph '{G.name()}' node count: {G.node_count()}\")\n",
    "print(f\"Graph '{G.name()}' node labels: {G.node_labels()}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f734edb7",
   "metadata": {},
   "source": [
    "## Creating FastRP node embeddings\n",
    "\n",
    "Next we use the [FastRP algorithm](https://neo4j.com/docs/graph-data-science/current/machine-learning/node-embeddings/fastrp/) to generate node embeddings that capture topological information from the graph. We choose to work with `embeddingDimension` set to 4 which is sufficient since our example graph is very small. The `iterationWeights` are chosen empirically to yield sensible results. Please see [the syntax section of the FastRP documentation](https://neo4j.com/docs/graph-data-science/current/machine-learning/node-embeddings/fastrp/#algorithms-embeddings-fastrp-syntax) for more information on these parameters.\n",
    "\n",
    "Since we want to use the embeddings as input when we run kNN later we use FastRP’s mutate mode."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f3e6916f",
   "metadata": {},
   "outputs": [],
   "source": [
    "# We can also estimate memory of running algorithms like FastRP, so let's do that first\n",
    "result = gds.fastRP.mutate.estimate(\n",
    "    G,\n",
    "    mutateProperty=\"embedding\",\n",
    "    randomSeed=42,\n",
    "    embeddingDimension=4,\n",
    "    relationshipWeightProperty=\"amount\",\n",
    "    iterationWeights=[0.8, 1, 1, 1],\n",
    ")\n",
    "\n",
    "print(f\"Required memory for running FastRP: {result['requiredMemory']}\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "8c2a3932",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Now let's run FastRP and mutate our projected graph 'purchases' with the results\n",
    "result = gds.fastRP.mutate(\n",
    "    G,\n",
    "    mutateProperty=\"embedding\",\n",
    "    randomSeed=42,\n",
    "    embeddingDimension=4,\n",
    "    relationshipWeightProperty=\"amount\",\n",
    "    iterationWeights=[0.8, 1, 1, 1],\n",
    ")\n",
    "\n",
    "# Let's make sure we got an embedding for each node\n",
    "print(f\"Number of embedding vectors produced: {result['nodePropertiesWritten']}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1213e261",
   "metadata": {},
   "source": [
    "## Similarities with kNN\n",
    "\n",
    "Now we can run [kNN](https://neo4j.com/docs/graph-data-science/current/algorithms/knn/) to identify similar nodes by using the node embeddings that we generated with FastRP as `nodeProperties`. Since we are working with a small graph, we can set `sampleRate` to 1 and `deltaThreshold` to 0 without having to worry about long computation times. The `concurrency` parameter is set to 1 (along with the fixed `randomSeed`) in order to get a deterministic result. Please see [the syntax section of the kNN documentation](https://neo4j.com/docs/graph-data-science/current/algorithms/knn/#algorithms-knn-syntax) for more information on these parameters.\n",
    "\n",
    "Note that we will use the algorithm’s write mode to write the properties and relationships back to our database, so that we can analyze them later using Cypher."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "9b132f95",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Run kNN and write back to db (we skip memory estimation this time...)\n",
    "result = gds.knn.write(\n",
    "    G,\n",
    "    topK=2,\n",
    "    nodeProperties=[\"embedding\"],\n",
    "    randomSeed=42,\n",
    "    concurrency=1,\n",
    "    sampleRate=1.0,\n",
    "    deltaThreshold=0.0,\n",
    "    writeRelationshipType=\"SIMILAR\",\n",
    "    writeProperty=\"score\",\n",
    ")\n",
    "\n",
    "print(f\"Relationships produced: {result['relationshipsWritten']}\")\n",
    "print(f\"Nodes compared: {result['nodesCompared']}\")\n",
    "print(f\"Mean similarity: {result['similarityDistribution']['mean']}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f2bed240",
   "metadata": {},
   "source": [
    "As we can see the mean similarity between nodes is quite high. This is due to the fact that we have a small example where there are no long paths between nodes leading to many similar FastRP node embeddings."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ff4175c9",
   "metadata": {},
   "source": [
    "## Exploring the results\n",
    "\n",
    "Let us now inspect the results of our kNN call by using Cypher. We can use the `SIMILARITY` relationship type to filter out the relationships we are interested in. And since we just care about similarities between people for our product recommendation engine, we make sure to only match nodes with the `Person` label.\n",
    "\n",
    "Please see [the Cypher manual](https://neo4j.com/docs/cypher-manual/current/) for documentation on how to use Cypher."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ebf3e425",
   "metadata": {},
   "outputs": [],
   "source": [
    "gds.run_cypher(\n",
    "    \"\"\"\n",
    "        MATCH (p1:Person)-[r:SIMILAR]->(p2:Person)\n",
    "        RETURN p1.name AS person1, p2.name AS person2, r.score AS similarity\n",
    "        ORDER BY similarity DESCENDING, person1, person2\n",
    "    \"\"\"\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "086f561b",
   "metadata": {},
   "source": [
    "Our kNN results indicate among other things that the `Person` nodes named \"Annie\" and \"Matt\" are very similar. Looking at the `BUYS` relationships for these two nodes we can see that such a conclusion makes sense. They both buy three products, two of which are the same (`Product` nodes named \"Cucumber\" and \"Tomatoes\") for both people and with similar amounts. We can therefore have high confidence in our approach."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "752bf299",
   "metadata": {},
   "source": [
    "## Making recommendations\n",
    "\n",
    "Using the information we derived that the `Person` nodes named \"Annie\" and \"Matt\" are similar, we can make product recommendations for each of them. Since they are similar, we can assume that products purchased by only one of the people may be of interest to buy also for the other person not already buying the product. By this principle we can derive product recommendations for the `Person` named \"Matt\" using a simple Cypher query."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "cb05d14f",
   "metadata": {},
   "outputs": [],
   "source": [
    "gds.run_cypher(\n",
    "    \"\"\"\n",
    "        MATCH (:Person {name: \"Annie\"})-[:BUYS]->(p1:Product)\n",
    "        WITH collect(p1) as products\n",
    "        MATCH (:Person {name: \"Matt\"})-[:BUYS]->(p2:Product)\n",
    "        WHERE not p2 in products\n",
    "        RETURN p2.name as recommendation\n",
    "    \"\"\"\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f732dc04",
   "metadata": {},
   "source": [
    "Indeed, \"Kale\" is the one product that the Person named \"Annie\" buys that is also not purchased by the Person named \"Matt\"."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7b43798c",
   "metadata": {},
   "source": [
    "## Cleaning up\n",
    "\n",
    "Before finishing we can clean up the example data from both the GDS in-memory state and the database."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "fe3961e0",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Remove our projection from the GDS graph catalog\n",
    "G.drop()\n",
    "\n",
    "# Remove all the example data from the database\n",
    "_ = gds.run_cypher(\"MATCH (n) DETACH DELETE n\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d59cb732",
   "metadata": {},
   "source": [
    "## Conclusion\n",
    "\n",
    "Using two GDS algorithms and some basic Cypher we were easily able to derive some sensible product recommendations for a customer in our small example.\n",
    "\n",
    "To make sure to get similarities to other customers for every customer in our graph with kNN, we could play around with increasing the `topK` parameter."
   ]
  }
 ],
 "metadata": {
  "language_info": {
   "name": "python"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}