KGC from Technical Text.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# Knowledge Graph Construction from Technical Short Text\n",
    "\n",
    "In this notebook we are going to construct a simple knowledge graph using Python, and run some queries on the graph in Neo4j. We have broken the notebook into several steps:\n",
    "\n",
    "1. Problem description\n",
    "2. Introduction to Natural and Technical Language Processing\n",
    "3. Loading the data\n",
    "4. Cleaning the data via **Lexical Normalisation**\n",
    "5. Extracting entities via **Named Entity Recognition** (NER)\n",
    "6. Creating relations between entities via **Relation Extraction** (RE)\n",
    "7. Combining Named Entity Recognition + Relation Extraction\n",
    "8. Creating the graph\n",
    "9. Querying the graph in Neo4j\n",
    "10. What next?\n",
    "\n",
    "## Requirements\n",
    "\n",
    "To run this notebook you will need to install the following via pip (see the cell below):\n",
    "\n",
    "- `py2neo`: A library for working with Neo4j in Python.\n",
    "- `gqvis`: Our simple tool for visualising graph queries in Jupyter.\n",
    "- `flair`: A deep learning library for natural language processing. Note this library is quite large (a couple gb I believe). If you don't wish to install this, we have provided non deep-learning based alternatives so you can still follow along."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!pip install py2neo\n",
    "!pip install gqvis\n",
    "!pip install flair"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "Sections 8 (Creating the graph) and 9 (Querying the graph in Neo4j) require Neo4j to be installed. We are offering this notebook as both a local installation to run in Jupyter Notebook (via the GitHub repository), and on Google Colab.\n",
    "\n",
    "> ⚠️ If you use the **local Jupyter notebook** (i.e. you have cloned the GitHub repository and are running the notebook via `jupyter notebook`, you will need to have Neo4j Desktop installed (and running) for the last part of the tutorial. You can download and install Neo4j Desktop [here](https://neo4j.com/).\n",
    "\n",
    "> ⚠️ If you are using the **Google Colab notebook**, you do not need to install anything.\n",
    "\n",
    "We will be running through the code and Neo4j graph during the tutorial so you will not miss out if you are not able to install Neo4j."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# 1. Problem description\n",
    "\n",
    "Maintenance work orders (MWOs) capture information on the maintenance performed on assets. Much of this information is structured - such as dates, the functional location (the specific identifier of the asset), costs, and so on. However, a significant volume of the knowledge buried within a MWO is unstructured and therefore inaccessible - it is buried within the short text description.\n",
    "\n",
    "Here are some examples of these short text descriptions:\n",
    "\n",
    "    replace pump\n",
    "    a/c running hot\n",
    "    repair cracked hydraulic tank\n",
    "    \n",
    "As you can see, they often contain indicators of failure modes (e.g. overheating) and end of life events (e.g. a replacement). It would be useful to be able to automatically discover these, however it is next to impossible to manually trawl through thousands of these work orders to discover patterns. We need some way to ask questions of our unstructured data, which is where knowledge graphs shine.\n",
    "\n",
    "Our task in this session is therefore is to transform these work orders into a **knowledge graph**. We will be primarily focusing on the short text descriptions, but there will be some discussion at the end on incorporating other structured knowledge (e.g. dates) into our graph. The goal of building this knowledge graph is to be able to **ask questions of our data** such as \"what are the failure modes observed on pumps?\" and \"which assets have had leaks in the past 6 months?\"\n",
    "\n",
    "![Insight](images/dikw_pyramid.png \"Insight\")\n",
    "\n",
    "Image sourced from [OntoText](https://www.ontotext.com/knowledgehub/fundamentals/dikw-pyramid/)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# 2. Introduction to Natural (and Technical) Language Processing\n",
    "\n",
    "**Natural language processing** (NLP) is the study of the automatic interpetation and manipulation of natural language, like speech and written text. \n",
    "\n",
    "**Technical language processing** (TLP) is a subset of NLP that focuses specifically on technical text, such as the text present in maintenance work orders, doctor's notes, safety records, and so on. \n",
    "\n",
    "Here we will provide a brief overview of some of the most important concepts and terms in NLP."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 2.2. Core NLP terms and ideas"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's first define some core NLP terms and ideas that we will see numerous times throughout this notebook.\n",
    "\n",
    "### 2.2.1. Corpus\n",
    "\n",
    "A 💡 **corpus** is a set of text documents, where a document can be a word, sentence, paragraph, report, etc. Our corpus is a dataset of maintenance work order records.\n",
    "\n",
    "### 2.2.2. Tokenisation\n",
    "\n",
    "The first step for almost any NLP application is 💡 **Tokenisation**. This task splits text into smaller units, such as sentences (sentence tokenisation), words (word tokenisation), or characters (character tokenisation). For most applications, we split text into words.\n",
    "\n",
    "The simplest (but by no means best) way to tokenise is using Python's `split` function, which simply splits a string using the space character as the delimeter:\n",
    "\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "['this', 'is', 'a', 'sentence']\n"
     ]
    }
   ],
   "source": [
    "sentence = \"this is a sentence\"\n",
    "words = sentence.split()\n",
    "\n",
    "print(words)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This is good enough for our purposes (tokenising maintenance work orders), but does not perform well on natural language datasets due to the prevalence of punctuation (full stops, commas etc). The `split` function fails when our sentence ends with a full stop, for example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "['this', 'is', 'a', 'sentence.']\n"
     ]
    }
   ],
   "source": [
    "sentence = \"this is a sentence.\"\n",
    "words = sentence.split()\n",
    "\n",
    "print(words)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Fortunately this does not happen in our dataset so for simplicity we will just be using the `split` function.\n",
    "\n",
    "If you are interested in learning more about tokenisation, there are many tokenisation libraries available in Python. The most popular perhaps is NLTK, which has a range of tokenisers available (see [here](https://www.nltk.org/api/nltk.tokenize.html))."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 2.2.3. Vocabulary\n",
    "\n",
    "A 💡 **vocabularly** is set of terms that correspond to a particular subject matter. The vocabulary of maintenance texts will be quite large, even though the length of the texts are small. This is because maintainers often write the same word many different ways ('air conditioner' is written as 'a/c', 'air cond', etc).\n",
    "\n",
    "Note that depending on the domain, we may treat varying capitalisation of the same word (\"dog\" and \"Dog\", for example) as different words. In this notebook we will treat everything as lower-cased, though in many domains this is not a good idea (especially when many acronyms are present).\n",
    "\n",
    "Determining our vocabulary is a matter of creating a set of unique words in the corpus, for example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{'sentence', 'second', 'first', 'the', 'this', 'is'}\n"
     ]
    }
   ],
   "source": [
    "vocabulary = set()\n",
    "\n",
    "dataset = [\"this is the first sentence\", \"this is the second sentence\"]\n",
    "for sent in dataset:\n",
    "    words = sent.split()\n",
    "    for word in words:\n",
    "        vocabulary.add(word.lower())\n",
    "\n",
    "print(vocabulary)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 2.2.4. Word Embeddings"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Deep learning models are trained on numerical vectors. So how do we train NLP models to understand text?\n",
    "\n",
    "💡 **Word embeddings** are numerical representations of language. We can think of an embedding as a `k` dimensional vector, whereby the embeddings of **semantically similar** items (typically words) have a **high cosine similarity**."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![Embeddings](images/embeddings_2.png \"Embeddings\")\n",
    "\n",
    "Image sourced from [Medium](https://medium.com/@hari4om/word-embedding-d816f643140)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note how \"cat\" and \"kitten\" are close, while \"cat\" and \"houses\" are far away.\n",
    "\n",
    "Actual word embeddings are often much larger (typically 512 dimensions at least), but the general principle is the same. The model that generates the embeddings is designed to ensure that words appearing in a similar context (cat and dog etc) have similar vectors, but words appearing in different contexts (cat and cup) have dissimilar vectors.\n",
    "\n",
    "For fun, you might like to check out [Semantle](https://semantle.com/), where the goal is to determine the word of the day via its cosine similarity to other words."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Language models\n",
    "\n",
    "💡 **Language models** are used to generate embedding vectors. The choice of model depends largely on the corpus.\n",
    "\n",
    "Language models are typically **trained** on a corpus and then used to generate embeddings for words appearing in a different corpus. They can also be **fine-tuned** so that the model predicts more meaningful embeddings for words in a new corpus.\n",
    "\n",
    "Below is a table of some of the most popular language models, including how the models are trained.\n",
    "\n",
    "| Name     | Model                                                 | Method                                                                     | Granularity            |\n",
    "|:---------|:------------------------------------------------------|:---------------------------------------------------------------------------|:-----------------------|\n",
    "| word2vec | Feedforward neural network                            | Predict word given its context (CBOW), or context given a word (skip-gram) | Word-based             |\n",
    "| GloVe    | Log-bilinear regression model                         | Train word vectors from global co-occurence matrix                         | Word-based             |\n",
    "| FastText | Feedforward neural network                            | Predict context given a word (skip-gram)                                   | Character n-gram based |\n",
    "| ELMo     | Bi-directional Long Short Term Memory model (Bi-LSTM) | Predict word given all previous/next words                                 | Character-based        |\n",
    "| BERT     | Bi-directional Transformer                            | Predict masked word(s)                                                     | Wordpiece-based        |\n",
    "| Flair    | Bi-LSTM + Conditional Random Field (CRF)              | Predict next character given the previous characters                                                | Character-based     |\n",
    "\n",
    "While `word2vec` remains one of the most popular language models, it has one key downside - it is not able to generate embedding vectors for words that do not appear in the corpus on which it was trained. This is a problem for our maintenance texts as they are rife with spelling errors, acronyms, etc, as well as many terms that do not occur in common natural language.\n",
    "\n",
    "Character-level embeddings are able to deal with this issue because they are modelled at the character-level, and thus the vector for similar spellings of the same word ('pump', 'puump', etc) will have high cosine similarity. For our application we will therefore choose Flair embeddings, though FastText, ELMO and BERT would work well too."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 2.2.5. Sequence Labelling and Text Classification\n",
    "\n",
    "There are two umbrella terms that almost all NLP tasks fall under - **sequence labelling** and **text classification**.\n",
    "\n",
    "💡 **Sequence labelling** involves assigning a label to every item in a sequence. Examples of sequence labelling tasks involve Named Entity Recognition (assigning an entity class label to every token in a sentence) and Lexical Normalisation (assigning the correct form of the word to every word in a sentence).\n",
    "\n",
    "💡 **Text classification** involves assigning one or more label(s) to an entire sequence. Examples of text classification tasks include sentiment analysis (determining whether a document is positive, negative, or neutral). In this notebook, our Relation Extraction model is also a text classification model (determine the relation type of a given (entity 1, entity 2, context)).\n",
    "\n",
    "![NLP Tasks](images/nlp_tasks.jpg \"NLP Tasks\")\n",
    "\n",
    "Broadly speaking, there are three widely-used types of methods for sequence labelling and text classification: **rule-based methods**, **feature extraction-based methods**, and **representation learning** methods.\n",
    "\n",
    "#### Rule-based methods\n",
    "\n",
    "Rule-based methods for sequence labelling/text classification are relatively straightfoward: we define rules that govern how a particular token or sequence should be labelled. These rules can simple, i.e. in the form of \"token\" &rarr; \"label\", such as \"pump\" &rarr; \"Item\", or more complex using regular expressions (\"p\" followed by any number of \"u\" characters followed by \"mp\" &rarr; \"Item\").\n",
    "\n",
    "Rule-based methods take significant manual effort to develop and refine. They are effectively hard-coded to one dataset - rules defined on one dataset do not necessarily work on another dataset. They are also prone to user error, particularly when one token can have multiple meanings depending on context (such as \"pump\" being either an \"Item\" or \"Activity\").\n",
    "\n",
    "\n",
    "#### Feature extraction-based sequence labelling\n",
    "\n",
    "Unlike rule-based systems, which are more prevalent in commercial applications, feature extraction (i.e. machine-learning) based methods do not require users to spend copius amounts of time developing rule sets for one specific application. \n",
    "\n",
    "Feature-based models are trained on *handcrafted features*, which are carefully selected by the developer to incorporate their own domain knowledge to the particular task. For example, in NER, a commonly-used feature is whether a word begins with a capital letter.\n",
    "\n",
    "Feature extraction-based models include:\n",
    "\n",
    "- **Hidden markov models (HMM)**: A finite-state automata with probabilistic transitions between states.\n",
    "- **Conditional random fields (CRF)**: Undirected graphical models that aim to predict multiple variables dependent on one another.\n",
    "\n",
    "\n",
    "#### Representation learning-based sequence labelling\n",
    "\n",
    "Recent research in NER trends towards deep learning-based models such as Bidirectional Long Short Term Memory (Bi-LSTM) and Transformers. These models require very little manual effort to employ - they simply need a set of annotated training data. The words are fed through an embedding layer to obtain word embedding vectors, which then propagate through the model. Deep learning models excel when trained on large amounts of data.\n",
    "\n",
    "There are several representation learning-based models commonly used throughout NLP:\n",
    "\n",
    "- **Feedforward neural networks**: A \"simple\" neural network comprised of multiple layers.\n",
    "- **Recurrent neural networks (RNN)**: A type of neural network designed to handle sequential data.\n",
    "- **Long short-term memory models (LSTMs)**: A type of RNN that fares better on long sequences (avoids the \"vanishing gradient problem).\n",
    "- **Gated recurrent units (GRUs)**: Similar to LSTM, but with fewer gates (thus, simpler).\n",
    "- **Convolutional neural networks**: A neural network that begins with a convolutional layer.\n",
    "- **Transformers**: An encoder/decoder model that combines feedfoward neural networks with multi-headed attention mechanisms.\n",
    "\n",
    "For our task we are going to use `Flair`, which is a Bidirectional LSTM model, for both Named Entity Recognition and Relation Extraction.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 2.2.7. Supervised learning and the need for annotated data\n",
    "\n",
    "The majority of feature extraction and representation learning-based models are **supervised learning** models, i.e. they learn from annotated data. Annotated data can be obtained via manual annotation using tools such as [Redcoat](https://nlp-tlp/redcoat) and [QuickGraph](https://quickgraph.nlp-tlp.org).\n",
    "\n",
    "For this notebook, our NER model is trained using an annotated dataset of ~4k MWOs tagged by the [UWA Natural & Technical Language Group](https://nlp-tlp.org). "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# 3. Loading the data"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "We are going to be building a knowledge graph on a small sample set of work orders. This will not be seen by the Named Entity Recognition or Relation Extraction models prior to constructing the graph - the idea is to get our models to run *inference* over this dataset to automatically predict the entities, and relationships between the entities, to build a graph.\n",
    "\n",
    "- `sample_work_orders.csv`: A csv file containing a set of work orders.\n",
    "\n",
    "We are using the simple `csv` library to read in the data, though this can also be done using `pandas`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "StartDate     FLOC          ShortText                              Cost   \n",
      "----------------------------------------------------------------------------------------------------\n",
      "              1234.02.11    broken handraill/h/s crows nest        3200   \n",
      "              1234.02.12    broken hose on cylinder                3300   \n",
      "              1234.02.13    broken l/h pulldown chain              3400   \n",
      "              1234.02.14    broken locking pin                     3500   \n",
      "17/08/2001    1234.02.15    broken tool wrench holding cylinder    3600   \n",
      "              1234.02.16    build up rod support beak              3700   \n",
      "              1234.02.17    bull hose air leak                     3800   \n",
      "25/02/2006    1234.02.18    bull hose split                        3900   \n",
      "              1234.02.19    busted hydraulic hose                  4000   \n",
      "              1234.02.20    c spanner for minning                  4100   \n"
     ]
    }
   ],
   "source": [
    "from csv import DictReader\n",
    "from helpers import print_table\n",
    "\n",
    "work_order_file = \"data/sample_work_orders.csv\"\n",
    "\n",
    "# A simple function to read in a csv file and return a list,\n",
    "# where each element in the list is a dictionary of {heading : value}\n",
    "def load_csv(filename):\n",
    "    data = []\n",
    "    with open(filename, 'r') as f:\n",
    "        reader = DictReader(f)\n",
    "        for row in reader:\n",
    "            data.append(row)\n",
    "    return data\n",
    "\n",
    "        \n",
    "work_order_data = load_csv(work_order_file)\n",
    "\n",
    "# Let's have a look at 10 rows\n",
    "print_table(work_order_data[30:40])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    },
    "tags": []
   },
   "source": [
    "# 4. Cleaning the data via Lexical Normalisation\n",
    "\n",
    "Our maintenance work order data is quite noisy - there are spelling errors, typos, acronyms, abbreviations, and so on. This will present challenges to us later when it comes time to build the knowledge graph. So to deal with these issues, we should first clean the text using **lexical normalisation**."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 4.1. Overview of Lexical Normalisation\n",
    "\n",
    "**Lexical normalisation** is an NLP task where the goal is to \"transform an utterance into its standard form, word by word, including both one-to-many (1-n) and many-to-one (n-1) replacements\" (van der Goot *et al.*, 2021). Lexical normalisation is closely related to the task of grammatical error correction however words are not included or removed to improve grammaticality. An example pair of noisy (non-canonical) and clean (canonical) sequences are shown below:\n",
    "\n",
    "    c/o braken a/c vent on the lhs of dump trk cab\n",
    "    change out broken air conditioner vent on the left hand side of dump truck cabin\n",
    "\n",
    "Lexical normalisation focuses on the normalisation of non-canonical lexical terms with one or more of the characteristics shown in the figure below. Lexical errors can be a result of: \n",
    "\n",
    "- unconventional and phonetic spelling\n",
    "- improper casing\n",
    "- acronyms\n",
    "- abbreviations and initialisms\n",
    "- domain-specific terms\n",
    "- jargon\n",
    "- neologisms\n",
    "- erroneous concatenation or tokenization\n",
    "\n",
    "For technical short text such as maintenance work orders, lexical errors are substantial due to the terse nature of the texts and technical content being conveyed.\n",
    "\n",
    "![alt text](images/lexnorm.png \"Lexical normalisation\")\n",
    "\n",
    "(Figure from van der Goot *et al.*, 2018)\n",
    "\n",
    "There are two main reasons why applying lexical normalisation to erroneous/noisy texts is advantageous: **improved downstream performance** in NLP tasks (van der Goot *et al.*, 2017) and **improved quality in knowledge representation** (e.g. nodes in a knowledge graph).\n",
    "\n",
    "The task of lexical normalisation was introduced by (Han and Baldwin, 2011) and made popular through the 2015 workshop on noisy user-generated text (WNUT) (Baldwin *et al.*, 2015) where the main focus was on social media posts, namely Twitter as they capture significant lexical noise. Since then there has been significant progress in the task, with state-of-the-art performance achieved via pipelines of ensembles of discriminators (neural, embeddings) (van der Goot *et al.*, 2017), however statistical/neural token-classification (Stewart *et al.*, 2018; Muller *et al.*, 2019) and sequence-to-sequence (Lourentzou *et al.*, 2019; Nguyen and Sandro, 2020) models have also demonstrated promising performance in various contexts. Recently, state-of-the-art performance on multilingual lexical normalisation has been achieved by fine-tuning ByT5 transformer (Samuel and Milan, 2021; van der Goot *et al.*, 2021).\n",
    "\n",
    "\n",
    "For low-resource technical texts like maintenance work orders, training strategies employed for general domain texts are challenging to adopt as parallel corpora (noisy/clean) are scarce.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 4.2. Running lexical normalisation over our data"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In the interest of time/simplicity we are not going to use a neural model here, but instead we will use a simple lexicon-based normaliser. This model will simply replace a misspelled phrase with its correct form. This is not practical in the real world (as there's no way we could possibly build a lexicon of all possible misspellings) but it is good enough for our small example.\n",
    "\n",
    "The following code imports our `LexiconNormaliser` model. This model simply replaces any predefined terms with their replacements, e.g. \"puump\" will be normalised to \"pump\", and so on.\n",
    "\n",
    "If you're interested in seeing this lexicon, it's available under [data/lexicon_normalisation.csv](files/data/lexicon_normalisation.csv)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {
    "scrolled": false,
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "outputs": [],
   "source": [
    "from helpers import LexiconNormaliser"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "Now that the LexiconNormaliser has been defined, let's run it over all of the ShortText fields in our dataset."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "book out filters\n",
      "book out filters\n",
      "\n",
      "both rear jacks leaking oil\n",
      "both rear jacks leak oil\n",
      "\n",
      "break out u/s\n",
      "break out unserviceable\n",
      "\n",
      "breakout fork cylinder - rework\n",
      "breakout fork cylinder - rework\n",
      "\n",
      "broken control connection\n",
      "breakdown control connection\n",
      "\n"
     ]
    }
   ],
   "source": [
    "lexicon_file = \"data/lexicon_normalisation.csv\"\n",
    "normaliser = LexiconNormaliser(lexicon_file)\n",
    "\n",
    "work_order_data = load_csv(work_order_file)\n",
    "\n",
    "for i, row in enumerate(work_order_data):\n",
    "    before = row['ShortText']    \n",
    "    row['ShortText'] = normaliser.normalise(row['ShortText'])\n",
    "    \n",
    "    # Let's print the first 5 to have a look at the difference\n",
    "    if i > 23 and i <= 28:\n",
    "        print(before)\n",
    "        print(row['ShortText'])\n",
    "        print()\n",
    "    "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    },
    "tags": []
   },
   "source": [
    "# 5. Named Entity Recognition\n",
    "\n",
    "The next task is to extract the entities in the short text descriptions and construct nodes from those entities. This is how we are able to unlock the knowledge captured within the short text and combine it with the structured fields.\n",
    "\n",
    "![alt text](images/extracting-entities-v2.png \"Extracting entities\")\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 5.1. Overview of Named Entity Recognition\n",
    "\n",
    "Named Entity Recognition (NER) is a long-standing NLP task. Introduced in the 6th Message Understanding Conference (MUC-6) in 1996, the goal of NER is to label every *named entity* in a corpus with its corresponding type. NER is a **sequence labelling** task.\n",
    "\n",
    "The choice of entity class depends on the corpus. NER on natural language corpora typically uses four classes (`Person`, `Organisation`, `Location`, `Miscellaneous`), though there are many schemas available. In our application, we will use the following three classes:\n",
    "\n",
    "- **`Item`**: A maintainable item such as \"exhaust\".\n",
    "- **`Activity`**: A maintenance activity performed on an item, such as \"replace\".\n",
    "- **`Observation`**: An observation on an Item, such as \"lagging\".\n",
    "\n",
    "![Example tagged sentence](images/tagged_sentence.png)\n",
    "\n",
    "### 5.1.1. State-of-the-art\n",
    "\n",
    "The current state-of-the-art in NER makes use of deep learning models trained on copious amounts of training data. Here are three of the state-of-the-art models for NER:\n",
    "\n",
    "- [**A Unified Generative Framework for Various NER Subtasks**](https://arxiv.org/pdf/2106.01223): Encodes input sequences into a fixed content space and then autoregressively decodes into an output sequence.\n",
    "- [**LUKE: Deep Contextualized Entity Representations with Entity-aware Self-attention**](https://aclanthology.org/2020.emnlp-main.523/): A transformer-based NER model based on the BERT language model.\n",
    "- [**Contextual String Embeddings for Sequence Labelling (Flair)**](https://aclanthology.org/C18-1139.pdf): A character-level language model feeds into a Bi-LSTM sequence labelling model to predict the entity type of each word.\n",
    "\n",
    "For a detailed list of SOTA NER models feel free to check out [NLP Progress](http://nlpprogress.com/english/named_entity_recognition.html).\n",
    "\n",
    "#### Flair\n",
    "\n",
    "We will be using Flair to perform Named Entity Recognition. Flair combines a character-level language model with a sequence labelling model, and exists as a simple-to-use library on GitHub. A diagram of the model is shown below, taken from the [\"Contextual String Embeddings for Sequence Labelling\"](https://aclanthology.org/C18-1139.pdf) paper.\n",
    "\n",
    "![alt text](images/flair_model.png \"A diagram of the Flair model\")\n",
    "\n",
    "You can learn more about Flair via the papers ([here](https://aclanthology.org/N19-4010/) and [here](https://aclanthology.org/C18-1139.pdf)), or check out the [GitHub repository](https://github.com/flairNLP/flair)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 5.2. Loading and inspecting the data\n",
    "\n",
    "The dataset to train and evaluate the NER model is split into three files:\n",
    "\n",
    "- `ner_dataset/train.txt`: The dataset we will use to *train* the NER model to predict the entities appearing in each work order.\n",
    "- `ner_dataset/dev.txt`: The dataset we will use to *validate* the quality of the model during training.\n",
    "- `ner_dataset/test.txt`: The dataset we will use to *evaluate* the final performance of the NER model after training.\n",
    "\n",
    "Let's start by defining some functions for loading the CONLL-formatted data. The CONLL format is a widely used format for Named Entity Recognition, and looks like this:\n",
    "\n",
    "    Michael B-PER\n",
    "    works O\n",
    "    at O\n",
    "    The B-ORG\n",
    "    University I-ORG\n",
    "    of I-ORG\n",
    "    Western I-ORG\n",
    "    Australia I-ORG\n",
    "    \n",
    "\n",
    "Note the **BIO** format being used here (\"beginning\", \"inside\", \"outside\"). **B** denotes that the word is the start of en entity, **I** denotes that the word is inside an entity, and **O** denotes that a word is not an entity.\n",
    "\n",
    "It's a bit tricky to work with it in this format, so we are going to define some functions to parse it into something like this:\n",
    "\n",
    "    { tokens: ['Michael', 'works', 'at', 'The', 'University', 'of', 'Western', 'Australia'],\n",
    "      labels: ['B-PER', 'O', 'O', 'B-ORG', 'I-ORG', 'I-ORG', 'I-ORG', 'I-ORG'] }\n",
    "      \n",
    "Note that many NLP libraries also have this functionality (NLTK for example) - but we will do it in pure Python in the interest of keeping our dependencies minimal."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [],
   "source": [
    "import os\n",
    "\n",
    "def to_conll_document(s: str):\n",
    "    \"\"\"Parse a CONLL-formatted document into a dictionary of\n",
    "    tokens and labels.\n",
    "\n",
    "    Args:\n",
    "        s (str): A string, separated by newlines, where each\n",
    "        line is a token, then a space, then a label.\n",
    "\n",
    "    Returns:\n",
    "        dict: A dict of tokens and labels.\n",
    "    \"\"\"\n",
    "    tokens, labels = [], []\n",
    "    for line in s.split(\"\\n\"):\n",
    "        if len(line.strip()) == 0:\n",
    "            continue\n",
    "        token, label = line.split()\n",
    "\n",
    "        tokens.append(token)\n",
    "        labels.append(label)\n",
    "    return {'tokens': tokens, 'labels': labels}\n",
    "\n",
    "\n",
    "def load_conll_dataset(filename: str) -> list:\n",
    "    \"\"\"Load a list of documents from the given CONLL-formatted dataset.\n",
    "\n",
    "    Args:\n",
    "        filename (str): The filename to load from.\n",
    "\n",
    "    Returns:\n",
    "        list: A list of documents, where each document is a dict of tokens and labels.\n",
    "    \"\"\"\n",
    "    documents = []\n",
    "    with open(filename, \"r\") as f:\n",
    "        docs = f.read().split(\"\\n\\n\")\n",
    "        for d in docs:\n",
    "            if len(d) == 0:\n",
    "                continue\n",
    "            document = to_conll_document(d)\n",
    "            documents.append(document)\n",
    "    print(f\"Loaded {len(documents)} documents from {filename}.\")\n",
    "    return documents\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's take a quick look at the first row of our training dataset to make sure it loads OK:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Loaded 3201 documents from data/ner_dataset\\train.txt.\n",
      "{'tokens': ['ram', 'on', 'cup', 'rod', 'support', 'broken'], 'labels': ['B-Item', 'O', 'B-Item', 'B-Item', 'I-Item', 'B-Observation']}\n"
     ]
    }
   ],
   "source": [
    "NER_DATASET_PATH = \"data/ner_dataset\"\n",
    "train_dataset = load_conll_dataset(os.path.join(NER_DATASET_PATH, 'train.txt'))\n",
    "\n",
    "print(train_dataset[0])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 5.3. Define an abstract base class for NER Models\n",
    "\n",
    "Seeing as we would like to be able to work with a range of NER models, it's a good idea to create an 'abstract base class' to represent an NER model. This way, we can create classes for our NER models that inherit from this base class. Every model we create must have these three functions:\n",
    "\n",
    "- `train`: Train the model on the datasets in the given path.\n",
    "- `inference`: Run inference over the given sentence.\n",
    "- `load`: Load the model from the given path.\n",
    "\n",
    "If we try to create an NER model that does not have one of these functions, it will raise an error."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {},
   "outputs": [],
   "source": [
    "\"\"\" Abstract base class for the NER Model. \"\"\"\n",
    "\n",
    "from abc import ABC, abstractmethod\n",
    "\n",
    "\n",
    "class NERModel(ABC):\n",
    "    def __init__(self):\n",
    "        pass\n",
    "\n",
    "    @abstractmethod\n",
    "    def train(self, datasets_path: str):\n",
    "        pass\n",
    "\n",
    "    @abstractmethod\n",
    "    def inference(self, sent: list):\n",
    "        pass\n",
    "\n",
    "    @abstractmethod\n",
    "    def load(self, model_path):\n",
    "        pass\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 5.4. Define our NER models"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "tags": []
   },
   "source": [
    "#### 5.4.1. Flair-based NER Model\n",
    "\n",
    "In this tutorial we will use [Flair](https://github.com/flairNLP/flair), which simplifies the process of building a deep learning model for a variety of NLP tasks.\n",
    "\n",
    "The code below is a class representing a `FlairNERModel`, which is based on the `NERModel` class above. It has the same three methods, i.e `train()`, `inference()`, and `save()`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Device: cuda:0\n"
     ]
    }
   ],
   "source": [
    "\"\"\"A Flair-based Named Entity Recognition model. Learns to predict entity\n",
    "classes via deep learning.\"\"\"\n",
    "\n",
    "import os\n",
    "import flair\n",
    "from flair.data import Corpus, Sentence\n",
    "from flair.datasets import ColumnCorpus\n",
    "from flair.embeddings import (\n",
    "    StackedEmbeddings,\n",
    "    FlairEmbeddings,\n",
    ")\n",
    "from flair.models import SequenceTagger\n",
    "from flair.trainers import ModelTrainer\n",
    "from typing import List\n",
    "from flair.visual.training_curves import Plotter\n",
    "import torch\n",
    "\n",
    "\n",
    "HIDDEN_SIZE = 256\n",
    "\n",
    "# Check whether CUDA is available and set the device accordingly\n",
    "if torch.cuda.is_available():\n",
    "    flair.device = torch.device(\"cuda:0\")\n",
    "else:\n",
    "    flair.device = torch.device(\"cpu\")\n",
    "print(\"Device:\", flair.device)\n",
    "\n",
    "\n",
    "class FlairNERModel(NERModel):\n",
    "\n",
    "    model_name: str = \"Flair\"\n",
    "\n",
    "    \"\"\"A Flair-based Named Entity Recognition model.\n",
    "    \"\"\"\n",
    "\n",
    "    def __init__(self):\n",
    "        super(FlairNERModel, self).__init__()\n",
    "\n",
    "        self.model = None\n",
    "\n",
    "    def train(self, datasets_path: os.path, trained_model_path: os.path):\n",
    "        \"\"\" Train the Flair model on the given conll datasets.\n",
    "\n",
    "        Args:\n",
    "            datasets_path (os.path): The folder containing the\n",
    "              train, dev and text CONLL-formatted datasets.\n",
    "            trained_model_path (os.path): The folder to save the trained\n",
    "              model to.\n",
    "        \"\"\"\n",
    "\n",
    "        columns = {0: \"text\", 1: \"ner\"}\n",
    "        corpus: Corpus = ColumnCorpus(\n",
    "            datasets_path,\n",
    "            columns,\n",
    "            train_file=\"train.txt\",\n",
    "            dev_file=\"dev.txt\",\n",
    "            test_file=\"test.txt\",\n",
    "        )\n",
    "        label_dict = corpus.make_label_dictionary(label_type=\"ner\")\n",
    "\n",
    "        # Train the sequence tagger\n",
    "        embedding_types = [\n",
    "            FlairEmbeddings(\"mix-forward\"),\n",
    "            FlairEmbeddings(\"mix-backward\"),\n",
    "        ]\n",
    "\n",
    "        embeddings = StackedEmbeddings(embeddings=embedding_types)\n",
    "\n",
    "        tagger = SequenceTagger(\n",
    "            hidden_size=HIDDEN_SIZE,\n",
    "            embeddings=embeddings,\n",
    "            tag_dictionary=label_dict,\n",
    "            tag_type=\"ner\",\n",
    "            use_crf=True,\n",
    "        )\n",
    "\n",
    "        trainer = ModelTrainer(tagger, corpus)\n",
    "\n",
    "        sm = \"cpu\"\n",
    "        if torch.cuda.is_available():\n",
    "            sm = \"gpu\"\n",
    "        trainer.train(\n",
    "            trained_model_path,\n",
    "            learning_rate=0.1,\n",
    "            mini_batch_size=32,\n",
    "            max_epochs=10,\n",
    "            embeddings_storage_mode=sm,\n",
    "        )\n",
    "\n",
    "        plotter = Plotter()\n",
    "        plotter.plot_weights(os.path.join(trained_model_path, \"weights.txt\"))\n",
    "\n",
    "        self.load(os.path.join(trained_model_path, 'final-model.pt'))\n",
    "\n",
    "    def inference(self, sent: list) -> dict:\n",
    "        \"\"\"Run the inference on a given list of short texts.\n",
    "\n",
    "        Args:\n",
    "            sent (list): The sentence (list of words).\n",
    "\n",
    "        Returns:\n",
    "            dict: The tagged sentence now in the form of {'tokens': [list],\n",
    "                'labels': [list]}.\n",
    "\n",
    "        Raises:\n",
    "            ValueError: If the model has not yet been trained.\n",
    "        \"\"\"\n",
    "        if self.model is None:\n",
    "            raise ValueError(\n",
    "                \"The NER Model has not yet been trained. \"\n",
    "                \"Please train/load this Flair model before proceeding.\"\n",
    "            )\n",
    "        \n",
    "        sentence_obj = Sentence(sentence, use_tokenizer=False)\n",
    "        self.model.predict(sentence_obj)\n",
    "        labels = [\"O\"] * len(sentence)\n",
    "\n",
    "        for entity in sentence_obj.get_spans(\"ner\"):\n",
    "            for i, token in enumerate(entity):\n",
    "                label = entity.get_label(\"ner\").value\n",
    "                prefix = \"B-\" if i == 0 else \"I-\"\n",
    "                \n",
    "                # Token idx starts from 1 in Flair.\n",
    "                labels[token.idx - 1] = prefix + label\n",
    "\n",
    "        return { 'tokens': sent, 'labels': labels }\n",
    "\n",
    "    def load(self, model_path: str):\n",
    "        \"\"\"Load the model from the specified path.\n",
    "\n",
    "        Args:\n",
    "            model_path (os.path): The path to load.\n",
    "\n",
    "        Raises:\n",
    "            ValueError: If the path does not exist i.e. model not yet trained.\n",
    "        \"\"\"\n",
    "        self.model = SequenceTagger.load(model_path)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 5.4.2. Dictionary-based NER model\n",
    "\n",
    "If you are not able to use the Flair library, here is a simple model you can use to extract the entities, albeit with a much weaker performance. This one scans the training data, builds a mapping between each phrase (one or more tokens in a row) and the most common entity type associated with that phrase, then uses that entity type as the prediction when seeing that token in the test data.\n",
    "\n",
    "The model is super simple, so we won't show the code here, but feel free to have a look under `helpers/DictionaryNERModel.py` if you are interested."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {},
   "outputs": [],
   "source": [
    "from helpers import DictionaryNERModel"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 5.5. Training/loading the models"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "tags": []
   },
   "source": [
    "### 5.5.1. Loading the pre-trained Flair model\n",
    "\n",
    "Training a deep learning model takes time, especially without a GPU. We have trained the model on the NER dataset already, and have uploaded the model to HuggingFace. You can simply load the model via the code below."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "c:\\users\\micha\\appdata\\local\\programs\\python\\python37\\lib\\site-packages\\huggingface_hub\\file_download.py:591: FutureWarning: `cached_download` is the legacy way to download files from the HF hub, please consider upgrading to `hf_hub_download`\n",
      "  FutureWarning,\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "2022-11-29 21:07:54,871 loading file C:\\Users\\micha\\.flair\\models\\mwo-ner\\e6f3ee401bab0df2bf0ef5b63f59f57b17b631d5eb531f336980540ed4910d45.8d1c1ab84b25bb14ce63a1634124d5da5c29c553c0776cfa3214bf6a47519b55\n",
      "2022-11-29 21:07:55,435 SequenceTagger predicts: Dictionary with 15 tags: O, S-Item, B-Item, E-Item, I-Item, S-Activity, B-Activity, E-Activity, I-Activity, S-Observation, B-Observation, E-Observation, I-Observation, <START>, <STOP>\n"
     ]
    }
   ],
   "source": [
    "flair_ner_model = FlairNERModel()\n",
    "flair_ner_model.load('nlp-tlp/mwo-ner')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 5.5.2. Training the Flair model from scratch\n",
    "\n",
    "If you wish to train the model yourself (not recommended unless you have a GPU with CUDA enabled), the code for doing that is as follows:\n",
    "\n",
    "    flair_ner_model = FlairNERModel()\n",
    "    flair_ner_model.train(NER_DATASET_PATH, 'models/ner_models/flair')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 5.5.2. \"Training\" the DictionaryNERModel\n",
    "\n",
    "The code below \"trains\" the dictionary-based model. We put \"trains\" in quotes here because it is not really training at all, but rather building a dictionary mapping terms to their corresponding entity categories.\n",
    "\n",
    "Feel free to run this code instead of the Flair code if you do not have Flair installed."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Building dictionary...\n",
      "Loaded 3201 documents from data/ner_dataset\\train.txt.\n",
      "Loaded 402 documents from data/ner_dataset\\dev.txt.\n"
     ]
    }
   ],
   "source": [
    "from helpers import DictionaryNERModel\n",
    "\n",
    "NER_DATASET_PATH = \"data/ner_dataset\"\n",
    "\n",
    "dictionary_ner_model = DictionaryNERModel()\n",
    "dictionary_ner_model.train(NER_DATASET_PATH, 'models/ner_models/dictionary')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 5.6. Running inference on unseen sentences\n",
    "\n",
    "The next step is to use our trained model to infer the entity type of each entity appearing in a list of previously unseen data."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{'tokens': ['air', 'leak', 'around', 'rotary', 'head'], 'labels': ['O', 'B-Observation', 'O', 'B-Item', 'I-Item']}\n"
     ]
    }
   ],
   "source": [
    "tagged_bio_sents = []\n",
    "\n",
    "#model = dictionary_ner_model # Uncomment this line and comment the line below if you want to use the dictionary model\n",
    "model = flair_ner_model\n",
    "\n",
    "sentences = []\n",
    "for row in work_order_data:\n",
    "    sentence = row[\"ShortText\"].split() # We must 'tokenise' the sentence first, i.e. split into words\n",
    "    tagged_sent = model.inference(sentence) # replace 'flair' with 'dictionary' if not using flair  \n",
    "    tagged_bio_sents.append(tagged_sent)\n",
    "\n",
    "# Print an example tagged sentence\n",
    "print(tagged_bio_sents[15])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# 6. Extracting relations between the entities via Relation Extraction\n",
    "\n",
    "We have extracted the entities appearing in each work order. The next step is to extract the relationships between those entities. We can do this using Relation Extraction.\n",
    "\n",
    "![alt text](images/building-relations.png \"Building relations\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 6.1. Overview of Relation Extraction\n",
    "\n",
    "**Relation extraction** is the process of determining the relationships between entities in text. It plays a pivotal role in knowledge graph construction as it provides the relation component of each triple.\n",
    " \n",
    "For our application we are going to use of the following relationships:\n",
    "\n",
    " - **HAS_OBSERVATION**: A relationship between an `Item` and an `Observation`.\n",
    " - **HAS_ACTIVITY**: A relationship between an `Item` and an `Activity`.\n",
    " - **APPEARS_WITH**: A relationship between an `Item` and another `Item`.\n",
    " \n",
    "Note that this is just one way to represent relationships in the data. It is an example of **co-occurrence relations**, i.e. the relationships are formed between entities that co-occur in the same document. We are modelling them this way in light of the types of queries we want to be able to write (e.g. \"what are all failure modes observed on pumps\"), but the code here will be applicable to any relation types.\n",
    "\n",
    "### 6.1.1. Historical approaches to Relation Extraction\n",
    "\n",
    "Previous approaches to Relation Extraction treated the task as a **text classification** task, i.e. given two entities, determine the relationship between them. This can be seen in, for example, the [SemEval 2010 Task 8](https://aclanthology.org/S10-1006/). Many of these methods were **feature extraction-based**, making use of a range of different features such as the local context, the part of speech (noun, verb, etc), syntactic patterns, and so on.\n",
    "\n",
    "### 6.1.2. State-of-the-art\n",
    "\n",
    "The current SOTA relation extraction models are predominately deep learning based. Many of the most recent Relation Extraction models perform both NER and Relation Extraction simultaneously, and thus \"relation extraction\" is becoming less popular as a task on its own. The models perform both NER + RE by taking a sentence as input and producing a sequence that looks like a marked-up list of triples (such as `<triplet>UWA<subj>Michael<obj>works at`). Examples of these models include:\n",
    "\n",
    " - [**DeepStruct: Pretraining of Language Models for Structure Prediction**](https://arxiv.org/pdf/2205.10475): A sequence-labelling based method that uses structure pretraining.\n",
    " - [**REBEL: Relation extraction by end-to-end language generation.**](https://aclanthology.org/2021.findings-emnlp.204/): An autoregressive sequence to sequence model.\n",
    " - [**Span-based joint entity and relation extraction with transformer pre-training (SpERT)**](https://arxiv.org/pdf/1909.07755): A joint NER + Relation extraction model based on the BERT language model.\n",
    " - [**GenIE: generative information extraction**](https://arxiv.org/pdf/2112.08340): A generative model that makes use of an existing knowledge base to constrain the types of relations produced based on the context.\n",
    "\n",
    "For a list of RE models feel free to check out [Awesome Relation Extraction](https://github.com/roomylee/awesome-relation-extraction) or [NLP Progress](https://nlpprogress.com/english/relationship_extraction.html).\n",
    "\n",
    "#### Flair\n",
    "\n",
    "In the interest of simplicity and explainability, we will be performing RE separately from NER, rather than making use of these joint Named Entity Recognition + Relation Extraction models.\n",
    "\n",
    "We are thus once again going to use Flair, this time to perform Relation Extraction. As of the time of writing this notebook, Flair does have support for RE, but not in the latest branch. We will thus be using Flair's Text Classification model to devise our own method for running relation extraction.\n",
    "\n",
    "Our Relation Extraction task will be as follows: *given a row of (entity_1, entity_2, label_1, label_2, context), determine the type of relationship*. All components of the row are concatenated into a single sequence which is then fed through the model to produce the predicted label.\n",
    "\n",
    "Note how this is a **text classification** task, i.e. one sequence mapped to one output label."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 6.2. Loading and inspecting the data\n",
    "\n",
    "Let's take a look again at the Relation Extraction dataset we are working with."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "['broken', 'rod support', 'Observation', 'Item', 'rod support broken', '0', '1', 'O']\n",
      "['rod support', 'broken', 'Item', 'Observation', 'rod support broken', '1', '0', 'HAS_OBSERVATION']\n",
      "['broken', 'cup', 'Observation', 'Item', 'cup rod support broken', '0', '2', 'O']\n"
     ]
    }
   ],
   "source": [
    "import os\n",
    "import json\n",
    "\n",
    "RE_DATASET_PATH = \"data/re_dataset\"\n",
    "\n",
    "\n",
    "def load_re_dataset(filename: str) -> list:\n",
    "    \"\"\"Load the Relation Extraction dataset into a list.\n",
    "        \n",
    "    Args:\n",
    "        filename (str): The name of the file to load.\n",
    "    \"\"\"\n",
    "    re_data = []\n",
    "    with open(filename, 'r') as f:\n",
    "        for row in f:\n",
    "            re_data.append(row.strip().split(','))\n",
    "    return re_data\n",
    "\n",
    "train_dataset = load_re_dataset(os.path.join(RE_DATASET_PATH, 'train.csv'))\n",
    "\n",
    "# Let's take a quick look at a few rows\n",
    "for row in train_dataset[:3]:\n",
    "    print(row)\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can interpret this as follows:\n",
    " - 'broken': entity 1\n",
    " - 'rod support': entity 2\n",
    " - 'Observation': label of entity 1\n",
    " - 'Item': label of entity 2\n",
    " - 'rod support broken': The text between 'broken' and 'rod support', inclusive\n",
    " - '0': The mention index of entity 1\n",
    " - '1': The mention index of entity 2\n",
    " - 'O': The relation type. \"O\" means no relation."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 6.3. Define the Abstract Base Class\n",
    "\n",
    "We are going to see two different Relation Extraction models, so let's define an abstract base class again just like we did for the NER models. Just like the NER model, we have three functions:\n",
    "\n",
    "- `inference`: Given a row (as above, but without the last column), predict the given relation type (\"O\" if no relation).\n",
    "- `train`: Train the model on the files in the given dataset path.\n",
    "- `load`: Load the model from the specified path."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "metadata": {},
   "outputs": [],
   "source": [
    "from abc import ABC, abstractmethod\n",
    "\n",
    "class REModel(ABC):\n",
    "    def __init__(self):\n",
    "        pass\n",
    "\n",
    "    @abstractmethod\n",
    "    def inference(self, row: list) -> str:\n",
    "        pass        \n",
    "\n",
    "    @abstractmethod\n",
    "    def train(self, re_datasets_path: str):\n",
    "        pass\n",
    "\n",
    "    @abstractmethod\n",
    "    def load(self, model_path: str):\n",
    "        pass"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 6.4. Define our Relation Extraction model(s)\n",
    "\n",
    "As with the NER models, we will define one deep learning-based model (Flair) and one simple alternative."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 6.4.1. Flair-based Relation Extraction model"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 46,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Device: cuda:0\n"
     ]
    }
   ],
   "source": [
    "\"\"\" A Flair-based relation extraction model.\n",
    "This one uses Flair's TextClassifier model to classify the\n",
    "relation type of a given row.\n",
    "\"\"\"\n",
    "\n",
    "import os\n",
    "import json\n",
    "from typing import List\n",
    "\n",
    "import flair\n",
    "from flair.trainers import ModelTrainer\n",
    "from flair.datasets import CSVClassificationCorpus\n",
    "from flair.embeddings import (\n",
    "    PooledFlairEmbeddings,\n",
    "    DocumentRNNEmbeddings,\n",
    ")\n",
    "from flair.data import Sentence\n",
    "from typing import List\n",
    "from flair.models import TextClassifier, SequenceTagger\n",
    "from flair.visual.training_curves import Plotter\n",
    "\n",
    "from huggingface_hub import hf_hub_download\n",
    "\n",
    "import torch\n",
    "\n",
    "MAX_EPOCHS = 1\n",
    "HIDDEN_SIZE = 256\n",
    "\n",
    "# Check whether CUDA is available and set the device accordingly\n",
    "if torch.cuda.is_available():\n",
    "    flair.device = torch.device(\"cuda:0\")\n",
    "else:\n",
    "    flair.device = torch.device(\"cpu\")\n",
    "print(\"Device:\", flair.device)\n",
    "\n",
    "\n",
    "class FlairREModel(REModel):\n",
    "\n",
    "    \"\"\"The Flair-based RE model.\"\"\"\n",
    "\n",
    "    model_name: str = \"Flair\"\n",
    "\n",
    "    def __init__(self):\n",
    "        super(FlairREModel, self).__init__()\n",
    "        self.model = None\n",
    "\n",
    "    def train(self, datasets_path: os.path, trained_model_path: os.path):\n",
    "        \"\"\"Train the Flair RE model on the given CSV datasets.\n",
    "\n",
    "        Args:\n",
    "            datasets_path (os.path): The path containing the train and dev\n",
    "               datasets.\n",
    "            trained_model_path (os.path): The path to save the trained model.\n",
    "        \"\"\"\n",
    "\n",
    "        column_name_map = {\n",
    "            0: \"text\",\n",
    "            1: \"text\",\n",
    "            2: \"text\",\n",
    "            3: \"text\",\n",
    "            4: \"text\",\n",
    "            7: \"label_relation\",\n",
    "        }\n",
    "\n",
    "        # Define corpus, labels, word embeddings, doc embeddings\n",
    "        corpus = CSVClassificationCorpus(\n",
    "            datasets_path,\n",
    "            column_name_map,\n",
    "            delimiter=\",\",\n",
    "            label_type=\"relation\",\n",
    "        )\n",
    "\n",
    "        label_dict = corpus.make_label_dictionary(label_type=\"relation\")\n",
    "\n",
    "        word_embeddings = [\n",
    "            PooledFlairEmbeddings(\"mix-forward\"),\n",
    "            PooledFlairEmbeddings(\"mix-backward\"),\n",
    "        ]\n",
    "\n",
    "        document_embeddings = DocumentRNNEmbeddings(\n",
    "            word_embeddings, hidden_size=HIDDEN_SIZE\n",
    "        )\n",
    "\n",
    "        # Initialise sequence tagger\n",
    "        tagger = TextClassifier(\n",
    "            document_embeddings,\n",
    "            label_dictionary=label_dict,\n",
    "            label_type=\"relation\",\n",
    "        )\n",
    "\n",
    "        # Initialize trainer\n",
    "        trainer = ModelTrainer(tagger, corpus)\n",
    "\n",
    "        sm = \"cpu\"\n",
    "        if torch.cuda.is_available():\n",
    "            sm = \"gpu\"\n",
    "        \n",
    "        # Start training\n",
    "        trainer.train(\n",
    "            trained_model_path,\n",
    "            learning_rate=0.1,\n",
    "            mini_batch_size=32,\n",
    "            max_epochs=MAX_EPOCHS,\n",
    "            patience=3,\n",
    "            embeddings_storage_mode=sm,\n",
    "        )\n",
    "\n",
    "        self.load(os.path.join(trained_model_path, 'final-model.pt'))\n",
    "\n",
    "    def load(self, model_path: str):\n",
    "        \"\"\"Load the model from the given path.\n",
    "\n",
    "        Args:\n",
    "            model_path (str): The filename containing the model.\n",
    "               Can also be the name of a repo on Huggingface.\n",
    "        \"\"\"\n",
    "        \n",
    "        # We need to hard-code this one because TextClassifier doesn't\n",
    "        # yet support HuggingFace.\n",
    "        if(model_path == \"nlp-tlp/mwo-re\"):         \n",
    "            model_path = hf_hub_download(\n",
    "                repo_id=\"nlp-tlp/mwo-re\",\n",
    "                filename=\"pytorch_model.bin\",\n",
    "                cache_dir=flair.cache_root / \"models\" / \"mwo-re\"\n",
    "            )\n",
    "        \n",
    "        self.model = TextClassifier.load(model_path)\n",
    "\n",
    "    def inference(self, row: list) -> str:\n",
    "        \"\"\"Run the inference over the given document.\n",
    "\n",
    "        Args:\n",
    "            row (list): The row to predict the relation of.\n",
    "\n",
    "        Returns:\n",
    "            str: The relation type.\n",
    "        \"\"\"\n",
    "        \n",
    "        s = Sentence(\" \".join(row[:5]))\n",
    "        label = \"O\"\n",
    "        self.model.predict(s)\n",
    "        if len(s.labels) > 0:\n",
    "            label = str(s.labels[0].value)\n",
    "        return label\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 6.4.2. 'SimpleMWO' Relation Extraction model\n",
    "\n",
    "Because maintenance work orders are very short (5-7 words typically), generally speaking we can create a useful knowledge graph by simply linking each Item entity in the work order and each other entity in that work order. For example:\n",
    "\n",
    "    replace pump\n",
    "    \n",
    "We can say the \"pump\" entity `HAS_ACTIVITY` \"replace\". Likewise for the following:\n",
    "\n",
    "    fix air conditioner , not working\n",
    "    \n",
    "We can say that \"air conditioner\" `HAS_ACTIVITY` \"fix\", and `HAS_OBSERVATION` \"not working\".\n",
    "\n",
    "This is not a foolproof method, though - it is a heuristic, i.e. a rule-based method designed to exploit a pattern in the data. For creating this specific type of knowledge graph, though, it works quite well, and thus we can define a model to use this heuristic as a weaker alternative to a deep learning model.\n",
    "\n",
    "Just like the dictionary-based NER model, the model is super simple, so we won't show the code here, but feel free to have a look under `helpers/SimpleMWOREModel.py` if you are interested."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 34,
   "metadata": {},
   "outputs": [],
   "source": [
    "from helpers import SimpleMWOREModel"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Here's an example output from the model. Note we have set the last column (i.e. the relation type) to `None`, as it is our model's job to predict that column:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 35,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'HAS_OBSERVATION'"
      ]
     },
     "execution_count": 35,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "r = SimpleMWOREModel()\n",
    "\n",
    "r.inference([\n",
    "  \"rod support\",\n",
    "  \"broken\",\n",
    "  \"Item\",\n",
    "  \"Observation\",\n",
    "  \"rod support broken\",\n",
    "  \"1\",\n",
    "  \"0\",\n",
    "  None\n",
    " ])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 6.5. Train the model/load the pretrained model"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's load the pretrained Flair Relation Extraction model from Huggingface.\n",
    "\n",
    "(or alternatively you can train it yourself by uncommenting the train line, and commenting the load line)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 47,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "2022-11-29 21:11:54,773 loading file C:\\Users\\micha\\.flair\\models\\mwo-re\\models--nlp-tlp--mwo-re\\snapshots\\5f8a5e81a96d0c4022097528a90f659755081994\\pytorch_model.bin\n"
     ]
    }
   ],
   "source": [
    "flair_re_model = FlairREModel()\n",
    "flair_re_model.load('nlp-tlp/mwo-re')\n",
    "\n",
    "#flair_re_model.train(RE_DATASET_PATH, \"models/re_models/flair\") # Uncomment to train manually"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 6.6. Inference\n",
    "\n",
    "Now we have our Relation Extraction model, the next step is to run inference on the MWO dataset to extract the relationships between the entities.\n",
    "\n",
    "We need our data to be in the same format as required by the model, i.e. a list of rows where each row has five columns (entity 1, entity 2, etc), just like the training data used to train the model.\n",
    "\n",
    "So before we can run Relation Extraction, we need to 'wrangle' our data again to get it into the right format."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 6.6.1. Converting the BIO format to the \"Mention\"-based format\n",
    "\n",
    "The BIO-based format from the NER model has one key downside - it is not good for representing 'phrases' of more than one token in length. This makes it difficult to work with for future steps, such as constructing nodes from the entities and running relation extraction. In light of this, we will now convert the BIO-formatted predictions into Mention format, i.e. go from this:\n",
    "\n",
    "    {'tokens': ['a/c', 'not', 'working'],\n",
    "     'labels': ['B-Item', 'B-Observation', 'I-Observation']}\n",
    "    \n",
    "To this:\n",
    "\n",
    "    {'tokens': ['a/c', 'not', 'working'],\n",
    "     'mentions': [\n",
    "         {'start': 0, 'labels': ['Item'], 'end': 1},\n",
    "         {'start': 1, 'labels': ['Observation'], 'end': 3}]}\n",
    "    \n",
    "Note that this format is also able to now support multiple labels per mention (though we will only be using single labels for simplicity). Researchers use this format for **entity typing**, which is similar to NER but with >= 1 label per mention.\n",
    "\n",
    "This step is just a bit of data wrangling - here we have defined a helper function to convert a BIO-tagged sentence into a Mention-tagged sentence."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 37,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{\n",
      " \"tokens\": [\n",
      "  \"air\",\n",
      "  \"leak\",\n",
      "  \"around\",\n",
      "  \"rotary\",\n",
      "  \"head\"\n",
      " ],\n",
      " \"mentions\": [\n",
      "  {\n",
      "   \"start\": 1,\n",
      "   \"labels\": [\n",
      "    \"Observation\"\n",
      "   ],\n",
      "   \"end\": 3,\n",
      "   \"phrase\": \"leak around\"\n",
      "  },\n",
      "  {\n",
      "   \"start\": 3,\n",
      "   \"labels\": [\n",
      "    \"Item\"\n",
      "   ],\n",
      "   \"end\": 5,\n",
      "   \"phrase\": \"rotary head\"\n",
      "  }\n",
      " ]\n",
      "}\n"
     ]
    }
   ],
   "source": [
    "import json\n",
    "\n",
    "def bio_to_mention(bio_doc: dict):\n",
    "    \"\"\"Return a Mention-format representation of a BIO-formatted\n",
    "    tagged sentence.\n",
    "\n",
    "    Args:\n",
    "        bio_doc (dict): The BIO doc to convert to the Mention-based doc.\n",
    "\n",
    "    Returns:\n",
    "        dict: A mention-formatted dict created from the bio_doc.\n",
    "    \"\"\"\n",
    "    tokens = bio_doc[\"tokens\"]\n",
    "    labels = bio_doc[\"labels\"]\n",
    "    mentions_list = []\n",
    "\n",
    "    start = 0\n",
    "    end = 0\n",
    "    label = None\n",
    "    for i, (token, label) in enumerate(\n",
    "        zip(tokens, labels)\n",
    "    ):\n",
    "        if label.startswith(\"B-\"):\n",
    "            if len(mentions_list) > 0:\n",
    "                mentions_list[-1][\"end\"] = i\n",
    "            mentions_list.append({\"start\": i, \"labels\": [label[2:]]})\n",
    "        elif label == \"O\" and len(mentions_list) > 0:\n",
    "            mentions_list[-1][\"end\"] = i\n",
    "        if len(mentions_list) == 0:\n",
    "            continue\n",
    "        if i == (len(tokens) - 1) and \"end\" not in mentions_list[-1]:\n",
    "            mentions_list[-1][\"end\"] = i + 1\n",
    "            \n",
    "    for m in mentions_list:\n",
    "        m['phrase'] = \" \".join(tokens[m['start']:m['end']])\n",
    "    return {'tokens': tokens, 'mentions': mentions_list}\n",
    "\n",
    "\n",
    "# For each BIO tagged sentence in tagged_sents, convert it to the mention-based\n",
    "# representation\n",
    "tagged_sents = []\n",
    "for doc in tagged_bio_sents:\n",
    "    mention_doc = bio_to_mention(doc)\n",
    "    tagged_sents.append(mention_doc)\n",
    "\n",
    "# Let's print our example sentence again, this time with the mention-based\n",
    "# representation.\n",
    "# We'll use json.dumps to make it a bit easier to read.\n",
    "print(json.dumps(tagged_sents[15],indent=1))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note we have added a \"phrase\" to each mention. We technically could get this phrase by looking at the list of tokens from the `start` to the `end` of the mention, but storing it inside `mentions` directly makes things easier later on."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 6.6.2. Building a list of potential relations between entities\n",
    "\n",
    "Now we have our data in a more amenable format, but we still need tabular data as required by the Relation Extraction model. To refresh your memory, this is the required format:\n",
    "\n",
    " - entity 1\n",
    " - entity 2\n",
    " - label of entity 1\n",
    " - label of entity 2\n",
    " - The text between 'broken' and 'rod support', inclusive\n",
    " - The position of entity 1\n",
    " - The position of entity 2\n",
    " - The relation type. \"O\" means no relation.\n",
    " \n",
    "We don't need that last column here as this is what we want our model to predict. We will set it to `None` to denote that no relation has been assigned yet.\n",
    "\n",
    "We also need to add a new column to represent the document index - we will see why later.\n",
    "\n",
    "Here is a helper function to transform our mention-based entity format of a single document into a list of potential relationships between each entity and each other entity in that document."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 41,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "['lights', 'out on', 'Item', 'Observation', 'lights out on', 0, 1, None, 1]\n"
     ]
    }
   ],
   "source": [
    "def build_potential_relations(tagged_sents) -> list:\n",
    "    \"\"\"Build a list of potential relations, i.e. all possible relationships\n",
    "    between each entity in each document. The 8th column (which denotes the\n",
    "    relationship type) will be set to None. The 9th column is the document index.\n",
    "    \n",
    "    Args:\n",
    "        tagged_sents(list): The list of tagged sentences, where each sentence is a\n",
    "            dict of tokens: [list of tokens] and mentions: [list of mentions].\n",
    "    \n",
    "    Returns:\n",
    "        list: A list of rows, where each row is a potential relationship.\n",
    "    \"\"\"\n",
    "\n",
    "    relations = []\n",
    "    for doc_idx, doc in enumerate(tagged_sents):\n",
    "        for m1_idx, mention_1 in enumerate(doc['mentions']):\n",
    "            entity_1 = \" \".join(doc['tokens'][mention_1['start']: mention_1['end']])\n",
    "            label_1 = mention_1['labels'][0]\n",
    "\n",
    "            for m2_idx, mention_2 in enumerate(doc['mentions']):\n",
    "                if m1_idx == m2_idx:\n",
    "                    continue\n",
    "                entity_2 = \" \".join(doc['tokens'][mention_2['start']: mention_2['end']])\n",
    "                label_2 = mention_2['labels'][0]\n",
    "                mention_text = \" \".join(doc['tokens'][mention_1['start']:mention_2['end']]   )         \n",
    "\n",
    "                relations.append(\n",
    "                    [entity_1, entity_2, label_1, label_2, mention_text, m1_idx, m2_idx, None, doc_idx]         \n",
    "                )\n",
    "    return relations\n",
    "            \n",
    "relations = build_potential_relations(tagged_sents)\n",
    "print(relations[0])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 6.6.3 Running inference over every row\n",
    "\n",
    "Now that our data is in the same format that we used to train the Relation Extraction model, we can run the inference on it."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 48,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "['lights', 'out on', 'Item', 'Observation', 'lights out on', 0, 1, 'HAS_OBSERVATION', 1]\n",
      "['lights', 'machine', 'Item', 'Item', 'lights out on machine', 0, 2, 'APPEARS_WITH', 1]\n",
      "['out on', 'lights', 'Observation', 'Item', '', 1, 0, 'O', 1]\n",
      "['out on', 'machine', 'Observation', 'Item', 'out on machine', 1, 2, 'O', 1]\n",
      "['machine', 'lights', 'Item', 'Item', '', 2, 0, 'O', 1]\n",
      "['machine', 'out on', 'Item', 'Observation', '', 2, 1, 'HAS_OBSERVATION', 1]\n",
      "['volt lights', 'out', 'Item', 'Observation', 'volt lights out', 0, 1, 'HAS_OBSERVATION', 2]\n",
      "['out', 'volt lights', 'Observation', 'Item', '', 1, 0, 'O', 2]\n",
      "['compressor oil', 'requires top', 'Item', 'Observation', 'compressor oil requires top', 0, 1, 'HAS_OBSERVATION', 3]\n",
      "['requires top', 'compressor oil', 'Observation', 'Item', '', 1, 0, 'O', 3]\n"
     ]
    }
   ],
   "source": [
    "from helpers import SimpleMWOREModel\n",
    "\n",
    "def tag_all_relations(relations: list):\n",
    "    \"\"\"Run model inference over every potential relation in the list of\n",
    "    relations.\n",
    "    \n",
    "    Args:\n",
    "        relations(list): The list of (untagged) relations.\n",
    "        \n",
    "    Returns:\n",
    "        tagged_relations(list): The same list, but with the rel_type in the\n",
    "           8th column.\n",
    "    \n",
    "    \"\"\"\n",
    "    tagged_relations = []\n",
    "\n",
    "    for rel in relations:\n",
    "        tagged_rel = rel[:]\n",
    "        rel_type = rel_model.inference(rel)\n",
    "        tagged_rel[7] = rel_type\n",
    "        tagged_relations.append(tagged_rel)\n",
    "    return tagged_relations\n",
    "     \n",
    "#rel_model = SimpleMWOREModel()\n",
    "rel_model = flair_re_model\n",
    "tagged_relations = tag_all_relations(relations)\n",
    "\n",
    "# Print the first 10 rows\n",
    "for row in tagged_relations[:10]:\n",
    "    print(row)\n",
    "        "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# 7. Combining Named Entity Recognition + Relation Extraction\n",
    "\n",
    "Now we have outputs from both the NER model and the RE model. The NER model's output looks like this:\n",
    "\n",
    "    {'tokens': ['a/c', 'not', 'working'],\n",
    "     'mentions': [\n",
    "         {'start': 0, 'labels': ['Item'], 'end': 1},\n",
    "         {'start': 1, 'labels': ['Observation'], 'end': 3}]}         \n",
    "While the RE model's output is shown in the cell above.\n",
    "\n",
    "The next step is to combine the two outputs. Fortunately we stored the document index in the relations, so we can easily join them up.\n",
    "\n",
    "Let's add a 'relations' key to this dictionary. It will capture the relationships between mentions, e.g.\n",
    "\n",
    "    'relations': {'start': 0, 'end': 1, 'type': 'HAS_OBSERVATION'}\n",
    "    \n",
    "... which denotes that mention 0 ('a/c') has the observation of mention 1 ('not working')."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 49,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{\n",
      " \"tokens\": [\n",
      "  \"ITEM_ID\",\n",
      "  \"pre-service\",\n",
      "  \"setup\"\n",
      " ],\n",
      " \"mentions\": [\n",
      "  {\n",
      "   \"start\": 2,\n",
      "   \"labels\": [\n",
      "    \"Activity\"\n",
      "   ],\n",
      "   \"end\": 3,\n",
      "   \"phrase\": \"setup\"\n",
      "  }\n",
      " ],\n",
      " \"relations\": []\n",
      "}\n"
     ]
    }
   ],
   "source": [
    "for i, sent in enumerate(tagged_sents):\n",
    "    \n",
    "    # Note we only care about the relations that do not have the class \"O\".\n",
    "    doc_relations = [row for row in tagged_relations if row[7] != \"O\" and row[8] == i]\n",
    "    \n",
    "    sent['relations'] = []    \n",
    "    for row in doc_relations:\n",
    "        rel = {'start': row[5], 'end': row[6], 'type': row[7]}     \n",
    "        sent['relations'].append(rel)\n",
    "\n",
    "# Let's print an example...\n",
    "print(json.dumps(tagged_sents[9], indent=1))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# 8. Creating the graph\n",
    "\n",
    "We now have a data structure that stores the tokens, entity mentions, and relationships between those mentions, for each document. The last step is to put it all into a Neo4j graph so that we can query this information.\n",
    "\n",
    "There are two popular methods for doing this:\n",
    "\n",
    "- Using `py2neo` to programatically insert data into Neo4j\n",
    "- Saving CSVs of your entities and relations, then reading them in via a `LOAD CSV` query in Neo4j\n",
    "\n",
    "The first option is simple but a bit slow, and the second option is a little more complex but much faster. We will go with the first option here in this notebook for simplicity.\n",
    "\n",
    "**If you are using Jupyter Notebook** (i.e. you have cloned the GitHub repository and are running this notebook locally), then you will need to have Neo4j Desktop installed. You can download and install Neo4j from here if you haven't already: https://neo4j.com/download/.\n",
    "\n",
    "> ⚠️ Before proceeding, make sure you have created a new graph in Neo4j and that your new Neo4j graph is running. You can do this by opening Neo4j Browser, clicking \"Add\" at the top-right, then creating a new graph database.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**If you are running this notebook in Google Colab**, you will not need to install Neo4j. It should already be installed on the Colab machine, though it is a little temperamental so errors may arise.\n",
    "\n",
    "If any issues occur, please see the \"Installing Neo4j on Google Colab\" section in the Appendix."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Code for building the graph\n",
    "\n",
    "The following code creates the entire graph using `py2neo`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 50,
   "metadata": {},
   "outputs": [],
   "source": [
    "from py2neo import Graph\n",
    "from py2neo.data import Node, Relationship\n",
    "from dateutil.parser import parse as parse_date\n",
    "\n",
    "GRAPH_PASSWORD = \"password\" # Set this to the password of your Neo4J graph\n",
    "\n",
    "\n",
    "def get_node_id(phrase, entity_class):\n",
    "    \"\"\"A simple function to generate an id.\n",
    "    This ensures an entity that can be different classes (pump for example) can have\n",
    "    a unique node for each class type.\n",
    "    \"\"\"\n",
    "    return f\"{phrase}__{entity_class}\"\n",
    "    \n",
    "# Dates are a little awkward in Neo4j - we have to convert it to an integer representation in Python.\n",
    "# The APOC library has functions to handle this better.\n",
    "def date_to_int(date):\n",
    "    parsed_date = parse_date(str(date))\n",
    "    date = int(\"%s%s%s\" % (parsed_date.year, str(parsed_date.month).zfill(2), str(parsed_date.day).zfill(2)))\n",
    "    return date    \n",
    "    \n",
    "def create_graph(tagged_sents):\n",
    "    \"\"\"Build the Neo4j graph.\n",
    "    We do this by iterating over each tagged_sentence, and constructing the\n",
    "    graph as follows:\n",
    "     - Create a node to represent the document itself.\n",
    "     - Create nodes for each entity appearing in that document, if they have not\n",
    "       already been created. Each unique combination of entity + class will be added, so\n",
    "       pump (the Item) is different from pump (the Activity).\n",
    "     - Create a relationship between each entity and each document in which it appears.\n",
    "     - Create a relationship between each entity and each other entity it is related to,\n",
    "       via the list of relations.\n",
    "     \n",
    "    Args:\n",
    "        tagged_sents(list): The list of tagged sentences.\n",
    "    \"\"\"\n",
    "    graph = Graph(password = GRAPH_PASSWORD)\n",
    "\n",
    "    # We will start by deleting all nodes and edges in the current graph.\n",
    "    # If we don't do this, we will end up with duplicate nodes and edges when running this script again.\n",
    "    graph.delete_all() \n",
    "\n",
    "    tx = graph.begin()\n",
    "    \n",
    "    # Keep track of the created entity nodes.\n",
    "    # We need a way to map the id of the nodes to the py2neo Node objects so that we can\n",
    "    # easily create relationships between these nodes.\n",
    "    created_entity_nodes = {}\n",
    "    \n",
    "    # Iterate over the list of tagged sentences and programmatically create the graph.\n",
    "    for i, sent in enumerate(tagged_sents):\n",
    "        \n",
    "        # Let's first grab some properties from the original work order dataset.\n",
    "        # We will add date and cost into our graph on the Document nodes.\n",
    "        work_order_row = work_order_data[i]\n",
    "        \n",
    "        document_properties = {\n",
    "            'name': \" \".join(sent['tokens']),\n",
    "            'cost': work_order_row['Cost']          \n",
    "            \n",
    "        }\n",
    "        if work_order_row['StartDate'] != \"\":\n",
    "            document_properties[\"date\"] = date_to_int(work_order_row['StartDate'])\n",
    "\n",
    "        \n",
    "        \n",
    "        # Create a node to represent the document.\n",
    "        # Note that if you had additional properties in tagged_sents (such as dates, costs, etc)\n",
    "        # you could add them as properties of the Document nodes here.\n",
    "        document_node = Node(\"Document\", **document_properties)\n",
    "        tx.create(document_node)\n",
    "        \n",
    "        tokens = sent['tokens']\n",
    "        mentions = sent['mentions']\n",
    "        relations = sent['relations']\n",
    "        \n",
    "        for m in mentions:\n",
    "            start = m['start']\n",
    "            end = m['end']\n",
    "            entity_class = m['labels'][0]        \n",
    "            phrase = \" \".join(tokens[start: end])     \n",
    "                    \n",
    "            # Create a node for this entity mention.\n",
    "            # If the node has already been created (i.e. it exists in created_nodes), \n",
    "            # simply retrieve that Node from created_entity_nodes.\n",
    "            # Otherwise, create it, and add it to created_entity_nodes.\n",
    "            entity_node_id = get_node_id(phrase, entity_class)\n",
    "\n",
    "            if entity_node_id in created_entity_nodes:\n",
    "                entity_node = created_entity_nodes[entity_node_id]\n",
    "            else:\n",
    "                entity_node = Node(\"Entity\", entity_class, _id=entity_node_id, name=phrase)\n",
    "                created_entity_nodes[entity_node_id] = entity_node\n",
    "                tx.create(entity_node)            \n",
    "                        \n",
    "                \n",
    "            # Create a relationship between that node and the document\n",
    "            # in which it appears.               \n",
    "            r = Relationship(entity_node, \"APPEARS_IN\", document_node)\n",
    "            tx.create(r)\n",
    "            \n",
    "        # Create relationships between each (entity_1, entity_2) in the\n",
    "        # list of relations for this document.\n",
    "        for rel in relations:\n",
    "            start = rel['start']\n",
    "            end = rel['end']\n",
    "            \n",
    "            phrase_1 = mentions[start]['phrase']\n",
    "            entity_class_1 = mentions[start]['labels'][0]\n",
    "            \n",
    "            phrase_2 = mentions[end]['phrase']\n",
    "            entity_class_2 = mentions[end]['labels'][0]\n",
    "                       \n",
    "            node_1 = created_entity_nodes[get_node_id(phrase_1, entity_class_1)]\n",
    "            node_2 = created_entity_nodes[get_node_id(phrase_2, entity_class_2)]\n",
    "            \n",
    "            r = Relationship(node_1, rel['type'], node_2)\n",
    "            tx.create(r)\n",
    "    tx.commit()\n",
    "\n",
    "create_graph(tagged_sents)        "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# 9. Querying the graph\n",
    "\n",
    "\n",
    "Now that the graph has been created, we can query it in Neo4j. This section lists some example queries that we can run on our graph. Feel free to try your own queries!\n",
    "\n",
    "Note we are using `gqvis` to visualise these in Jupyter Notebook. The results will look very similar if you run these queries directly in the Neo4j browser.\n",
    "\n",
    "*Note about gqvis: gqvis works out of the box in Jupyter Notebook, but to get it working in Jupyter Lab you'll need to install the jupyter_requirejs plugin. See the Appendix section at the bottom of this notebook for more details.*"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "First, let's try a simple query. Here is a query that searches for __all activities performed on engines__:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 51,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<!DOCTYPE html>\n",
       "<meta charset=\"utf-8\" />\n",
       "<link\n",
       "  href=\"https://fonts.googleapis.com/css2?family=Open+Sans&display=swap\"\n",
       "  rel=\"stylesheet\"\n",
       "/>\n",
       "<style>\n",
       "  circle {\n",
       "    cursor: pointer;\n",
       "\n",
       "  }\n",
       "  .not-selected {\n",
       "    opacity: 0.2;\n",
       "  }\n",
       "  text {\n",
       "    pointer-events: none;\n",
       "    font-family: \"Open Sans\", sans-serif;\n",
       "    font-size: 12;\n",
       "  }\n",
       "\n",
       "  g#links {\n",
       "    opacity: 0.3;\n",
       "  }\n",
       "\n",
       "  .tooltip {\n",
       "    background: #f5f5f5;\n",
       "\n",
       "    padding: 10px 10px;\n",
       "    font-family: \"Open Sans\", sans-serif;\n",
       "    box-sizing: border-box;\n",
       "    font-size: 0.8em;\n",
       "    position: absolute;\n",
       "    top: 1em;\n",
       "    left: 1em;\n",
       "    opacity: 0;\n",
       "    transition: opacity 0.3s ease;\n",
       "    pointer-events: none;\n",
       "    border: 2px solid #ddd;\n",
       "  }\n",
       "  .tooltip:after {\n",
       "    content: \" \";\n",
       "    position: absolute;\n",
       "    top: calc(50% - 6px);\n",
       "    left: -12px;\n",
       "    width: 0;\n",
       "    height: 0;\n",
       "    border-style: solid;\n",
       "    border-width: 6px 12px 6px 0;\n",
       "    border-color: transparent #f5f5f5 transparent transparent;\n",
       "  }\n",
       "  .tooltip:before {\n",
       "    content: \" \";\n",
       "    position: absolute;\n",
       "    top: calc(50% - 8px);\n",
       "    left: -16px;\n",
       "    width: 0;\n",
       "    height: 0;\n",
       "    border-style: solid;\n",
       "    border-width: 8px 16px 8px 0;\n",
       "    border-color: transparent #ddd transparent transparent;\n",
       "  }\n",
       "  .tooltip-table td {\n",
       "    padding: 0em 0.5em;\n",
       "  }\n",
       "  .tooltip-table tr td:first-child {\n",
       "    font-weight: bold;\n",
       "  }\n",
       "  .tooltip-table tr td:last-child {\n",
       "    text-align: left;\n",
       "  }\n",
       "\n",
       "  .d3-graph-wrapper {\n",
       "    width: 960px;\n",
       "    display: flex;\n",
       "    flex-direction: row;\n",
       "    border: 2px solid #ddd;\n",
       "    position: relative;\n",
       "  }\n",
       "</style>\n",
       "<div class=\"d3-graph-wrapper\">\n",
       "  <svg id=\"svg-chart\" width=\"960px\" height=\"600\"></svg>\n",
       "  <div id=\"tooltip\" class=\"tooltip\">\n",
       "    <table class=\"tooltip-table\"></table>\n",
       "  </div>\n",
       "</div>\n",
       "<!-- Note d3 is loaded via require.js -->\n",
       "<script src=\"https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.6/require.min.js\"></script>\n",
       "<!-- <script>\n",
       "  // This bit is a bit of a pain.\n",
       "  // I wanted a way to run this both directly in the browser (for developing),\n",
       "  // and in Jupyter.\n",
       "  // When developing, I needed some 'dummy data' to populate the graph.\n",
       "  // The following script tag attempts to load the file 'dummyData.js' (which\n",
       "  // contains the dummy data). It will fail when running on jupyter.\n",
       "  //\n",
       "  // Whether or not the dummyData file loads (and dummyData is not null) determines\n",
       "  // whether the CHART_SELECTOR (the id of the svg chart) will be fixed or\n",
       "  // dynamic based on template injection, and also whether the nodes and links are from\n",
       "  // the dummyData or dynamic via template injection.\n",
       "  dummyData = null;\n",
       "  console.log(\n",
       "    \"Attempting to load dummy data. This will fail if running via \" +\n",
       "      \"jupyter notebook, and may throw console errors - this is OK.\"\n",
       "  );\n",
       "</script>\n",
       "<script src=\"dummyData.js\"></script> -->\n",
       "<script>\n",
       "  require.config({\n",
       "    paths: {\n",
       "      d3: \"https://d3js.org/d3.v7.min\",\n",
       "    },\n",
       "  });\n",
       "\n",
       "  // Everything is wrapped in this require.js function - this way the variables don't\n",
       "  // go into the global scope and everything works even when multiple graphs are\n",
       "  // rendered.\n",
       "  require([\"d3\"], function (d3) {\n",
       "    dummyData = null;\n",
       "\n",
       "    console.log(\"Initialising GQVis...\")\n",
       "    const CHART_SELECTOR = dummyData ? \"#chart\" : \"#chart-506929\";\n",
       "    const TOOLTIP_SELECTOR = dummyData ? \"#tooltip\" : \"#tooltip-506929\";\n",
       "    const svg_chart = document.getElementById(\"svg-chart\");\n",
       "    const tooltip = document.getElementById(\"tooltip\");\n",
       "\n",
       "    // Maintain the svg element the tooltip is currently bound to.\n",
       "    let tooltipNode = null;\n",
       "    const tooltipTable = tooltip.querySelector(\".tooltip-table\");\n",
       "\n",
       "    // Maintain the currently selected node, if any, as well as all nodes/links\n",
       "    // related to it.\n",
       "    // When not null, it will have the following:\n",
       "    // {\n",
       "    //  baseNodeId: (the index of the base node being selected),\n",
       "    //  connectedNodeIds: (an array of all connected node ids),\n",
       "    //  connectedLinkIds: (an array of all connected link ids),\n",
       "    // };\n",
       "    let selectedNode = null;\n",
       "\n",
       "\n",
       "\n",
       "    // Dynamically set the id of the svg and tooltip.\n",
       "    // If in development mode (i.e. dummyData is not null), the id will just be\n",
       "    // \"#chart\" or \"#tooltip\" respectively.\n",
       "    svg_chart.id = CHART_SELECTOR.substring(1, CHART_SELECTOR.length);\n",
       "\n",
       "    console.log(\"SVG Chart ID: \" + svg_chart.id)\n",
       "    tooltip.id = TOOLTIP_SELECTOR.substring(1, TOOLTIP_SELECTOR.length);\n",
       "    let data = {};\n",
       "    if (dummyData) {\n",
       "      data = dummyData;\n",
       "    } else {\n",
       "      data = {\n",
       "        nodes: JSON.parse(\"[{'id': 1415, 'category': 'Item', 'name': 'engine', '_id': 'engine__Item'}, {'id': 1459, 'category': 'Activity', 'name': 'repair', '_id': 'repair__Activity'}, {'id': 2459, 'category': 'Activity', 'name': 'tighten front', '_id': 'tighten front__Activity'}]\".replace(/'/g, '\"')),\n",
       "        links: JSON.parse(\"[{'source': 1415, 'target': 1459, 'type': 'HAS_ACTIVITY'}, {'source': 1415, 'target': 2459, 'type': 'HAS_ACTIVITY'}]\".replace(/'/g, '\"')),\n",
       "      };\n",
       "    }\n",
       "\n",
       "    if(data.nodes.length == 0) {\n",
       "      svg_chart.parentElement.innerHTML = \"No results to display.\";\n",
       "    }\n",
       "\n",
       "    /* Code found in a range of places, spliced together from the following:\n",
       "    https://observablehq.com/@brunolaranjeira/d3-v6-force-directed-graph-with-directional-straight-arrow\n",
       "    https://bl.ocks.org/mbostock/4062045\n",
       "    https://github.com/nlp-tlp/aquila/blob/master/views/visualisations/entity_linking_graph.jade\n",
       "    https://observablehq.com/@harrylove/draw-an-arrowhead-marker-connected-to-a-line-in-d3\n",
       "    */\n",
       "\n",
       "    // https://stackoverflow.com/questions/5560248/programmatically-lighten-or-darken-a-hex-color-or-rgb-and-blend-colors\n",
       "    function lightenDarkenColor(col, amt) {\n",
       "      let usePound = false;\n",
       "      if (col[0] == \"#\") {\n",
       "        col = col.slice(1);\n",
       "        usePound = true;\n",
       "      }\n",
       "\n",
       "      let num = parseInt(col, 16);\n",
       "\n",
       "      let r = (num >> 16) + amt;\n",
       "\n",
       "      if (r > 255) r = 255;\n",
       "      else if (r < 0) r = 0;\n",
       "\n",
       "      let b = ((num >> 8) & 0x00ff) + amt;\n",
       "\n",
       "      if (b > 255) b = 255;\n",
       "      else if (b < 0) b = 0;\n",
       "\n",
       "      let g = (num & 0x0000ff) + amt;\n",
       "\n",
       "      if (g > 255) g = 255;\n",
       "      else if (g < 0) g = 0;\n",
       "\n",
       "      return (usePound ? \"#\" : \"\") + (g | (b << 8) | (r << 16)).toString(16);\n",
       "    }\n",
       "\n",
       "    /**\n",
       "     * Set the tooltip (after hovering over a specific node). The tooltip, which appears\n",
       "     * on the right of the graph, will show the property (key, value) pairs of the\n",
       "     * selected node.\n",
       "     * @param {[type]} d The d3 data point.\n",
       "     * @param {[type]} i The object.\n",
       "     */\n",
       "    function setTooltip(d, i) {\n",
       "      var p = Object.getPrototypeOf(i);\n",
       "      const keys = Object.keys(p);\n",
       "      const vals = keys.map((key) => p[key]);\n",
       "\n",
       "      let table = \"\";\n",
       "      for (var j = 0; j < keys.length; j++) {\n",
       "        table += \"<tr>\";\n",
       "        table += `<td>${keys[j]}:</td>`;\n",
       "        table += `<td>${vals[j]}</td>`;\n",
       "        table += \"</tr>\";\n",
       "      }\n",
       "\n",
       "      tooltipTable.innerHTML = table;\n",
       "      tooltip.style.opacity = \"0.95\";\n",
       "\n",
       "      tooltipNode = d.target;\n",
       "      updateTooltipPosition();\n",
       "\n",
       "      return d;\n",
       "    }\n",
       "\n",
       "    /**\n",
       "     * Update the position (x and y coords) of the tooltip based on the location\n",
       "     * of the element it is bound to.\n",
       "     * @return {[type]} [description]\n",
       "     */\n",
       "    function updateTooltipPosition() {\n",
       "      if (!tooltipNode) return;\n",
       "      const rect = tooltipNode.getBoundingClientRect();\n",
       "      const tooltipRect = tooltip.getBoundingClientRect();\n",
       "      const svgRect = svg_chart.getBoundingClientRect();\n",
       "\n",
       "      tooltip.style.left = `${rect.right + 25 - svgRect.left}px`;\n",
       "      tooltip.style.top = `${\n",
       "        (rect.top + rect.bottom) / 2 - tooltipRect.height / 2 - svgRect.top\n",
       "      }px`;\n",
       "    }\n",
       "\n",
       "    /**\n",
       "     * Clear the tooltip by settings its opacity to 0.\n",
       "     * @return {[type]} [description]\n",
       "     */\n",
       "    function clearTooltip() {\n",
       "      tooltip.style.opacity = \"0\";\n",
       "    }\n",
       "\n",
       "    /**\n",
       "     * Allow the nodes to be moved around when dragged.\n",
       "     * @param  {[type]} simulation [description]\n",
       "     * @return {[type]}            [description]\n",
       "     */\n",
       "    let drag = (simulation) => {\n",
       "      function dragstarted(event) {\n",
       "        if (!event.active) simulation.alphaTarget(0.05).restart();\n",
       "        event.subject.fx = event.subject.x;\n",
       "        event.subject.fy = event.subject.y;\n",
       "      }\n",
       "\n",
       "      function dragged(event) {\n",
       "        event.subject.fx = event.x;\n",
       "        event.subject.fy = event.y;\n",
       "      }\n",
       "\n",
       "      function dragended(event) {\n",
       "        if (!event.active) simulation.alphaTarget(0);\n",
       "        event.subject.fx = null;\n",
       "        event.subject.fy = null;\n",
       "      }\n",
       "\n",
       "      return d3\n",
       "        .drag()\n",
       "        .on(\"start\", dragstarted)\n",
       "        .on(\"drag\", dragged)\n",
       "        .on(\"end\", dragended);\n",
       "    };\n",
       "\n",
       "    const scale = d3.scaleOrdinal(d3.schemeCategory10);\n",
       "\n",
       "    const nodeSize = 40;\n",
       "    let height = 600;\n",
       "    let width = 600;\n",
       "\n",
       "    const links = data.links.map((d) => Object.create(d));\n",
       "    const nodes = data.nodes.map((d) => Object.create(d));\n",
       "\n",
       "    // A list of colours that the colour map will be generated from.\n",
       "    const colours = [\n",
       "      \"#99ffcc\",\n",
       "      \"#ffcccc\",\n",
       "      \"#ccccff\",\n",
       "      \"#ccff99\",\n",
       "      \"#ccffcc\",\n",
       "      \"#ccffff\",\n",
       "      \"#ffcc99\",\n",
       "      \"#ffccff\",\n",
       "      \"#ffff99\",\n",
       "      \"#ffffcc\",\n",
       "      \"#cccc99\",\n",
       "      \"#fbafff\",\n",
       "    ];\n",
       "\n",
       "    /**\n",
       "     * Load the 'colour map' (i.e. mapping of category to colour).\n",
       "     * @param  {Array} nodes The node data.\n",
       "     * @return {Object}       The colour map.\n",
       "     */\n",
       "    function loadColourMap(nodes) {\n",
       "      let colourMap = {};\n",
       "      // Load the colour map\n",
       "      for (let i = 0; i < nodes.length; i++) {\n",
       "        const category = nodes[i].category;\n",
       "        if (!(category in colourMap)) {\n",
       "          colourMap[category] =\n",
       "            colours[Object.keys(colourMap).length % colours.length];\n",
       "        }\n",
       "      }\n",
       "      return colourMap;\n",
       "    }\n",
       "    colourMap = loadColourMap(nodes);\n",
       "    const getColour = (d) => {\n",
       "      return colourMap[d.category];\n",
       "    };\n",
       "\n",
       "    // Initialise some d3 forces etc to make the graph behave properly.\n",
       "    const simulation = d3\n",
       "      .forceSimulation(nodes)\n",
       "      .force(\n",
       "        \"link\",\n",
       "        d3.forceLink(links).id((d) => d.id)\n",
       "      )\n",
       "      // .force(\"charge\", d3.forceManyBody().strength(-200))\n",
       "      .force(\n",
       "        \"collide\",\n",
       "        d3.forceCollide((d) => nodeSize * 1.5)\n",
       "      )\n",
       "      .force(\"center\", d3.forceCenter(width / 2, height / 2));\n",
       "\n",
       "    // Svg: the main container for rendering the graph.\n",
       "    const svg = d3\n",
       "      .select(CHART_SELECTOR)\n",
       "      .attr(\"viewBox\", [0, 0, width, height]);\n",
       "\n",
       "    // svg_g: The 'g' within svg, which seems to make zooming/panning smoother\n",
       "    const svg_g = svg.append(\"g\");\n",
       "    const defs = svg_g.append(\"defs\");\n",
       "\n",
       "    // Marker: a definition for the triangles appearing at the end of each link.\n",
       "    const marker = defs\n",
       "      .selectAll(\"marker\")\n",
       "      .data([\"type_1\"])\n",
       "      .enter()\n",
       "      .append(\"svg:marker\")\n",
       "      .attr(\"id\", function (d, i) {\n",
       "        return `marker_${i}`;\n",
       "      })\n",
       "      .attr(\"viewBox\", \"0 -5 10 10\")\n",
       "      .attr(\"refX\", 10)\n",
       "      .attr(\"refY\", 0)\n",
       "      .attr(\"markerWidth\", 6)\n",
       "      .attr(\"markerHeight\", 6)\n",
       "      .attr(\"orient\", \"auto\")\n",
       "      .append(\"svg:path\")\n",
       "      .attr(\"fill\", \"#444\")\n",
       "      .attr(\"d\", \"M0,-5L10,0L0,5\");\n",
       "\n",
       "    // Link: The links between nodes.\n",
       "    const link = svg_g\n",
       "      .append(\"g\")\n",
       "      .attr(\"id\", \"links\")\n",
       "      .attr(\"fill\", \"none\")\n",
       "      .attr(\"stroke-width\", 1.5)\n",
       "      .selectAll(\"path\")\n",
       "      .data(links)\n",
       "      .enter()\n",
       "      .append(\"path\")\n",
       "      .attr(\"stroke\", \"#444\")\n",
       "      .attr(\"stroke-width\", 2)\n",
       "      .attr(\"marker-end\", function (d, i) {\n",
       "        return `url(\"#marker_0\")`;\n",
       "      })\n",
       "      // 'd' attr is calculated on tick, not here.\n",
       "\n",
       "    /**\n",
       "     * When the mouse is unclicked, clear the selectedNode.\n",
       "     * This will remove the 'hide' class from all nodes in the tick function.\n",
       "     */\n",
       "    function deselectNode() {\n",
       "      selectedNode = null;\n",
       "    }\n",
       "\n",
       "    /**\n",
       "     * When a node is clicked, update selectedNode to reflect the id of that node,\n",
       "     * as well as the id of all nodes and links connected to it.\n",
       "     * @param  {[type]} d [description]\n",
       "     * @param  {[type]} i [description]\n",
       "     * @return {Object}   The selectedNode\n",
       "     *                    (baseNodeId, connectedNodeIds, connectedLinkIds).\n",
       "     */\n",
       "    function selectNode(d, i) {\n",
       "      let connectedNodeIds = new Set();\n",
       "      let connectedLinkIds = new Set();\n",
       "      for (let link of links) {\n",
       "        if (link.source.index === i.index || link.target.index === i.index) {\n",
       "          connectedLinkIds.add(link.index);\n",
       "          if (link.source.index === i.index) {\n",
       "            connectedNodeIds.add(link.target.index);\n",
       "          } else if (link.target.index === i.index) {\n",
       "            connectedNodeIds.add(link.source.index);\n",
       "          }\n",
       "        }\n",
       "      }\n",
       "      selectedNode = {\n",
       "        baseNodeId: i.index,\n",
       "        connectedNodeIds: connectedNodeIds,\n",
       "        connectedLinkIds: connectedLinkIds,\n",
       "      };\n",
       "    }\n",
       "\n",
       "    // Node: The nodes.\n",
       "    const node = svg_g\n",
       "      .append(\"g\")\n",
       "      .attr(\"stroke-width\", 3)\n",
       "      .selectAll(\"circle\")\n",
       "      .data(nodes)\n",
       "      .join(\"circle\")\n",
       "      .attr(\"class\", \"node\")\n",
       "      .attr(\"r\", nodeSize)\n",
       "      .attr(\"fill\", getColour)\n",
       "      .attr(\"stroke\", function (d) {\n",
       "        return lightenDarkenColor(getColour(d), -15);\n",
       "      })\n",
       "      .on(\"mousedown\", selectNode)\n",
       "      .call(drag(simulation));\n",
       "\n",
       "    // When a node is hovered over, set the tooltip accordingly.\n",
       "    // Clear the tooltip when the mouse leaves a node.\n",
       "    d3.selectAll(\".node\").on(\"mouseover\", setTooltip);\n",
       "    d3.selectAll(\".node\").on(\"mouseleave\", clearTooltip);\n",
       "\n",
       "    // When mouse up event (or pointer up event) fires, deselect the\n",
       "    // selected node if there is one.\n",
       "    document.addEventListener(\"mouseup\", deselectNode);\n",
       "    document.addEventListener(\"pointerup\", deselectNode);\n",
       "\n",
       "    // Text: The text appearing on the nodes.\n",
       "    const text = svg_g\n",
       "      .append(\"g\")\n",
       "      .selectAll(\"text\")\n",
       "      .data(nodes)\n",
       "      .enter()\n",
       "      .append(\"text\")\n",
       "      .text((d) => d.name)\n",
       "      .attr(\"font-size\", 12)\n",
       "      .attr(\"text-anchor\", \"middle\")\n",
       "      .attr(\"dominant-baseline\", \"central\");\n",
       "\n",
       "    // Links text: The text appearing on the links.\n",
       "    const link_text = svg_g\n",
       "      .append(\"g\")\n",
       "      .selectAll(\"text\")\n",
       "      .data(links)\n",
       "      .enter()\n",
       "      .append(\"text\")\n",
       "      .text((d) => d.type)\n",
       "      .attr(\"font-size\", 10)\n",
       "      .attr(\"text-anchor\", \"middle\")\n",
       "      .attr(\"dominant-baseline\", \"central\");\n",
       "\n",
       "    // Every time the simulation ticks, update the path of the links,\n",
       "    // the location of the nodes, the location of the text, and also the\n",
       "    // tooltip position.\n",
       "    simulation.on(\"tick\", () => {\n",
       "\n",
       "      // Only draw the links starting from the edge of node 1 to node 2.\n",
       "      // This way, when the nodes go transparent, the links won't be visible underneath\n",
       "      // the nodes (which looks bad).\n",
       "      // Code for doing this was found here:\n",
       "      // https://www.appsloveworld.com/d3js/100/17/\n",
       "      // create-links-from-node-border-to-node-border-not-center-to-center\n",
       "      link.attr(\n",
       "        \"d\",\n",
       "        (d) => {\n",
       "          x1 = d.source.x + (Math.cos(Math.atan2(d.target.y - d.source.y, d.target.x - d.source.x)) * nodeSize);\n",
       "\n",
       "          y1 = d.source.y + (Math.sin(Math.atan2(d.target.y - d.source.y, d.target.x - d.source.x)) * nodeSize);\n",
       "\n",
       "          x2 = d.target.x - (Math.cos(Math.atan2(d.target.y - d.source.y, d.target.x - d.source.x)) * nodeSize);\n",
       "\n",
       "          y2 = d.target.y - (Math.sin(Math.atan2(d.target.y - d.source.y, d.target.x - d.source.x)) * nodeSize);\n",
       "          return `M${x1},${y1}A0,0 0 0,1 ${x2},${y2}`\n",
       "        }\n",
       "      );\n",
       "\n",
       "      node.attr(\"cx\", (d) => d.x).attr(\"cy\", (d) => d.y);\n",
       "      text.attr(\"x\", (d) => Math.floor(d.x)).attr(\"y\", (d) => Math.floor(d.y));\n",
       "      link_text\n",
       "        .attr(\"x\", (d) => (d.source.x + d.target.x) / 2)\n",
       "        .attr(\"y\", (d) => (d.source.y + d.target.y) / 2);\n",
       "      updateTooltipPosition();\n",
       "\n",
       "      // If a node is currently selected, add a class to the nodes that are not\n",
       "      // related to that node.\n",
       "      //\n",
       "\n",
       "      node.classed(\"not-selected\", function (d, i) {\n",
       "        return (\n",
       "          selectedNode &&\n",
       "          selectedNode.baseNodeId !== i &&\n",
       "          !selectedNode.connectedNodeIds.has(i)\n",
       "        );\n",
       "      });\n",
       "\n",
       "      text.classed(\"not-selected\", function (d, i) {\n",
       "        return (\n",
       "          selectedNode &&\n",
       "          selectedNode.baseNodeId !== i &&\n",
       "          !selectedNode.connectedNodeIds.has(i)\n",
       "        );\n",
       "      });\n",
       "\n",
       "      link.classed(\"not-selected\", function (d, i) {\n",
       "        return selectedNode && !selectedNode.connectedLinkIds.has(i);\n",
       "      });\n",
       "\n",
       "      link_text.classed(\"not-selected\", function (d, i) {\n",
       "        return selectedNode && !selectedNode.connectedLinkIds.has(i);\n",
       "      });\n",
       "    });\n",
       "\n",
       "    // Register the zoom handler.\n",
       "    let zoom = d3.zoom().on(\"zoom\", handleZoom);\n",
       "\n",
       "    /**\n",
       "     * A function to handle zooming/panning. Sets a transform on the svg_g container\n",
       "     * according to the zoom/pan level.\n",
       "     * @param  {[type]} e [description]\n",
       "     * @return {[type]}   [description]\n",
       "     */\n",
       "    function handleZoom(e) {\n",
       "      transform = e.transform;\n",
       "      svg_g.attr(\"transform\", e.transform);\n",
       "      text.attr(\"font-size\", 12 / e.transform.k ** 0.7);\n",
       "      link_text.attr(\"font-size\", 10 / e.transform.k ** 0.7);\n",
       "    }\n",
       "\n",
       "    // Initialise the zooming.\n",
       "    function initZoom() {\n",
       "      svg.call(zoom);\n",
       "    }\n",
       "\n",
       "    initZoom();\n",
       "\n",
       "    // If dummyData is present (i.e. dev mode), display a message at the bottom.\n",
       "    if (dummyData) {\n",
       "      let div = document.createElement(\"div\");\n",
       "      div.innerHTML =\n",
       "        \"<h3>Note: currently in development mode using dummy data.</h3>\";\n",
       "      document.body.appendChild(div);\n",
       "    }\n",
       "  });\n",
       "</script>\n",
       "<!-- <script src=\"graphVisualisation.js\"></script> -->\n"
      ],
      "text/plain": [
       "<IPython.core.display.HTML object>"
      ]
     },
     "execution_count": 51,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "import gqvis\n",
    "\n",
    "gqvis.visualise_cypher(\"\"\"\n",
    "MATCH (e:Entity {name: \"engine\"})-[r:HAS_ACTIVITY]->(a:Activity)\n",
    "RETURN e, r, a\n",
    "\"\"\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now let's try __all failure modes observed on engines__:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 52,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<!DOCTYPE html>\n",
       "<meta charset=\"utf-8\" />\n",
       "<link\n",
       "  href=\"https://fonts.googleapis.com/css2?family=Open+Sans&display=swap\"\n",
       "  rel=\"stylesheet\"\n",
       "/>\n",
       "<style>\n",
       "  circle {\n",
       "    cursor: pointer;\n",
       "\n",
       "  }\n",
       "  .not-selected {\n",
       "    opacity: 0.2;\n",
       "  }\n",
       "  text {\n",
       "    pointer-events: none;\n",
       "    font-family: \"Open Sans\", sans-serif;\n",
       "    font-size: 12;\n",
       "  }\n",
       "\n",
       "  g#links {\n",
       "    opacity: 0.3;\n",
       "  }\n",
       "\n",
       "  .tooltip {\n",
       "    background: #f5f5f5;\n",
       "\n",
       "    padding: 10px 10px;\n",
       "    font-family: \"Open Sans\", sans-serif;\n",
       "    box-sizing: border-box;\n",
       "    font-size: 0.8em;\n",
       "    position: absolute;\n",
       "    top: 1em;\n",
       "    left: 1em;\n",
       "    opacity: 0;\n",
       "    transition: opacity 0.3s ease;\n",
       "    pointer-events: none;\n",
       "    border: 2px solid #ddd;\n",
       "  }\n",
       "  .tooltip:after {\n",
       "    content: \" \";\n",
       "    position: absolute;\n",
       "    top: calc(50% - 6px);\n",
       "    left: -12px;\n",
       "    width: 0;\n",
       "    height: 0;\n",
       "    border-style: solid;\n",
       "    border-width: 6px 12px 6px 0;\n",
       "    border-color: transparent #f5f5f5 transparent transparent;\n",
       "  }\n",
       "  .tooltip:before {\n",
       "    content: \" \";\n",
       "    position: absolute;\n",
       "    top: calc(50% - 8px);\n",
       "    left: -16px;\n",
       "    width: 0;\n",
       "    height: 0;\n",
       "    border-style: solid;\n",
       "    border-width: 8px 16px 8px 0;\n",
       "    border-color: transparent #ddd transparent transparent;\n",
       "  }\n",
       "  .tooltip-table td {\n",
       "    padding: 0em 0.5em;\n",
       "  }\n",
       "  .tooltip-table tr td:first-child {\n",
       "    font-weight: bold;\n",
       "  }\n",
       "  .tooltip-table tr td:last-child {\n",
       "    text-align: left;\n",
       "  }\n",
       "\n",
       "  .d3-graph-wrapper {\n",
       "    width: 960px;\n",
       "    display: flex;\n",
       "    flex-direction: row;\n",
       "    border: 2px solid #ddd;\n",
       "    position: relative;\n",
       "  }\n",
       "</style>\n",
       "<div class=\"d3-graph-wrapper\">\n",
       "  <svg id=\"svg-chart\" width=\"960px\" height=\"600\"></svg>\n",
       "  <div id=\"tooltip\" class=\"tooltip\">\n",
       "    <table class=\"tooltip-table\"></table>\n",
       "  </div>\n",
       "</div>\n",
       "<!-- Note d3 is loaded via require.js -->\n",
       "<script src=\"https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.6/require.min.js\"></script>\n",
       "<!-- <script>\n",
       "  // This bit is a bit of a pain.\n",
       "  // I wanted a way to run this both directly in the browser (for developing),\n",
       "  // and in Jupyter.\n",
       "  // When developing, I needed some 'dummy data' to populate the graph.\n",
       "  // The following script tag attempts to load the file 'dummyData.js' (which\n",
       "  // contains the dummy data). It will fail when running on jupyter.\n",
       "  //\n",
       "  // Whether or not the dummyData file loads (and dummyData is not null) determines\n",
       "  // whether the CHART_SELECTOR (the id of the svg chart) will be fixed or\n",
       "  // dynamic based on template injection, and also whether the nodes and links are from\n",
       "  // the dummyData or dynamic via template injection.\n",
       "  dummyData = null;\n",
       "  console.log(\n",
       "    \"Attempting to load dummy data. This will fail if running via \" +\n",
       "      \"jupyter notebook, and may throw console errors - this is OK.\"\n",
       "  );\n",
       "</script>\n",
       "<script src=\"dummyData.js\"></script> -->\n",
       "<script>\n",
       "  require.config({\n",
       "    paths: {\n",
       "      d3: \"https://d3js.org/d3.v7.min\",\n",
       "    },\n",
       "  });\n",
       "\n",
       "  // Everything is wrapped in this require.js function - this way the variables don't\n",
       "  // go into the global scope and everything works even when multiple graphs are\n",
       "  // rendered.\n",
       "  require([\"d3\"], function (d3) {\n",
       "    dummyData = null;\n",
       "\n",
       "    console.log(\"Initialising GQVis...\")\n",
       "    const CHART_SELECTOR = dummyData ? \"#chart\" : \"#chart-311788\";\n",
       "    const TOOLTIP_SELECTOR = dummyData ? \"#tooltip\" : \"#tooltip-311788\";\n",
       "    const svg_chart = document.getElementById(\"svg-chart\");\n",
       "    const tooltip = document.getElementById(\"tooltip\");\n",
       "\n",
       "    // Maintain the svg element the tooltip is currently bound to.\n",
       "    let tooltipNode = null;\n",
       "    const tooltipTable = tooltip.querySelector(\".tooltip-table\");\n",
       "\n",
       "    // Maintain the currently selected node, if any, as well as all nodes/links\n",
       "    // related to it.\n",
       "    // When not null, it will have the following:\n",
       "    // {\n",
       "    //  baseNodeId: (the index of the base node being selected),\n",
       "    //  connectedNodeIds: (an array of all connected node ids),\n",
       "    //  connectedLinkIds: (an array of all connected link ids),\n",
       "    // };\n",
       "    let selectedNode = null;\n",
       "\n",
       "\n",
       "\n",
       "    // Dynamically set the id of the svg and tooltip.\n",
       "    // If in development mode (i.e. dummyData is not null), the id will just be\n",
       "    // \"#chart\" or \"#tooltip\" respectively.\n",
       "    svg_chart.id = CHART_SELECTOR.substring(1, CHART_SELECTOR.length);\n",
       "\n",
       "    console.log(\"SVG Chart ID: \" + svg_chart.id)\n",
       "    tooltip.id = TOOLTIP_SELECTOR.substring(1, TOOLTIP_SELECTOR.length);\n",
       "    let data = {};\n",
       "    if (dummyData) {\n",
       "      data = dummyData;\n",
       "    } else {\n",
       "      data = {\n",
       "        nodes: JSON.parse(\"[{'id': 1415, 'category': 'Item', 'name': 'engine', '_id': 'engine__Item'}, {'id': 1402, 'category': 'Observation', 'name': 'breakdown', '_id': 'breakdown__Observation'}, {'id': 1640, 'category': 'Observation', 'name': 'failure', '_id': 'failure__Observation'}, {'id': 1879, 'category': 'Observation', 'name': 'loose', '_id': 'loose__Observation'}]\".replace(/'/g, '\"')),\n",
       "        links: JSON.parse(\"[{'source': 1415, 'target': 1402, 'type': 'HAS_OBSERVATION'}, {'source': 1415, 'target': 1640, 'type': 'HAS_OBSERVATION'}, {'source': 1415, 'target': 1879, 'type': 'HAS_OBSERVATION'}]\".replace(/'/g, '\"')),\n",
       "      };\n",
       "    }\n",
       "\n",
       "    if(data.nodes.length == 0) {\n",
       "      svg_chart.parentElement.innerHTML = \"No results to display.\";\n",
       "    }\n",
       "\n",
       "    /* Code found in a range of places, spliced together from the following:\n",
       "    https://observablehq.com/@brunolaranjeira/d3-v6-force-directed-graph-with-directional-straight-arrow\n",
       "    https://bl.ocks.org/mbostock/4062045\n",
       "    https://github.com/nlp-tlp/aquila/blob/master/views/visualisations/entity_linking_graph.jade\n",
       "    https://observablehq.com/@harrylove/draw-an-arrowhead-marker-connected-to-a-line-in-d3\n",
       "    */\n",
       "\n",
       "    // https://stackoverflow.com/questions/5560248/programmatically-lighten-or-darken-a-hex-color-or-rgb-and-blend-colors\n",
       "    function lightenDarkenColor(col, amt) {\n",
       "      let usePound = false;\n",
       "      if (col[0] == \"#\") {\n",
       "        col = col.slice(1);\n",
       "        usePound = true;\n",
       "      }\n",
       "\n",
       "      let num = parseInt(col, 16);\n",
       "\n",
       "      let r = (num >> 16) + amt;\n",
       "\n",
       "      if (r > 255) r = 255;\n",
       "      else if (r < 0) r = 0;\n",
       "\n",
       "      let b = ((num >> 8) & 0x00ff) + amt;\n",
       "\n",
       "      if (b > 255) b = 255;\n",
       "      else if (b < 0) b = 0;\n",
       "\n",
       "      let g = (num & 0x0000ff) + amt;\n",
       "\n",
       "      if (g > 255) g = 255;\n",
       "      else if (g < 0) g = 0;\n",
       "\n",
       "      return (usePound ? \"#\" : \"\") + (g | (b << 8) | (r << 16)).toString(16);\n",
       "    }\n",
       "\n",
       "    /**\n",
       "     * Set the tooltip (after hovering over a specific node). The tooltip, which appears\n",
       "     * on the right of the graph, will show the property (key, value) pairs of the\n",
       "     * selected node.\n",
       "     * @param {[type]} d The d3 data point.\n",
       "     * @param {[type]} i The object.\n",
       "     */\n",
       "    function setTooltip(d, i) {\n",
       "      var p = Object.getPrototypeOf(i);\n",
       "      const keys = Object.keys(p);\n",
       "      const vals = keys.map((key) => p[key]);\n",
       "\n",
       "      let table = \"\";\n",
       "      for (var j = 0; j < keys.length; j++) {\n",
       "        table += \"<tr>\";\n",
       "        table += `<td>${keys[j]}:</td>`;\n",
       "        table += `<td>${vals[j]}</td>`;\n",
       "        table += \"</tr>\";\n",
       "      }\n",
       "\n",
       "      tooltipTable.innerHTML = table;\n",
       "      tooltip.style.opacity = \"0.95\";\n",
       "\n",
       "      tooltipNode = d.target;\n",
       "      updateTooltipPosition();\n",
       "\n",
       "      return d;\n",
       "    }\n",
       "\n",
       "    /**\n",
       "     * Update the position (x and y coords) of the tooltip based on the location\n",
       "     * of the element it is bound to.\n",
       "     * @return {[type]} [description]\n",
       "     */\n",
       "    function updateTooltipPosition() {\n",
       "      if (!tooltipNode) return;\n",
       "      const rect = tooltipNode.getBoundingClientRect();\n",
       "      const tooltipRect = tooltip.getBoundingClientRect();\n",
       "      const svgRect = svg_chart.getBoundingClientRect();\n",
       "\n",
       "      tooltip.style.left = `${rect.right + 25 - svgRect.left}px`;\n",
       "      tooltip.style.top = `${\n",
       "        (rect.top + rect.bottom) / 2 - tooltipRect.height / 2 - svgRect.top\n",
       "      }px`;\n",
       "    }\n",
       "\n",
       "    /**\n",
       "     * Clear the tooltip by settings its opacity to 0.\n",
       "     * @return {[type]} [description]\n",
       "     */\n",
       "    function clearTooltip() {\n",
       "      tooltip.style.opacity = \"0\";\n",
       "    }\n",
       "\n",
       "    /**\n",
       "     * Allow the nodes to be moved around when dragged.\n",
       "     * @param  {[type]} simulation [description]\n",
       "     * @return {[type]}            [description]\n",
       "     */\n",
       "    let drag = (simulation) => {\n",
       "      function dragstarted(event) {\n",
       "        if (!event.active) simulation.alphaTarget(0.05).restart();\n",
       "        event.subject.fx = event.subject.x;\n",
       "        event.subject.fy = event.subject.y;\n",
       "      }\n",
       "\n",
       "      function dragged(event) {\n",
       "        event.subject.fx = event.x;\n",
       "        event.subject.fy = event.y;\n",
       "      }\n",
       "\n",
       "      function dragended(event) {\n",
       "        if (!event.active) simulation.alphaTarget(0);\n",
       "        event.subject.fx = null;\n",
       "        event.subject.fy = null;\n",
       "      }\n",
       "\n",
       "      return d3\n",
       "        .drag()\n",
       "        .on(\"start\", dragstarted)\n",
       "        .on(\"drag\", dragged)\n",
       "        .on(\"end\", dragended);\n",
       "    };\n",
       "\n",
       "    const scale = d3.scaleOrdinal(d3.schemeCategory10);\n",
       "\n",
       "    const nodeSize = 40;\n",
       "    let height = 600;\n",
       "    let width = 600;\n",
       "\n",
       "    const links = data.links.map((d) => Object.create(d));\n",
       "    const nodes = data.nodes.map((d) => Object.create(d));\n",
       "\n",
       "    // A list of colours that the colour map will be generated from.\n",
       "    const colours = [\n",
       "      \"#99ffcc\",\n",
       "      \"#ffcccc\",\n",
       "      \"#ccccff\",\n",
       "      \"#ccff99\",\n",
       "      \"#ccffcc\",\n",
       "      \"#ccffff\",\n",
       "      \"#ffcc99\",\n",
       "      \"#ffccff\",\n",
       "      \"#ffff99\",\n",
       "      \"#ffffcc\",\n",
       "      \"#cccc99\",\n",
       "      \"#fbafff\",\n",
       "    ];\n",
       "\n",
       "    /**\n",
       "     * Load the 'colour map' (i.e. mapping of category to colour).\n",
       "     * @param  {Array} nodes The node data.\n",
       "     * @return {Object}       The colour map.\n",
       "     */\n",
       "    function loadColourMap(nodes) {\n",
       "      let colourMap = {};\n",
       "      // Load the colour map\n",
       "      for (let i = 0; i < nodes.length; i++) {\n",
       "        const category = nodes[i].category;\n",
       "        if (!(category in colourMap)) {\n",
       "          colourMap[category] =\n",
       "            colours[Object.keys(colourMap).length % colours.length];\n",
       "        }\n",
       "      }\n",
       "      return colourMap;\n",
       "    }\n",
       "    colourMap = loadColourMap(nodes);\n",
       "    const getColour = (d) => {\n",
       "      return colourMap[d.category];\n",
       "    };\n",
       "\n",
       "    // Initialise some d3 forces etc to make the graph behave properly.\n",
       "    const simulation = d3\n",
       "      .forceSimulation(nodes)\n",
       "      .force(\n",
       "        \"link\",\n",
       "        d3.forceLink(links).id((d) => d.id)\n",
       "      )\n",
       "      // .force(\"charge\", d3.forceManyBody().strength(-200))\n",
       "      .force(\n",
       "        \"collide\",\n",
       "        d3.forceCollide((d) => nodeSize * 1.5)\n",
       "      )\n",
       "      .force(\"center\", d3.forceCenter(width / 2, height / 2));\n",
       "\n",
       "    // Svg: the main container for rendering the graph.\n",
       "    const svg = d3\n",
       "      .select(CHART_SELECTOR)\n",
       "      .attr(\"viewBox\", [0, 0, width, height]);\n",
       "\n",
       "    // svg_g: The 'g' within svg, which seems to make zooming/panning smoother\n",
       "    const svg_g = svg.append(\"g\");\n",
       "    const defs = svg_g.append(\"defs\");\n",
       "\n",
       "    // Marker: a definition for the triangles appearing at the end of each link.\n",
       "    const marker = defs\n",
       "      .selectAll(\"marker\")\n",
       "      .data([\"type_1\"])\n",
       "      .enter()\n",
       "      .append(\"svg:marker\")\n",
       "      .attr(\"id\", function (d, i) {\n",
       "        return `marker_${i}`;\n",
       "      })\n",
       "      .attr(\"viewBox\", \"0 -5 10 10\")\n",
       "      .attr(\"refX\", 10)\n",
       "      .attr(\"refY\", 0)\n",
       "      .attr(\"markerWidth\", 6)\n",
       "      .attr(\"markerHeight\", 6)\n",
       "      .attr(\"orient\", \"auto\")\n",
       "      .append(\"svg:path\")\n",
       "      .attr(\"fill\", \"#444\")\n",
       "      .attr(\"d\", \"M0,-5L10,0L0,5\");\n",
       "\n",
       "    // Link: The links between nodes.\n",
       "    const link = svg_g\n",
       "      .append(\"g\")\n",
       "      .attr(\"id\", \"links\")\n",
       "      .attr(\"fill\", \"none\")\n",
       "      .attr(\"stroke-width\", 1.5)\n",
       "      .selectAll(\"path\")\n",
       "      .data(links)\n",
       "      .enter()\n",
       "      .append(\"path\")\n",
       "      .attr(\"stroke\", \"#444\")\n",
       "      .attr(\"stroke-width\", 2)\n",
       "      .attr(\"marker-end\", function (d, i) {\n",
       "        return `url(\"#marker_0\")`;\n",
       "      })\n",
       "      // 'd' attr is calculated on tick, not here.\n",
       "\n",
       "    /**\n",
       "     * When the mouse is unclicked, clear the selectedNode.\n",
       "     * This will remove the 'hide' class from all nodes in the tick function.\n",
       "     */\n",
       "    function deselectNode() {\n",
       "      selectedNode = null;\n",
       "    }\n",
       "\n",
       "    /**\n",
       "     * When a node is clicked, update selectedNode to reflect the id of that node,\n",
       "     * as well as the id of all nodes and links connected to it.\n",
       "     * @param  {[type]} d [description]\n",
       "     * @param  {[type]} i [description]\n",
       "     * @return {Object}   The selectedNode\n",
       "     *                    (baseNodeId, connectedNodeIds, connectedLinkIds).\n",
       "     */\n",
       "    function selectNode(d, i) {\n",
       "      let connectedNodeIds = new Set();\n",
       "      let connectedLinkIds = new Set();\n",
       "      for (let link of links) {\n",
       "        if (link.source.index === i.index || link.target.index === i.index) {\n",
       "          connectedLinkIds.add(link.index);\n",
       "          if (link.source.index === i.index) {\n",
       "            connectedNodeIds.add(link.target.index);\n",
       "          } else if (link.target.index === i.index) {\n",
       "            connectedNodeIds.add(link.source.index);\n",
       "          }\n",
       "        }\n",
       "      }\n",
       "      selectedNode = {\n",
       "        baseNodeId: i.index,\n",
       "        connectedNodeIds: connectedNodeIds,\n",
       "        connectedLinkIds: connectedLinkIds,\n",
       "      };\n",
       "    }\n",
       "\n",
       "    // Node: The nodes.\n",
       "    const node = svg_g\n",
       "      .append(\"g\")\n",
       "      .attr(\"stroke-width\", 3)\n",
       "      .selectAll(\"circle\")\n",
       "      .data(nodes)\n",
       "      .join(\"circle\")\n",
       "      .attr(\"class\", \"node\")\n",
       "      .attr(\"r\", nodeSize)\n",
       "      .attr(\"fill\", getColour)\n",
       "      .attr(\"stroke\", function (d) {\n",
       "        return lightenDarkenColor(getColour(d), -15);\n",
       "      })\n",
       "      .on(\"mousedown\", selectNode)\n",
       "      .call(drag(simulation));\n",
       "\n",
       "    // When a node is hovered over, set the tooltip accordingly.\n",
       "    // Clear the tooltip when the mouse leaves a node.\n",
       "    d3.selectAll(\".node\").on(\"mouseover\", setTooltip);\n",
       "    d3.selectAll(\".node\").on(\"mouseleave\", clearTooltip);\n",
       "\n",
       "    // When mouse up event (or pointer up event) fires, deselect the\n",
       "    // selected node if there is one.\n",
       "    document.addEventListener(\"mouseup\", deselectNode);\n",
       "    document.addEventListener(\"pointerup\", deselectNode);\n",
       "\n",
       "    // Text: The text appearing on the nodes.\n",
       "    const text = svg_g\n",
       "      .append(\"g\")\n",
       "      .selectAll(\"text\")\n",
       "      .data(nodes)\n",
       "      .enter()\n",
       "      .append(\"text\")\n",
       "      .text((d) => d.name)\n",
       "      .attr(\"font-size\", 12)\n",
       "      .attr(\"text-anchor\", \"middle\")\n",
       "      .attr(\"dominant-baseline\", \"central\");\n",
       "\n",
       "    // Links text: The text appearing on the links.\n",
       "    const link_text = svg_g\n",
       "      .append(\"g\")\n",
       "      .selectAll(\"text\")\n",
       "      .data(links)\n",
       "      .enter()\n",
       "      .append(\"text\")\n",
       "      .text((d) => d.type)\n",
       "      .attr(\"font-size\", 10)\n",
       "      .attr(\"text-anchor\", \"middle\")\n",
       "      .attr(\"dominant-baseline\", \"central\");\n",
       "\n",
       "    // Every time the simulation ticks, update the path of the links,\n",
       "    // the location of the nodes, the location of the text, and also the\n",
       "    // tooltip position.\n",
       "    simulation.on(\"tick\", () => {\n",
       "\n",
       "      // Only draw the links starting from the edge of node 1 to node 2.\n",
       "      // This way, when the nodes go transparent, the links won't be visible underneath\n",
       "      // the nodes (which looks bad).\n",
       "      // Code for doing this was found here:\n",
       "      // https://www.appsloveworld.com/d3js/100/17/\n",
       "      // create-links-from-node-border-to-node-border-not-center-to-center\n",
       "      link.attr(\n",
       "        \"d\",\n",
       "        (d) => {\n",
       "          x1 = d.source.x + (Math.cos(Math.atan2(d.target.y - d.source.y, d.target.x - d.source.x)) * nodeSize);\n",
       "\n",
       "          y1 = d.source.y + (Math.sin(Math.atan2(d.target.y - d.source.y, d.target.x - d.source.x)) * nodeSize);\n",
       "\n",
       "          x2 = d.target.x - (Math.cos(Math.atan2(d.target.y - d.source.y, d.target.x - d.source.x)) * nodeSize);\n",
       "\n",
       "          y2 = d.target.y - (Math.sin(Math.atan2(d.target.y - d.source.y, d.target.x - d.source.x)) * nodeSize);\n",
       "          return `M${x1},${y1}A0,0 0 0,1 ${x2},${y2}`\n",
       "        }\n",
       "      );\n",
       "\n",
       "      node.attr(\"cx\", (d) => d.x).attr(\"cy\", (d) => d.y);\n",
       "      text.attr(\"x\", (d) => Math.floor(d.x)).attr(\"y\", (d) => Math.floor(d.y));\n",
       "      link_text\n",
       "        .attr(\"x\", (d) => (d.source.x + d.target.x) / 2)\n",
       "        .attr(\"y\", (d) => (d.source.y + d.target.y) / 2);\n",
       "      updateTooltipPosition();\n",
       "\n",
       "      // If a node is currently selected, add a class to the nodes that are not\n",
       "      // related to that node.\n",
       "      //\n",
       "\n",
       "      node.classed(\"not-selected\", function (d, i) {\n",
       "        return (\n",
       "          selectedNode &&\n",
       "          selectedNode.baseNodeId !== i &&\n",
       "          !selectedNode.connectedNodeIds.has(i)\n",
       "        );\n",
       "      });\n",
       "\n",
       "      text.classed(\"not-selected\", function (d, i) {\n",
       "        return (\n",
       "          selectedNode &&\n",
       "          selectedNode.baseNodeId !== i &&\n",
       "          !selectedNode.connectedNodeIds.has(i)\n",
       "        );\n",
       "      });\n",
       "\n",
       "      link.classed(\"not-selected\", function (d, i) {\n",
       "        return selectedNode && !selectedNode.connectedLinkIds.has(i);\n",
       "      });\n",
       "\n",
       "      link_text.classed(\"not-selected\", function (d, i) {\n",
       "        return selectedNode && !selectedNode.connectedLinkIds.has(i);\n",
       "      });\n",
       "    });\n",
       "\n",
       "    // Register the zoom handler.\n",
       "    let zoom = d3.zoom().on(\"zoom\", handleZoom);\n",
       "\n",
       "    /**\n",
       "     * A function to handle zooming/panning. Sets a transform on the svg_g container\n",
       "     * according to the zoom/pan level.\n",
       "     * @param  {[type]} e [description]\n",
       "     * @return {[type]}   [description]\n",
       "     */\n",
       "    function handleZoom(e) {\n",
       "      transform = e.transform;\n",
       "      svg_g.attr(\"transform\", e.transform);\n",
       "      text.attr(\"font-size\", 12 / e.transform.k ** 0.7);\n",
       "      link_text.attr(\"font-size\", 10 / e.transform.k ** 0.7);\n",
       "    }\n",
       "\n",
       "    // Initialise the zooming.\n",
       "    function initZoom() {\n",
       "      svg.call(zoom);\n",
       "    }\n",
       "\n",
       "    initZoom();\n",
       "\n",
       "    // If dummyData is present (i.e. dev mode), display a message at the bottom.\n",
       "    if (dummyData) {\n",
       "      let div = document.createElement(\"div\");\n",
       "      div.innerHTML =\n",
       "        \"<h3>Note: currently in development mode using dummy data.</h3>\";\n",
       "      document.body.appendChild(div);\n",
       "    }\n",
       "  });\n",
       "</script>\n",
       "<!-- <script src=\"graphVisualisation.js\"></script> -->\n"
      ],
      "text/plain": [
       "<IPython.core.display.HTML object>"
      ]
     },
     "execution_count": 52,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "gqvis.visualise_cypher(\"\"\"\n",
    "MATCH (e:Entity {name: \"engine\"})-[r:HAS_OBSERVATION]->(o:Observation)\n",
    "RETURN e, r, o\n",
    "\"\"\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n",
    "We can also use our graph as a way to quickly search and access work orders for the entities appearing in those work orders. For example, searching for __all work orders containing a leak__:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 45,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<!DOCTYPE html>\n",
       "<meta charset=\"utf-8\" />\n",
       "<link\n",
       "  href=\"https://fonts.googleapis.com/css2?family=Open+Sans&display=swap\"\n",
       "  rel=\"stylesheet\"\n",
       "/>\n",
       "<style>\n",
       "  circle {\n",
       "    cursor: pointer;\n",
       "\n",
       "  }\n",
       "  .not-selected {\n",
       "    opacity: 0.2;\n",
       "  }\n",
       "  text {\n",
       "    pointer-events: none;\n",
       "    font-family: \"Open Sans\", sans-serif;\n",
       "    font-size: 12;\n",
       "  }\n",
       "\n",
       "  g#links {\n",
       "    opacity: 0.3;\n",
       "  }\n",
       "\n",
       "  .tooltip {\n",
       "    background: #f5f5f5;\n",
       "\n",
       "    padding: 10px 10px;\n",
       "    font-family: \"Open Sans\", sans-serif;\n",
       "    box-sizing: border-box;\n",
       "    font-size: 0.8em;\n",
       "    position: absolute;\n",
       "    top: 1em;\n",
       "    left: 1em;\n",
       "    opacity: 0;\n",
       "    transition: opacity 0.3s ease;\n",
       "    pointer-events: none;\n",
       "    border: 2px solid #ddd;\n",
       "  }\n",
       "  .tooltip:after {\n",
       "    content: \" \";\n",
       "    position: absolute;\n",
       "    top: calc(50% - 6px);\n",
       "    left: -12px;\n",
       "    width: 0;\n",
       "    height: 0;\n",
       "    border-style: solid;\n",
       "    border-width: 6px 12px 6px 0;\n",
       "    border-color: transparent #f5f5f5 transparent transparent;\n",
       "  }\n",
       "  .tooltip:before {\n",
       "    content: \" \";\n",
       "    position: absolute;\n",
       "    top: calc(50% - 8px);\n",
       "    left: -16px;\n",
       "    width: 0;\n",
       "    height: 0;\n",
       "    border-style: solid;\n",
       "    border-width: 8px 16px 8px 0;\n",
       "    border-color: transparent #ddd transparent transparent;\n",
       "  }\n",
       "  .tooltip-table td {\n",
       "    padding: 0em 0.5em;\n",
       "  }\n",
       "  .tooltip-table tr td:first-child {\n",
       "    font-weight: bold;\n",
       "  }\n",
       "  .tooltip-table tr td:last-child {\n",
       "    text-align: left;\n",
       "  }\n",
       "\n",
       "  .d3-graph-wrapper {\n",
       "    width: 960px;\n",
       "    display: flex;\n",
       "    flex-direction: row;\n",
       "    border: 2px solid #ddd;\n",
       "    position: relative;\n",
       "  }\n",
       "</style>\n",
       "<div class=\"d3-graph-wrapper\">\n",
       "  <svg id=\"svg-chart\" width=\"960px\" height=\"600\"></svg>\n",
       "  <div id=\"tooltip\" class=\"tooltip\">\n",
       "    <table class=\"tooltip-table\"></table>\n",
       "  </div>\n",
       "</div>\n",
       "<!-- Note d3 is loaded via require.js -->\n",
       "<script src=\"https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.6/require.min.js\"></script>\n",
       "<!-- <script>\n",
       "  // This bit is a bit of a pain.\n",
       "  // I wanted a way to run this both directly in the browser (for developing),\n",
       "  // and in Jupyter.\n",
       "  // When developing, I needed some 'dummy data' to populate the graph.\n",
       "  // The following script tag attempts to load the file 'dummyData.js' (which\n",
       "  // contains the dummy data). It will fail when running on jupyter.\n",
       "  //\n",
       "  // Whether or not the dummyData file loads (and dummyData is not null) determines\n",
       "  // whether the CHART_SELECTOR (the id of the svg chart) will be fixed or\n",
       "  // dynamic based on template injection, and also whether the nodes and links are from\n",
       "  // the dummyData or dynamic via template injection.\n",
       "  dummyData = null;\n",
       "  console.log(\n",
       "    \"Attempting to load dummy data. This will fail if running via \" +\n",
       "      \"jupyter notebook, and may throw console errors - this is OK.\"\n",
       "  );\n",
       "</script>\n",
       "<script src=\"dummyData.js\"></script> -->\n",
       "<script>\n",
       "  require.config({\n",
       "    paths: {\n",
       "      d3: \"https://d3js.org/d3.v7.min\",\n",
       "    },\n",
       "  });\n",
       "\n",
       "  // Everything is wrapped in this require.js function - this way the variables don't\n",
       "  // go into the global scope and everything works even when multiple graphs are\n",
       "  // rendered.\n",
       "  require([\"d3\"], function (d3) {\n",
       "    dummyData = null;\n",
       "\n",
       "    console.log(\"Initialising GQVis...\")\n",
       "    const CHART_SELECTOR = dummyData ? \"#chart\" : \"#chart-790557\";\n",
       "    const TOOLTIP_SELECTOR = dummyData ? \"#tooltip\" : \"#tooltip-790557\";\n",
       "    const svg_chart = document.getElementById(\"svg-chart\");\n",
       "    const tooltip = document.getElementById(\"tooltip\");\n",
       "\n",
       "    // Maintain the svg element the tooltip is currently bound to.\n",
       "    let tooltipNode = null;\n",
       "    const tooltipTable = tooltip.querySelector(\".tooltip-table\");\n",
       "\n",
       "    // Maintain the currently selected node, if any, as well as all nodes/links\n",
       "    // related to it.\n",
       "    // When not null, it will have the following:\n",
       "    // {\n",
       "    //  baseNodeId: (the index of the base node being selected),\n",
       "    //  connectedNodeIds: (an array of all connected node ids),\n",
       "    //  connectedLinkIds: (an array of all connected link ids),\n",
       "    // };\n",
       "    let selectedNode = null;\n",
       "\n",
       "\n",
       "\n",
       "    // Dynamically set the id of the svg and tooltip.\n",
       "    // If in development mode (i.e. dummyData is not null), the id will just be\n",
       "    // \"#chart\" or \"#tooltip\" respectively.\n",
       "    svg_chart.id = CHART_SELECTOR.substring(1, CHART_SELECTOR.length);\n",
       "\n",
       "    console.log(\"SVG Chart ID: \" + svg_chart.id)\n",
       "    tooltip.id = TOOLTIP_SELECTOR.substring(1, TOOLTIP_SELECTOR.length);\n",
       "    let data = {};\n",
       "    if (dummyData) {\n",
       "      data = dummyData;\n",
       "    } else {\n",
       "      data = {\n",
       "        nodes: JSON.parse(\"[{'id': 786, 'category': 'Document', 'name': 'oil leak under oil cooler'}, {'id': 139, 'category': 'Observation', 'name': 'leak', '_id': 'leak__Observation'}, {'id': 424, 'category': 'Document', 'name': 'dust leak into cab'}, {'id': 206, 'category': 'Document', 'name': 'bull hose air leak'}, {'id': 537, 'category': 'Document', 'name': 'grease leak at frame lube pump fittings'}, {'id': 168, 'category': 'Document', 'name': 'both rear jacks leak oil'}, {'id': 796, 'category': 'Document', 'name': 'one filter still leak oil'}, {'id': 678, 'category': 'Document', 'name': 'lhs mast lift cylinder leak'}, {'id': 781, 'category': 'Document', 'name': 'oil leak regen valve'}, {'id': 769, 'category': 'Document', 'name': 'oil leak at bottom of mast'}, {'id': 1202, 'category': 'Document', 'name': 'rotary head seal leak'}, {'id': 771, 'category': 'Document', 'name': 'oil leak at deck wrench'}, {'id': 931, 'category': 'Document', 'name': 'repair leak air conditioner motor'}, {'id': 283, 'category': 'Document', 'name': 'coolant leak around coolant sensor'}, {'id': 783, 'category': 'Document', 'name': 'oil leak under acc. pumps'}, {'id': 772, 'category': 'Document', 'name': 'oil leak at l/h/f chassis'}, {'id': 10, 'category': 'Document', 'name': 'check oil leak at rotary head'}, {'id': 612, 'category': 'Document', 'name': 'input seal leak on front drive box'}, {'id': 1259, 'category': 'Document', 'name': 'tap leak on compressor tank'}, {'id': 767, 'category': 'Document', 'name': 'oil leak around pumps'}, {'id': 548, 'category': 'Document', 'name': 'grease tank leak at pump base'}, {'id': 774, 'category': 'Document', 'name': 'oil leak at l/h/f jack cylinder'}, {'id': 776, 'category': 'Document', 'name': 'oil leak at turbo'}, {'id': 617, 'category': 'Document', 'name': 'inspect hydraulic oil leak on jack leg'}, {'id': 928, 'category': 'Document', 'name': 'repair hydraulic leak up mast'}, {'id': 137, 'category': 'Document', 'name': 'air leak around rotary head'}, {'id': 673, 'category': 'Document', 'name': 'leak l/h fan motor hose'}, {'id': 383, 'category': 'Document', 'name': 'def.tap on potable water inlet leak'}, {'id': 938, 'category': 'Document', 'name': 'repair oil leak on hydraulic return hose'}, {'id': 675, 'category': 'Document', 'name': 'leak cyclinder'}, {'id': 780, 'category': 'Document', 'name': 'oil leak on feed cylinder'}, {'id': 777, 'category': 'Document', 'name': 'oil leak feed pump'}, {'id': 365, 'category': 'Document', 'name': 'def.compressor receiver tap leak'}, {'id': 838, 'category': 'Document', 'name': 'r/h upper loader cyl leak'}, {'id': 1065, 'category': 'Document', 'name': 'replace leak fuel filter'}, {'id': 779, 'category': 'Document', 'name': 'oil leak l/h feed cylinder'}, {'id': 937, 'category': 'Document', 'name': 'repair oil leak on cylinder'}, {'id': 354, 'category': 'Document', 'name': 'def.check engine oil leak'}, {'id': 28, 'category': 'Document', 'name': 'case-drain leak'}]\".replace(/'/g, '\"')),\n",
       "        links: JSON.parse(\"[{'source': 139, 'target': 786, 'type': 'APPEARS_IN'}, {'source': 139, 'target': 424, 'type': 'APPEARS_IN'}, {'source': 139, 'target': 206, 'type': 'APPEARS_IN'}, {'source': 139, 'target': 537, 'type': 'APPEARS_IN'}, {'source': 139, 'target': 168, 'type': 'APPEARS_IN'}, {'source': 139, 'target': 796, 'type': 'APPEARS_IN'}, {'source': 139, 'target': 678, 'type': 'APPEARS_IN'}, {'source': 139, 'target': 781, 'type': 'APPEARS_IN'}, {'source': 139, 'target': 769, 'type': 'APPEARS_IN'}, {'source': 139, 'target': 1202, 'type': 'APPEARS_IN'}, {'source': 139, 'target': 771, 'type': 'APPEARS_IN'}, {'source': 139, 'target': 931, 'type': 'APPEARS_IN'}, {'source': 139, 'target': 283, 'type': 'APPEARS_IN'}, {'source': 139, 'target': 783, 'type': 'APPEARS_IN'}, {'source': 139, 'target': 772, 'type': 'APPEARS_IN'}, {'source': 139, 'target': 10, 'type': 'APPEARS_IN'}, {'source': 139, 'target': 612, 'type': 'APPEARS_IN'}, {'source': 139, 'target': 1259, 'type': 'APPEARS_IN'}, {'source': 139, 'target': 767, 'type': 'APPEARS_IN'}, {'source': 139, 'target': 548, 'type': 'APPEARS_IN'}, {'source': 139, 'target': 774, 'type': 'APPEARS_IN'}, {'source': 139, 'target': 776, 'type': 'APPEARS_IN'}, {'source': 139, 'target': 617, 'type': 'APPEARS_IN'}, {'source': 139, 'target': 928, 'type': 'APPEARS_IN'}, {'source': 139, 'target': 137, 'type': 'APPEARS_IN'}, {'source': 139, 'target': 673, 'type': 'APPEARS_IN'}, {'source': 139, 'target': 383, 'type': 'APPEARS_IN'}, {'source': 139, 'target': 938, 'type': 'APPEARS_IN'}, {'source': 139, 'target': 675, 'type': 'APPEARS_IN'}, {'source': 139, 'target': 780, 'type': 'APPEARS_IN'}, {'source': 139, 'target': 777, 'type': 'APPEARS_IN'}, {'source': 139, 'target': 365, 'type': 'APPEARS_IN'}, {'source': 139, 'target': 838, 'type': 'APPEARS_IN'}, {'source': 139, 'target': 1065, 'type': 'APPEARS_IN'}, {'source': 139, 'target': 779, 'type': 'APPEARS_IN'}, {'source': 139, 'target': 937, 'type': 'APPEARS_IN'}, {'source': 139, 'target': 354, 'type': 'APPEARS_IN'}, {'source': 139, 'target': 28, 'type': 'APPEARS_IN'}]\".replace(/'/g, '\"')),\n",
       "      };\n",
       "    }\n",
       "\n",
       "    if(data.nodes.length == 0) {\n",
       "      svg_chart.parentElement.innerHTML = \"No results to display.\";\n",
       "    }\n",
       "\n",
       "    /* Code found in a range of places, spliced together from the following:\n",
       "    https://observablehq.com/@brunolaranjeira/d3-v6-force-directed-graph-with-directional-straight-arrow\n",
       "    https://bl.ocks.org/mbostock/4062045\n",
       "    https://github.com/nlp-tlp/aquila/blob/master/views/visualisations/entity_linking_graph.jade\n",
       "    https://observablehq.com/@harrylove/draw-an-arrowhead-marker-connected-to-a-line-in-d3\n",
       "    */\n",
       "\n",
       "    // https://stackoverflow.com/questions/5560248/programmatically-lighten-or-darken-a-hex-color-or-rgb-and-blend-colors\n",
       "    function lightenDarkenColor(col, amt) {\n",
       "      let usePound = false;\n",
       "      if (col[0] == \"#\") {\n",
       "        col = col.slice(1);\n",
       "        usePound = true;\n",
       "      }\n",
       "\n",
       "      let num = parseInt(col, 16);\n",
       "\n",
       "      let r = (num >> 16) + amt;\n",
       "\n",
       "      if (r > 255) r = 255;\n",
       "      else if (r < 0) r = 0;\n",
       "\n",
       "      let b = ((num >> 8) & 0x00ff) + amt;\n",
       "\n",
       "      if (b > 255) b = 255;\n",
       "      else if (b < 0) b = 0;\n",
       "\n",
       "      let g = (num & 0x0000ff) + amt;\n",
       "\n",
       "      if (g > 255) g = 255;\n",
       "      else if (g < 0) g = 0;\n",
       "\n",
       "      return (usePound ? \"#\" : \"\") + (g | (b << 8) | (r << 16)).toString(16);\n",
       "    }\n",
       "\n",
       "    /**\n",
       "     * Set the tooltip (after hovering over a specific node). The tooltip, which appears\n",
       "     * on the right of the graph, will show the property (key, value) pairs of the\n",
       "     * selected node.\n",
       "     * @param {[type]} d The d3 data point.\n",
       "     * @param {[type]} i The object.\n",
       "     */\n",
       "    function setTooltip(d, i) {\n",
       "      var p = Object.getPrototypeOf(i);\n",
       "      const keys = Object.keys(p);\n",
       "      const vals = keys.map((key) => p[key]);\n",
       "\n",
       "      let table = \"\";\n",
       "      for (var j = 0; j < keys.length; j++) {\n",
       "        table += \"<tr>\";\n",
       "        table += `<td>${keys[j]}:</td>`;\n",
       "        table += `<td>${vals[j]}</td>`;\n",
       "        table += \"</tr>\";\n",
       "      }\n",
       "\n",
       "      tooltipTable.innerHTML = table;\n",
       "      tooltip.style.opacity = \"0.95\";\n",
       "\n",
       "      tooltipNode = d.target;\n",
       "      updateTooltipPosition();\n",
       "\n",
       "      return d;\n",
       "    }\n",
       "\n",
       "    /**\n",
       "     * Update the position (x and y coords) of the tooltip based on the location\n",
       "     * of the element it is bound to.\n",
       "     * @return {[type]} [description]\n",
       "     */\n",
       "    function updateTooltipPosition() {\n",
       "      if (!tooltipNode) return;\n",
       "      const rect = tooltipNode.getBoundingClientRect();\n",
       "      const tooltipRect = tooltip.getBoundingClientRect();\n",
       "      const svgRect = svg_chart.getBoundingClientRect();\n",
       "\n",
       "      tooltip.style.left = `${rect.right + 25 - svgRect.left}px`;\n",
       "      tooltip.style.top = `${\n",
       "        (rect.top + rect.bottom) / 2 - tooltipRect.height / 2 - svgRect.top\n",
       "      }px`;\n",
       "    }\n",
       "\n",
       "    /**\n",
       "     * Clear the tooltip by settings its opacity to 0.\n",
       "     * @return {[type]} [description]\n",
       "     */\n",
       "    function clearTooltip() {\n",
       "      tooltip.style.opacity = \"0\";\n",
       "    }\n",
       "\n",
       "    /**\n",
       "     * Allow the nodes to be moved around when dragged.\n",
       "     * @param  {[type]} simulation [description]\n",
       "     * @return {[type]}            [description]\n",
       "     */\n",
       "    let drag = (simulation) => {\n",
       "      function dragstarted(event) {\n",
       "        if (!event.active) simulation.alphaTarget(0.05).restart();\n",
       "        event.subject.fx = event.subject.x;\n",
       "        event.subject.fy = event.subject.y;\n",
       "      }\n",
       "\n",
       "      function dragged(event) {\n",
       "        event.subject.fx = event.x;\n",
       "        event.subject.fy = event.y;\n",
       "      }\n",
       "\n",
       "      function dragended(event) {\n",
       "        if (!event.active) simulation.alphaTarget(0);\n",
       "        event.subject.fx = null;\n",
       "        event.subject.fy = null;\n",
       "      }\n",
       "\n",
       "      return d3\n",
       "        .drag()\n",
       "        .on(\"start\", dragstarted)\n",
       "        .on(\"drag\", dragged)\n",
       "        .on(\"end\", dragended);\n",
       "    };\n",
       "\n",
       "    const scale = d3.scaleOrdinal(d3.schemeCategory10);\n",
       "\n",
       "    const nodeSize = 40;\n",
       "    let height = 600;\n",
       "    let width = 600;\n",
       "\n",
       "    const links = data.links.map((d) => Object.create(d));\n",
       "    const nodes = data.nodes.map((d) => Object.create(d));\n",
       "\n",
       "    // A list of colours that the colour map will be generated from.\n",
       "    const colours = [\n",
       "      \"#99ffcc\",\n",
       "      \"#ffcccc\",\n",
       "      \"#ccccff\",\n",
       "      \"#ccff99\",\n",
       "      \"#ccffcc\",\n",
       "      \"#ccffff\",\n",
       "      \"#ffcc99\",\n",
       "      \"#ffccff\",\n",
       "      \"#ffff99\",\n",
       "      \"#ffffcc\",\n",
       "      \"#cccc99\",\n",
       "      \"#fbafff\",\n",
       "    ];\n",
       "\n",
       "    /**\n",
       "     * Load the 'colour map' (i.e. mapping of category to colour).\n",
       "     * @param  {Array} nodes The node data.\n",
       "     * @return {Object}       The colour map.\n",
       "     */\n",
       "    function loadColourMap(nodes) {\n",
       "      let colourMap = {};\n",
       "      // Load the colour map\n",
       "      for (let i = 0; i < nodes.length; i++) {\n",
       "        const category = nodes[i].category;\n",
       "        if (!(category in colourMap)) {\n",
       "          colourMap[category] =\n",
       "            colours[Object.keys(colourMap).length % colours.length];\n",
       "        }\n",
       "      }\n",
       "      return colourMap;\n",
       "    }\n",
       "    colourMap = loadColourMap(nodes);\n",
       "    const getColour = (d) => {\n",
       "      return colourMap[d.category];\n",
       "    };\n",
       "\n",
       "    // Initialise some d3 forces etc to make the graph behave properly.\n",
       "    const simulation = d3\n",
       "      .forceSimulation(nodes)\n",
       "      .force(\n",
       "        \"link\",\n",
       "        d3.forceLink(links).id((d) => d.id)\n",
       "      )\n",
       "      // .force(\"charge\", d3.forceManyBody().strength(-200))\n",
       "      .force(\n",
       "        \"collide\",\n",
       "        d3.forceCollide((d) => nodeSize * 1.5)\n",
       "      )\n",
       "      .force(\"center\", d3.forceCenter(width / 2, height / 2));\n",
       "\n",
       "    // Svg: the main container for rendering the graph.\n",
       "    const svg = d3\n",
       "      .select(CHART_SELECTOR)\n",
       "      .attr(\"viewBox\", [0, 0, width, height]);\n",
       "\n",
       "    // svg_g: The 'g' within svg, which seems to make zooming/panning smoother\n",
       "    const svg_g = svg.append(\"g\");\n",
       "    const defs = svg_g.append(\"defs\");\n",
       "\n",
       "    // Marker: a definition for the triangles appearing at the end of each link.\n",
       "    const marker = defs\n",
       "      .selectAll(\"marker\")\n",
       "      .data([\"type_1\"])\n",
       "      .enter()\n",
       "      .append(\"svg:marker\")\n",
       "      .attr(\"id\", function (d, i) {\n",
       "        return `marker_${i}`;\n",
       "      })\n",
       "      .attr(\"viewBox\", \"0 -5 10 10\")\n",
       "      .attr(\"refX\", 10)\n",
       "      .attr(\"refY\", 0)\n",
       "      .attr(\"markerWidth\", 6)\n",
       "      .attr(\"markerHeight\", 6)\n",
       "      .attr(\"orient\", \"auto\")\n",
       "      .append(\"svg:path\")\n",
       "      .attr(\"fill\", \"#444\")\n",
       "      .attr(\"d\", \"M0,-5L10,0L0,5\");\n",
       "\n",
       "    // Link: The links between nodes.\n",
       "    const link = svg_g\n",
       "      .append(\"g\")\n",
       "      .attr(\"id\", \"links\")\n",
       "      .attr(\"fill\", \"none\")\n",
       "      .attr(\"stroke-width\", 1.5)\n",
       "      .selectAll(\"path\")\n",
       "      .data(links)\n",
       "      .enter()\n",
       "      .append(\"path\")\n",
       "      .attr(\"stroke\", \"#444\")\n",
       "      .attr(\"stroke-width\", 2)\n",
       "      .attr(\"marker-end\", function (d, i) {\n",
       "        return `url(\"#marker_0\")`;\n",
       "      })\n",
       "      // 'd' attr is calculated on tick, not here.\n",
       "\n",
       "    /**\n",
       "     * When the mouse is unclicked, clear the selectedNode.\n",
       "     * This will remove the 'hide' class from all nodes in the tick function.\n",
       "     */\n",
       "    function deselectNode() {\n",
       "      selectedNode = null;\n",
       "    }\n",
       "\n",
       "    /**\n",
       "     * When a node is clicked, update selectedNode to reflect the id of that node,\n",
       "     * as well as the id of all nodes and links connected to it.\n",
       "     * @param  {[type]} d [description]\n",
       "     * @param  {[type]} i [description]\n",
       "     * @return {Object}   The selectedNode\n",
       "     *                    (baseNodeId, connectedNodeIds, connectedLinkIds).\n",
       "     */\n",
       "    function selectNode(d, i) {\n",
       "      let connectedNodeIds = new Set();\n",
       "      let connectedLinkIds = new Set();\n",
       "      for (let link of links) {\n",
       "        if (link.source.index === i.index || link.target.index === i.index) {\n",
       "          connectedLinkIds.add(link.index);\n",
       "          if (link.source.index === i.index) {\n",
       "            connectedNodeIds.add(link.target.index);\n",
       "          } else if (link.target.index === i.index) {\n",
       "            connectedNodeIds.add(link.source.index);\n",
       "          }\n",
       "        }\n",
       "      }\n",
       "      selectedNode = {\n",
       "        baseNodeId: i.index,\n",
       "        connectedNodeIds: connectedNodeIds,\n",
       "        connectedLinkIds: connectedLinkIds,\n",
       "      };\n",
       "    }\n",
       "\n",
       "    // Node: The nodes.\n",
       "    const node = svg_g\n",
       "      .append(\"g\")\n",
       "      .attr(\"stroke-width\", 3)\n",
       "      .selectAll(\"circle\")\n",
       "      .data(nodes)\n",
       "      .join(\"circle\")\n",
       "      .attr(\"class\", \"node\")\n",
       "      .attr(\"r\", nodeSize)\n",
       "      .attr(\"fill\", getColour)\n",
       "      .attr(\"stroke\", function (d) {\n",
       "        return lightenDarkenColor(getColour(d), -15);\n",
       "      })\n",
       "      .on(\"mousedown\", selectNode)\n",
       "      .call(drag(simulation));\n",
       "\n",
       "    // When a node is hovered over, set the tooltip accordingly.\n",
       "    // Clear the tooltip when the mouse leaves a node.\n",
       "    d3.selectAll(\".node\").on(\"mouseover\", setTooltip);\n",
       "    d3.selectAll(\".node\").on(\"mouseleave\", clearTooltip);\n",
       "\n",
       "    // When mouse up event (or pointer up event) fires, deselect the\n",
       "    // selected node if there is one.\n",
       "    document.addEventListener(\"mouseup\", deselectNode);\n",
       "    document.addEventListener(\"pointerup\", deselectNode);\n",
       "\n",
       "    // Text: The text appearing on the nodes.\n",
       "    const text = svg_g\n",
       "      .append(\"g\")\n",
       "      .selectAll(\"text\")\n",
       "      .data(nodes)\n",
       "      .enter()\n",
       "      .append(\"text\")\n",
       "      .text((d) => d.name)\n",
       "      .attr(\"font-size\", 12)\n",
       "      .attr(\"text-anchor\", \"middle\")\n",
       "      .attr(\"dominant-baseline\", \"central\");\n",
       "\n",
       "    // Links text: The text appearing on the links.\n",
       "    const link_text = svg_g\n",
       "      .append(\"g\")\n",
       "      .selectAll(\"text\")\n",
       "      .data(links)\n",
       "      .enter()\n",
       "      .append(\"text\")\n",
       "      .text((d) => d.type)\n",
       "      .attr(\"font-size\", 10)\n",
       "      .attr(\"text-anchor\", \"middle\")\n",
       "      .attr(\"dominant-baseline\", \"central\");\n",
       "\n",
       "    // Every time the simulation ticks, update the path of the links,\n",
       "    // the location of the nodes, the location of the text, and also the\n",
       "    // tooltip position.\n",
       "    simulation.on(\"tick\", () => {\n",
       "\n",
       "      // Only draw the links starting from the edge of node 1 to node 2.\n",
       "      // This way, when the nodes go transparent, the links won't be visible underneath\n",
       "      // the nodes (which looks bad).\n",
       "      // Code for doing this was found here:\n",
       "      // https://www.appsloveworld.com/d3js/100/17/\n",
       "      // create-links-from-node-border-to-node-border-not-center-to-center\n",
       "      link.attr(\n",
       "        \"d\",\n",
       "        (d) => {\n",
       "          x1 = d.source.x + (Math.cos(Math.atan2(d.target.y - d.source.y, d.target.x - d.source.x)) * nodeSize);\n",
       "\n",
       "          y1 = d.source.y + (Math.sin(Math.atan2(d.target.y - d.source.y, d.target.x - d.source.x)) * nodeSize);\n",
       "\n",
       "          x2 = d.target.x - (Math.cos(Math.atan2(d.target.y - d.source.y, d.target.x - d.source.x)) * nodeSize);\n",
       "\n",
       "          y2 = d.target.y - (Math.sin(Math.atan2(d.target.y - d.source.y, d.target.x - d.source.x)) * nodeSize);\n",
       "          return `M${x1},${y1}A0,0 0 0,1 ${x2},${y2}`\n",
       "        }\n",
       "      );\n",
       "\n",
       "      node.attr(\"cx\", (d) => d.x).attr(\"cy\", (d) => d.y);\n",
       "      text.attr(\"x\", (d) => Math.floor(d.x)).attr(\"y\", (d) => Math.floor(d.y));\n",
       "      link_text\n",
       "        .attr(\"x\", (d) => (d.source.x + d.target.x) / 2)\n",
       "        .attr(\"y\", (d) => (d.source.y + d.target.y) / 2);\n",
       "      updateTooltipPosition();\n",
       "\n",
       "      // If a node is currently selected, add a class to the nodes that are not\n",
       "      // related to that node.\n",
       "      //\n",
       "\n",
       "      node.classed(\"not-selected\", function (d, i) {\n",
       "        return (\n",
       "          selectedNode &&\n",
       "          selectedNode.baseNodeId !== i &&\n",
       "          !selectedNode.connectedNodeIds.has(i)\n",
       "        );\n",
       "      });\n",
       "\n",
       "      text.classed(\"not-selected\", function (d, i) {\n",
       "        return (\n",
       "          selectedNode &&\n",
       "          selectedNode.baseNodeId !== i &&\n",
       "          !selectedNode.connectedNodeIds.has(i)\n",
       "        );\n",
       "      });\n",
       "\n",
       "      link.classed(\"not-selected\", function (d, i) {\n",
       "        return selectedNode && !selectedNode.connectedLinkIds.has(i);\n",
       "      });\n",
       "\n",
       "      link_text.classed(\"not-selected\", function (d, i) {\n",
       "        return selectedNode && !selectedNode.connectedLinkIds.has(i);\n",
       "      });\n",
       "    });\n",
       "\n",
       "    // Register the zoom handler.\n",
       "    let zoom = d3.zoom().on(\"zoom\", handleZoom);\n",
       "\n",
       "    /**\n",
       "     * A function to handle zooming/panning. Sets a transform on the svg_g container\n",
       "     * according to the zoom/pan level.\n",
       "     * @param  {[type]} e [description]\n",
       "     * @return {[type]}   [description]\n",
       "     */\n",
       "    function handleZoom(e) {\n",
       "      transform = e.transform;\n",
       "      svg_g.attr(\"transform\", e.transform);\n",
       "      text.attr(\"font-size\", 12 / e.transform.k ** 0.7);\n",
       "      link_text.attr(\"font-size\", 10 / e.transform.k ** 0.7);\n",
       "    }\n",
       "\n",
       "    // Initialise the zooming.\n",
       "    function initZoom() {\n",
       "      svg.call(zoom);\n",
       "    }\n",
       "\n",
       "    initZoom();\n",
       "\n",
       "    // If dummyData is present (i.e. dev mode), display a message at the bottom.\n",
       "    if (dummyData) {\n",
       "      let div = document.createElement(\"div\");\n",
       "      div.innerHTML =\n",
       "        \"<h3>Note: currently in development mode using dummy data.</h3>\";\n",
       "      document.body.appendChild(div);\n",
       "    }\n",
       "  });\n",
       "</script>\n",
       "<!-- <script src=\"graphVisualisation.js\"></script> -->\n"
      ],
      "text/plain": [
       "<IPython.core.display.HTML object>"
      ]
     },
     "execution_count": 45,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "gqvis.visualise_cypher(\"MATCH (d:Document)<-[a:APPEARS_IN]-(o:Observation {name: 'leak'}) RETURN d, a, o\")\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We could extend this to also show the items on which the leaks were present:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 54,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<!DOCTYPE html>\n",
       "<meta charset=\"utf-8\" />\n",
       "<link\n",
       "  href=\"https://fonts.googleapis.com/css2?family=Open+Sans&display=swap\"\n",
       "  rel=\"stylesheet\"\n",
       "/>\n",
       "<style>\n",
       "  circle {\n",
       "    cursor: pointer;\n",
       "\n",
       "  }\n",
       "  .not-selected {\n",
       "    opacity: 0.2;\n",
       "  }\n",
       "  text {\n",
       "    pointer-events: none;\n",
       "    font-family: \"Open Sans\", sans-serif;\n",
       "    font-size: 12;\n",
       "  }\n",
       "\n",
       "  g#links {\n",
       "    opacity: 0.3;\n",
       "  }\n",
       "\n",
       "  .tooltip {\n",
       "    background: #f5f5f5;\n",
       "\n",
       "    padding: 10px 10px;\n",
       "    font-family: \"Open Sans\", sans-serif;\n",
       "    box-sizing: border-box;\n",
       "    font-size: 0.8em;\n",
       "    position: absolute;\n",
       "    top: 1em;\n",
       "    left: 1em;\n",
       "    opacity: 0;\n",
       "    transition: opacity 0.3s ease;\n",
       "    pointer-events: none;\n",
       "    border: 2px solid #ddd;\n",
       "  }\n",
       "  .tooltip:after {\n",
       "    content: \" \";\n",
       "    position: absolute;\n",
       "    top: calc(50% - 6px);\n",
       "    left: -12px;\n",
       "    width: 0;\n",
       "    height: 0;\n",
       "    border-style: solid;\n",
       "    border-width: 6px 12px 6px 0;\n",
       "    border-color: transparent #f5f5f5 transparent transparent;\n",
       "  }\n",
       "  .tooltip:before {\n",
       "    content: \" \";\n",
       "    position: absolute;\n",
       "    top: calc(50% - 8px);\n",
       "    left: -16px;\n",
       "    width: 0;\n",
       "    height: 0;\n",
       "    border-style: solid;\n",
       "    border-width: 8px 16px 8px 0;\n",
       "    border-color: transparent #ddd transparent transparent;\n",
       "  }\n",
       "  .tooltip-table td {\n",
       "    padding: 0em 0.5em;\n",
       "  }\n",
       "  .tooltip-table tr td:first-child {\n",
       "    font-weight: bold;\n",
       "  }\n",
       "  .tooltip-table tr td:last-child {\n",
       "    text-align: left;\n",
       "  }\n",
       "\n",
       "  .d3-graph-wrapper {\n",
       "    width: 960px;\n",
       "    display: flex;\n",
       "    flex-direction: row;\n",
       "    border: 2px solid #ddd;\n",
       "    position: relative;\n",
       "  }\n",
       "</style>\n",
       "<div class=\"d3-graph-wrapper\">\n",
       "  <svg id=\"svg-chart\" width=\"960px\" height=\"600\"></svg>\n",
       "  <div id=\"tooltip\" class=\"tooltip\">\n",
       "    <table class=\"tooltip-table\"></table>\n",
       "  </div>\n",
       "</div>\n",
       "<!-- Note d3 is loaded via require.js -->\n",
       "<script src=\"https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.6/require.min.js\"></script>\n",
       "<!-- <script>\n",
       "  // This bit is a bit of a pain.\n",
       "  // I wanted a way to run this both directly in the browser (for developing),\n",
       "  // and in Jupyter.\n",
       "  // When developing, I needed some 'dummy data' to populate the graph.\n",
       "  // The following script tag attempts to load the file 'dummyData.js' (which\n",
       "  // contains the dummy data). It will fail when running on jupyter.\n",
       "  //\n",
       "  // Whether or not the dummyData file loads (and dummyData is not null) determines\n",
       "  // whether the CHART_SELECTOR (the id of the svg chart) will be fixed or\n",
       "  // dynamic based on template injection, and also whether the nodes and links are from\n",
       "  // the dummyData or dynamic via template injection.\n",
       "  dummyData = null;\n",
       "  console.log(\n",
       "    \"Attempting to load dummy data. This will fail if running via \" +\n",
       "      \"jupyter notebook, and may throw console errors - this is OK.\"\n",
       "  );\n",
       "</script>\n",
       "<script src=\"dummyData.js\"></script> -->\n",
       "<script>\n",
       "  require.config({\n",
       "    paths: {\n",
       "      d3: \"https://d3js.org/d3.v7.min\",\n",
       "    },\n",
       "  });\n",
       "\n",
       "  // Everything is wrapped in this require.js function - this way the variables don't\n",
       "  // go into the global scope and everything works even when multiple graphs are\n",
       "  // rendered.\n",
       "  require([\"d3\"], function (d3) {\n",
       "    dummyData = null;\n",
       "\n",
       "    console.log(\"Initialising GQVis...\")\n",
       "    const CHART_SELECTOR = dummyData ? \"#chart\" : \"#chart-795873\";\n",
       "    const TOOLTIP_SELECTOR = dummyData ? \"#tooltip\" : \"#tooltip-795873\";\n",
       "    const svg_chart = document.getElementById(\"svg-chart\");\n",
       "    const tooltip = document.getElementById(\"tooltip\");\n",
       "\n",
       "    // Maintain the svg element the tooltip is currently bound to.\n",
       "    let tooltipNode = null;\n",
       "    const tooltipTable = tooltip.querySelector(\".tooltip-table\");\n",
       "\n",
       "    // Maintain the currently selected node, if any, as well as all nodes/links\n",
       "    // related to it.\n",
       "    // When not null, it will have the following:\n",
       "    // {\n",
       "    //  baseNodeId: (the index of the base node being selected),\n",
       "    //  connectedNodeIds: (an array of all connected node ids),\n",
       "    //  connectedLinkIds: (an array of all connected link ids),\n",
       "    // };\n",
       "    let selectedNode = null;\n",
       "\n",
       "\n",
       "\n",
       "    // Dynamically set the id of the svg and tooltip.\n",
       "    // If in development mode (i.e. dummyData is not null), the id will just be\n",
       "    // \"#chart\" or \"#tooltip\" respectively.\n",
       "    svg_chart.id = CHART_SELECTOR.substring(1, CHART_SELECTOR.length);\n",
       "\n",
       "    console.log(\"SVG Chart ID: \" + svg_chart.id)\n",
       "    tooltip.id = TOOLTIP_SELECTOR.substring(1, TOOLTIP_SELECTOR.length);\n",
       "    let data = {};\n",
       "    if (dummyData) {\n",
       "      data = dummyData;\n",
       "    } else {\n",
       "      data = {\n",
       "        nodes: JSON.parse(\"[{'id': 1354, 'category': 'Document', 'cost': '2700', 'name': 'both rear jacks leak oil'}, {'id': 1356, 'category': 'Observation', 'name': 'leak', '_id': 'leak__Observation'}, {'id': 1355, 'category': 'Item', 'name': 'jacks', '_id': 'jacks__Item'}, {'id': 1568, 'category': 'Item', 'name': 'engine oil', '_id': 'engine oil__Item'}, {'id': 1368, 'category': 'Item', 'name': 'mast', '_id': 'mast__Item'}, {'id': 2117, 'category': 'Item', 'name': 'motor', '_id': 'motor__Item'}, {'id': 1408, 'category': 'Item', 'name': 'air conditioner', '_id': 'air conditioner__Item'}, {'id': 2260, 'category': 'Item', 'name': 'fuel filter', '_id': 'fuel filter__Item'}, {'id': 1593, 'category': 'Item', 'name': 'potable water inlet', '_id': 'potable water inlet__Item'}, {'id': 1319, 'category': 'Item', 'name': 'rotary head', '_id': 'rotary head__Item'}, {'id': 1446, 'category': 'Item', 'name': 'cyclinder', '_id': 'cyclinder__Item'}, {'id': 1388, 'category': 'Item', 'name': 'bull hose air', '_id': 'bull hose air__Item'}, {'id': 1965, 'category': 'Item', 'name': 'feed pump', '_id': 'feed pump__Item'}, {'id': 1969, 'category': 'Item', 'name': 'regen valve', '_id': 'regen valve__Item'}, {'id': 1617, 'category': 'Item', 'name': 'lift cylinder', '_id': 'lift cylinder__Item'}, {'id': 2022, 'category': 'Item', 'name': 'loader cyl', '_id': 'loader cyl__Item'}, {'id': 1452, 'category': 'Item', 'name': 'seal', '_id': 'seal__Item'}, {'id': 1567, 'category': 'Document', 'cost': '10500', 'name': 'def.check engine oil leak'}, {'id': 1964, 'category': 'Document', 'cost': '27000', 'name': 'oil leak feed pump'}, {'id': 2401, 'category': 'Document', 'date': 20010816, 'cost': '45200', 'name': 'rotary head seal leak'}]\".replace(/'/g, '\"')),\n",
       "        links: JSON.parse(\"[{'source': 1356, 'target': 1354, 'type': 'APPEARS_IN'}, {'source': 1355, 'target': 1356, 'type': 'HAS_OBSERVATION'}, {'source': 1356, 'target': 1354, 'type': 'APPEARS_IN'}, {'source': 1568, 'target': 1356, 'type': 'HAS_OBSERVATION'}, {'source': 1356, 'target': 1354, 'type': 'APPEARS_IN'}, {'source': 1368, 'target': 1356, 'type': 'HAS_OBSERVATION'}, {'source': 1356, 'target': 1354, 'type': 'APPEARS_IN'}, {'source': 2117, 'target': 1356, 'type': 'HAS_OBSERVATION'}, {'source': 1356, 'target': 1354, 'type': 'APPEARS_IN'}, {'source': 1408, 'target': 1356, 'type': 'HAS_OBSERVATION'}, {'source': 1356, 'target': 1354, 'type': 'APPEARS_IN'}, {'source': 2260, 'target': 1356, 'type': 'HAS_OBSERVATION'}, {'source': 1356, 'target': 1354, 'type': 'APPEARS_IN'}, {'source': 1593, 'target': 1356, 'type': 'HAS_OBSERVATION'}, {'source': 1356, 'target': 1354, 'type': 'APPEARS_IN'}, {'source': 1319, 'target': 1356, 'type': 'HAS_OBSERVATION'}, {'source': 1356, 'target': 1354, 'type': 'APPEARS_IN'}, {'source': 1446, 'target': 1356, 'type': 'HAS_OBSERVATION'}, {'source': 1356, 'target': 1354, 'type': 'APPEARS_IN'}, {'source': 1388, 'target': 1356, 'type': 'HAS_OBSERVATION'}, {'source': 1356, 'target': 1354, 'type': 'APPEARS_IN'}, {'source': 1965, 'target': 1356, 'type': 'HAS_OBSERVATION'}, {'source': 1356, 'target': 1354, 'type': 'APPEARS_IN'}, {'source': 1969, 'target': 1356, 'type': 'HAS_OBSERVATION'}, {'source': 1356, 'target': 1354, 'type': 'APPEARS_IN'}, {'source': 1617, 'target': 1356, 'type': 'HAS_OBSERVATION'}, {'source': 1356, 'target': 1354, 'type': 'APPEARS_IN'}, {'source': 2022, 'target': 1356, 'type': 'HAS_OBSERVATION'}, {'source': 1356, 'target': 1354, 'type': 'APPEARS_IN'}, {'source': 1452, 'target': 1356, 'type': 'HAS_OBSERVATION'}, {'source': 1356, 'target': 1567, 'type': 'APPEARS_IN'}, {'source': 1355, 'target': 1356, 'type': 'HAS_OBSERVATION'}, {'source': 1356, 'target': 1567, 'type': 'APPEARS_IN'}, {'source': 1568, 'target': 1356, 'type': 'HAS_OBSERVATION'}, {'source': 1356, 'target': 1567, 'type': 'APPEARS_IN'}, {'source': 1368, 'target': 1356, 'type': 'HAS_OBSERVATION'}, {'source': 1356, 'target': 1567, 'type': 'APPEARS_IN'}, {'source': 2117, 'target': 1356, 'type': 'HAS_OBSERVATION'}, {'source': 1356, 'target': 1567, 'type': 'APPEARS_IN'}, {'source': 1408, 'target': 1356, 'type': 'HAS_OBSERVATION'}, {'source': 1356, 'target': 1567, 'type': 'APPEARS_IN'}, {'source': 2260, 'target': 1356, 'type': 'HAS_OBSERVATION'}, {'source': 1356, 'target': 1567, 'type': 'APPEARS_IN'}, {'source': 1593, 'target': 1356, 'type': 'HAS_OBSERVATION'}, {'source': 1356, 'target': 1567, 'type': 'APPEARS_IN'}, {'source': 1319, 'target': 1356, 'type': 'HAS_OBSERVATION'}, {'source': 1356, 'target': 1567, 'type': 'APPEARS_IN'}, {'source': 1446, 'target': 1356, 'type': 'HAS_OBSERVATION'}, {'source': 1356, 'target': 1567, 'type': 'APPEARS_IN'}, {'source': 1388, 'target': 1356, 'type': 'HAS_OBSERVATION'}, {'source': 1356, 'target': 1567, 'type': 'APPEARS_IN'}, {'source': 1965, 'target': 1356, 'type': 'HAS_OBSERVATION'}, {'source': 1356, 'target': 1567, 'type': 'APPEARS_IN'}, {'source': 1969, 'target': 1356, 'type': 'HAS_OBSERVATION'}, {'source': 1356, 'target': 1567, 'type': 'APPEARS_IN'}, {'source': 1617, 'target': 1356, 'type': 'HAS_OBSERVATION'}, {'source': 1356, 'target': 1567, 'type': 'APPEARS_IN'}, {'source': 2022, 'target': 1356, 'type': 'HAS_OBSERVATION'}, {'source': 1356, 'target': 1567, 'type': 'APPEARS_IN'}, {'source': 1452, 'target': 1356, 'type': 'HAS_OBSERVATION'}, {'source': 1356, 'target': 1964, 'type': 'APPEARS_IN'}, {'source': 1355, 'target': 1356, 'type': 'HAS_OBSERVATION'}, {'source': 1356, 'target': 1964, 'type': 'APPEARS_IN'}, {'source': 1568, 'target': 1356, 'type': 'HAS_OBSERVATION'}, {'source': 1356, 'target': 1964, 'type': 'APPEARS_IN'}, {'source': 1368, 'target': 1356, 'type': 'HAS_OBSERVATION'}, {'source': 1356, 'target': 1964, 'type': 'APPEARS_IN'}, {'source': 2117, 'target': 1356, 'type': 'HAS_OBSERVATION'}, {'source': 1356, 'target': 1964, 'type': 'APPEARS_IN'}, {'source': 1408, 'target': 1356, 'type': 'HAS_OBSERVATION'}, {'source': 1356, 'target': 1964, 'type': 'APPEARS_IN'}, {'source': 2260, 'target': 1356, 'type': 'HAS_OBSERVATION'}, {'source': 1356, 'target': 1964, 'type': 'APPEARS_IN'}, {'source': 1593, 'target': 1356, 'type': 'HAS_OBSERVATION'}, {'source': 1356, 'target': 1964, 'type': 'APPEARS_IN'}, {'source': 1319, 'target': 1356, 'type': 'HAS_OBSERVATION'}, {'source': 1356, 'target': 1964, 'type': 'APPEARS_IN'}, {'source': 1446, 'target': 1356, 'type': 'HAS_OBSERVATION'}, {'source': 1356, 'target': 1964, 'type': 'APPEARS_IN'}, {'source': 1388, 'target': 1356, 'type': 'HAS_OBSERVATION'}, {'source': 1356, 'target': 1964, 'type': 'APPEARS_IN'}, {'source': 1965, 'target': 1356, 'type': 'HAS_OBSERVATION'}, {'source': 1356, 'target': 1964, 'type': 'APPEARS_IN'}, {'source': 1969, 'target': 1356, 'type': 'HAS_OBSERVATION'}, {'source': 1356, 'target': 1964, 'type': 'APPEARS_IN'}, {'source': 1617, 'target': 1356, 'type': 'HAS_OBSERVATION'}, {'source': 1356, 'target': 1964, 'type': 'APPEARS_IN'}, {'source': 2022, 'target': 1356, 'type': 'HAS_OBSERVATION'}, {'source': 1356, 'target': 1964, 'type': 'APPEARS_IN'}, {'source': 1452, 'target': 1356, 'type': 'HAS_OBSERVATION'}, {'source': 1356, 'target': 2401, 'type': 'APPEARS_IN'}, {'source': 1355, 'target': 1356, 'type': 'HAS_OBSERVATION'}, {'source': 1356, 'target': 2401, 'type': 'APPEARS_IN'}, {'source': 1568, 'target': 1356, 'type': 'HAS_OBSERVATION'}, {'source': 1356, 'target': 2401, 'type': 'APPEARS_IN'}, {'source': 1368, 'target': 1356, 'type': 'HAS_OBSERVATION'}, {'source': 1356, 'target': 2401, 'type': 'APPEARS_IN'}, {'source': 2117, 'target': 1356, 'type': 'HAS_OBSERVATION'}, {'source': 1356, 'target': 2401, 'type': 'APPEARS_IN'}, {'source': 1408, 'target': 1356, 'type': 'HAS_OBSERVATION'}]\".replace(/'/g, '\"')),\n",
       "      };\n",
       "    }\n",
       "\n",
       "    if(data.nodes.length == 0) {\n",
       "      svg_chart.parentElement.innerHTML = \"No results to display.\";\n",
       "    }\n",
       "\n",
       "    /* Code found in a range of places, spliced together from the following:\n",
       "    https://observablehq.com/@brunolaranjeira/d3-v6-force-directed-graph-with-directional-straight-arrow\n",
       "    https://bl.ocks.org/mbostock/4062045\n",
       "    https://github.com/nlp-tlp/aquila/blob/master/views/visualisations/entity_linking_graph.jade\n",
       "    https://observablehq.com/@harrylove/draw-an-arrowhead-marker-connected-to-a-line-in-d3\n",
       "    */\n",
       "\n",
       "    // https://stackoverflow.com/questions/5560248/programmatically-lighten-or-darken-a-hex-color-or-rgb-and-blend-colors\n",
       "    function lightenDarkenColor(col, amt) {\n",
       "      let usePound = false;\n",
       "      if (col[0] == \"#\") {\n",
       "        col = col.slice(1);\n",
       "        usePound = true;\n",
       "      }\n",
       "\n",
       "      let num = parseInt(col, 16);\n",
       "\n",
       "      let r = (num >> 16) + amt;\n",
       "\n",
       "      if (r > 255) r = 255;\n",
       "      else if (r < 0) r = 0;\n",
       "\n",
       "      let b = ((num >> 8) & 0x00ff) + amt;\n",
       "\n",
       "      if (b > 255) b = 255;\n",
       "      else if (b < 0) b = 0;\n",
       "\n",
       "      let g = (num & 0x0000ff) + amt;\n",
       "\n",
       "      if (g > 255) g = 255;\n",
       "      else if (g < 0) g = 0;\n",
       "\n",
       "      return (usePound ? \"#\" : \"\") + (g | (b << 8) | (r << 16)).toString(16);\n",
       "    }\n",
       "\n",
       "    /**\n",
       "     * Set the tooltip (after hovering over a specific node). The tooltip, which appears\n",
       "     * on the right of the graph, will show the property (key, value) pairs of the\n",
       "     * selected node.\n",
       "     * @param {[type]} d The d3 data point.\n",
       "     * @param {[type]} i The object.\n",
       "     */\n",
       "    function setTooltip(d, i) {\n",
       "      var p = Object.getPrototypeOf(i);\n",
       "      const keys = Object.keys(p);\n",
       "      const vals = keys.map((key) => p[key]);\n",
       "\n",
       "      let table = \"\";\n",
       "      for (var j = 0; j < keys.length; j++) {\n",
       "        table += \"<tr>\";\n",
       "        table += `<td>${keys[j]}:</td>`;\n",
       "        table += `<td>${vals[j]}</td>`;\n",
       "        table += \"</tr>\";\n",
       "      }\n",
       "\n",
       "      tooltipTable.innerHTML = table;\n",
       "      tooltip.style.opacity = \"0.95\";\n",
       "\n",
       "      tooltipNode = d.target;\n",
       "      updateTooltipPosition();\n",
       "\n",
       "      return d;\n",
       "    }\n",
       "\n",
       "    /**\n",
       "     * Update the position (x and y coords) of the tooltip based on the location\n",
       "     * of the element it is bound to.\n",
       "     * @return {[type]} [description]\n",
       "     */\n",
       "    function updateTooltipPosition() {\n",
       "      if (!tooltipNode) return;\n",
       "      const rect = tooltipNode.getBoundingClientRect();\n",
       "      const tooltipRect = tooltip.getBoundingClientRect();\n",
       "      const svgRect = svg_chart.getBoundingClientRect();\n",
       "\n",
       "      tooltip.style.left = `${rect.right + 25 - svgRect.left}px`;\n",
       "      tooltip.style.top = `${\n",
       "        (rect.top + rect.bottom) / 2 - tooltipRect.height / 2 - svgRect.top\n",
       "      }px`;\n",
       "    }\n",
       "\n",
       "    /**\n",
       "     * Clear the tooltip by settings its opacity to 0.\n",
       "     * @return {[type]} [description]\n",
       "     */\n",
       "    function clearTooltip() {\n",
       "      tooltip.style.opacity = \"0\";\n",
       "    }\n",
       "\n",
       "    /**\n",
       "     * Allow the nodes to be moved around when dragged.\n",
       "     * @param  {[type]} simulation [description]\n",
       "     * @return {[type]}            [description]\n",
       "     */\n",
       "    let drag = (simulation) => {\n",
       "      function dragstarted(event) {\n",
       "        if (!event.active) simulation.alphaTarget(0.05).restart();\n",
       "        event.subject.fx = event.subject.x;\n",
       "        event.subject.fy = event.subject.y;\n",
       "      }\n",
       "\n",
       "      function dragged(event) {\n",
       "        event.subject.fx = event.x;\n",
       "        event.subject.fy = event.y;\n",
       "      }\n",
       "\n",
       "      function dragended(event) {\n",
       "        if (!event.active) simulation.alphaTarget(0);\n",
       "        event.subject.fx = null;\n",
       "        event.subject.fy = null;\n",
       "      }\n",
       "\n",
       "      return d3\n",
       "        .drag()\n",
       "        .on(\"start\", dragstarted)\n",
       "        .on(\"drag\", dragged)\n",
       "        .on(\"end\", dragended);\n",
       "    };\n",
       "\n",
       "    const scale = d3.scaleOrdinal(d3.schemeCategory10);\n",
       "\n",
       "    const nodeSize = 40;\n",
       "    let height = 600;\n",
       "    let width = 600;\n",
       "\n",
       "    const links = data.links.map((d) => Object.create(d));\n",
       "    const nodes = data.nodes.map((d) => Object.create(d));\n",
       "\n",
       "    // A list of colours that the colour map will be generated from.\n",
       "    const colours = [\n",
       "      \"#99ffcc\",\n",
       "      \"#ffcccc\",\n",
       "      \"#ccccff\",\n",
       "      \"#ccff99\",\n",
       "      \"#ccffcc\",\n",
       "      \"#ccffff\",\n",
       "      \"#ffcc99\",\n",
       "      \"#ffccff\",\n",
       "      \"#ffff99\",\n",
       "      \"#ffffcc\",\n",
       "      \"#cccc99\",\n",
       "      \"#fbafff\",\n",
       "    ];\n",
       "\n",
       "    /**\n",
       "     * Load the 'colour map' (i.e. mapping of category to colour).\n",
       "     * @param  {Array} nodes The node data.\n",
       "     * @return {Object}       The colour map.\n",
       "     */\n",
       "    function loadColourMap(nodes) {\n",
       "      let colourMap = {};\n",
       "      // Load the colour map\n",
       "      for (let i = 0; i < nodes.length; i++) {\n",
       "        const category = nodes[i].category;\n",
       "        if (!(category in colourMap)) {\n",
       "          colourMap[category] =\n",
       "            colours[Object.keys(colourMap).length % colours.length];\n",
       "        }\n",
       "      }\n",
       "      return colourMap;\n",
       "    }\n",
       "    colourMap = loadColourMap(nodes);\n",
       "    const getColour = (d) => {\n",
       "      return colourMap[d.category];\n",
       "    };\n",
       "\n",
       "    // Initialise some d3 forces etc to make the graph behave properly.\n",
       "    const simulation = d3\n",
       "      .forceSimulation(nodes)\n",
       "      .force(\n",
       "        \"link\",\n",
       "        d3.forceLink(links).id((d) => d.id)\n",
       "      )\n",
       "      // .force(\"charge\", d3.forceManyBody().strength(-200))\n",
       "      .force(\n",
       "        \"collide\",\n",
       "        d3.forceCollide((d) => nodeSize * 1.5)\n",
       "      )\n",
       "      .force(\"center\", d3.forceCenter(width / 2, height / 2));\n",
       "\n",
       "    // Svg: the main container for rendering the graph.\n",
       "    const svg = d3\n",
       "      .select(CHART_SELECTOR)\n",
       "      .attr(\"viewBox\", [0, 0, width, height]);\n",
       "\n",
       "    // svg_g: The 'g' within svg, which seems to make zooming/panning smoother\n",
       "    const svg_g = svg.append(\"g\");\n",
       "    const defs = svg_g.append(\"defs\");\n",
       "\n",
       "    // Marker: a definition for the triangles appearing at the end of each link.\n",
       "    const marker = defs\n",
       "      .selectAll(\"marker\")\n",
       "      .data([\"type_1\"])\n",
       "      .enter()\n",
       "      .append(\"svg:marker\")\n",
       "      .attr(\"id\", function (d, i) {\n",
       "        return `marker_${i}`;\n",
       "      })\n",
       "      .attr(\"viewBox\", \"0 -5 10 10\")\n",
       "      .attr(\"refX\", 10)\n",
       "      .attr(\"refY\", 0)\n",
       "      .attr(\"markerWidth\", 6)\n",
       "      .attr(\"markerHeight\", 6)\n",
       "      .attr(\"orient\", \"auto\")\n",
       "      .append(\"svg:path\")\n",
       "      .attr(\"fill\", \"#444\")\n",
       "      .attr(\"d\", \"M0,-5L10,0L0,5\");\n",
       "\n",
       "    // Link: The links between nodes.\n",
       "    const link = svg_g\n",
       "      .append(\"g\")\n",
       "      .attr(\"id\", \"links\")\n",
       "      .attr(\"fill\", \"none\")\n",
       "      .attr(\"stroke-width\", 1.5)\n",
       "      .selectAll(\"path\")\n",
       "      .data(links)\n",
       "      .enter()\n",
       "      .append(\"path\")\n",
       "      .attr(\"stroke\", \"#444\")\n",
       "      .attr(\"stroke-width\", 2)\n",
       "      .attr(\"marker-end\", function (d, i) {\n",
       "        return `url(\"#marker_0\")`;\n",
       "      })\n",
       "      // 'd' attr is calculated on tick, not here.\n",
       "\n",
       "    /**\n",
       "     * When the mouse is unclicked, clear the selectedNode.\n",
       "     * This will remove the 'hide' class from all nodes in the tick function.\n",
       "     */\n",
       "    function deselectNode() {\n",
       "      selectedNode = null;\n",
       "    }\n",
       "\n",
       "    /**\n",
       "     * When a node is clicked, update selectedNode to reflect the id of that node,\n",
       "     * as well as the id of all nodes and links connected to it.\n",
       "     * @param  {[type]} d [description]\n",
       "     * @param  {[type]} i [description]\n",
       "     * @return {Object}   The selectedNode\n",
       "     *                    (baseNodeId, connectedNodeIds, connectedLinkIds).\n",
       "     */\n",
       "    function selectNode(d, i) {\n",
       "      let connectedNodeIds = new Set();\n",
       "      let connectedLinkIds = new Set();\n",
       "      for (let link of links) {\n",
       "        if (link.source.index === i.index || link.target.index === i.index) {\n",
       "          connectedLinkIds.add(link.index);\n",
       "          if (link.source.index === i.index) {\n",
       "            connectedNodeIds.add(link.target.index);\n",
       "          } else if (link.target.index === i.index) {\n",
       "            connectedNodeIds.add(link.source.index);\n",
       "          }\n",
       "        }\n",
       "      }\n",
       "      selectedNode = {\n",
       "        baseNodeId: i.index,\n",
       "        connectedNodeIds: connectedNodeIds,\n",
       "        connectedLinkIds: connectedLinkIds,\n",
       "      };\n",
       "    }\n",
       "\n",
       "    // Node: The nodes.\n",
       "    const node = svg_g\n",
       "      .append(\"g\")\n",
       "      .attr(\"stroke-width\", 3)\n",
       "      .selectAll(\"circle\")\n",
       "      .data(nodes)\n",
       "      .join(\"circle\")\n",
       "      .attr(\"class\", \"node\")\n",
       "      .attr(\"r\", nodeSize)\n",
       "      .attr(\"fill\", getColour)\n",
       "      .attr(\"stroke\", function (d) {\n",
       "        return lightenDarkenColor(getColour(d), -15);\n",
       "      })\n",
       "      .on(\"mousedown\", selectNode)\n",
       "      .call(drag(simulation));\n",
       "\n",
       "    // When a node is hovered over, set the tooltip accordingly.\n",
       "    // Clear the tooltip when the mouse leaves a node.\n",
       "    d3.selectAll(\".node\").on(\"mouseover\", setTooltip);\n",
       "    d3.selectAll(\".node\").on(\"mouseleave\", clearTooltip);\n",
       "\n",
       "    // When mouse up event (or pointer up event) fires, deselect the\n",
       "    // selected node if there is one.\n",
       "    document.addEventListener(\"mouseup\", deselectNode);\n",
       "    document.addEventListener(\"pointerup\", deselectNode);\n",
       "\n",
       "    // Text: The text appearing on the nodes.\n",
       "    const text = svg_g\n",
       "      .append(\"g\")\n",
       "      .selectAll(\"text\")\n",
       "      .data(nodes)\n",
       "      .enter()\n",
       "      .append(\"text\")\n",
       "      .text((d) => d.name)\n",
       "      .attr(\"font-size\", 12)\n",
       "      .attr(\"text-anchor\", \"middle\")\n",
       "      .attr(\"dominant-baseline\", \"central\");\n",
       "\n",
       "    // Links text: The text appearing on the links.\n",
       "    const link_text = svg_g\n",
       "      .append(\"g\")\n",
       "      .selectAll(\"text\")\n",
       "      .data(links)\n",
       "      .enter()\n",
       "      .append(\"text\")\n",
       "      .text((d) => d.type)\n",
       "      .attr(\"font-size\", 10)\n",
       "      .attr(\"text-anchor\", \"middle\")\n",
       "      .attr(\"dominant-baseline\", \"central\");\n",
       "\n",
       "    // Every time the simulation ticks, update the path of the links,\n",
       "    // the location of the nodes, the location of the text, and also the\n",
       "    // tooltip position.\n",
       "    simulation.on(\"tick\", () => {\n",
       "\n",
       "      // Only draw the links starting from the edge of node 1 to node 2.\n",
       "      // This way, when the nodes go transparent, the links won't be visible underneath\n",
       "      // the nodes (which looks bad).\n",
       "      // Code for doing this was found here:\n",
       "      // https://www.appsloveworld.com/d3js/100/17/\n",
       "      // create-links-from-node-border-to-node-border-not-center-to-center\n",
       "      link.attr(\n",
       "        \"d\",\n",
       "        (d) => {\n",
       "          x1 = d.source.x + (Math.cos(Math.atan2(d.target.y - d.source.y, d.target.x - d.source.x)) * nodeSize);\n",
       "\n",
       "          y1 = d.source.y + (Math.sin(Math.atan2(d.target.y - d.source.y, d.target.x - d.source.x)) * nodeSize);\n",
       "\n",
       "          x2 = d.target.x - (Math.cos(Math.atan2(d.target.y - d.source.y, d.target.x - d.source.x)) * nodeSize);\n",
       "\n",
       "          y2 = d.target.y - (Math.sin(Math.atan2(d.target.y - d.source.y, d.target.x - d.source.x)) * nodeSize);\n",
       "          return `M${x1},${y1}A0,0 0 0,1 ${x2},${y2}`\n",
       "        }\n",
       "      );\n",
       "\n",
       "      node.attr(\"cx\", (d) => d.x).attr(\"cy\", (d) => d.y);\n",
       "      text.attr(\"x\", (d) => Math.floor(d.x)).attr(\"y\", (d) => Math.floor(d.y));\n",
       "      link_text\n",
       "        .attr(\"x\", (d) => (d.source.x + d.target.x) / 2)\n",
       "        .attr(\"y\", (d) => (d.source.y + d.target.y) / 2);\n",
       "      updateTooltipPosition();\n",
       "\n",
       "      // If a node is currently selected, add a class to the nodes that are not\n",
       "      // related to that node.\n",
       "      //\n",
       "\n",
       "      node.classed(\"not-selected\", function (d, i) {\n",
       "        return (\n",
       "          selectedNode &&\n",
       "          selectedNode.baseNodeId !== i &&\n",
       "          !selectedNode.connectedNodeIds.has(i)\n",
       "        );\n",
       "      });\n",
       "\n",
       "      text.classed(\"not-selected\", function (d, i) {\n",
       "        return (\n",
       "          selectedNode &&\n",
       "          selectedNode.baseNodeId !== i &&\n",
       "          !selectedNode.connectedNodeIds.has(i)\n",
       "        );\n",
       "      });\n",
       "\n",
       "      link.classed(\"not-selected\", function (d, i) {\n",
       "        return selectedNode && !selectedNode.connectedLinkIds.has(i);\n",
       "      });\n",
       "\n",
       "      link_text.classed(\"not-selected\", function (d, i) {\n",
       "        return selectedNode && !selectedNode.connectedLinkIds.has(i);\n",
       "      });\n",
       "    });\n",
       "\n",
       "    // Register the zoom handler.\n",
       "    let zoom = d3.zoom().on(\"zoom\", handleZoom);\n",
       "\n",
       "    /**\n",
       "     * A function to handle zooming/panning. Sets a transform on the svg_g container\n",
       "     * according to the zoom/pan level.\n",
       "     * @param  {[type]} e [description]\n",
       "     * @return {[type]}   [description]\n",
       "     */\n",
       "    function handleZoom(e) {\n",
       "      transform = e.transform;\n",
       "      svg_g.attr(\"transform\", e.transform);\n",
       "      text.attr(\"font-size\", 12 / e.transform.k ** 0.7);\n",
       "      link_text.attr(\"font-size\", 10 / e.transform.k ** 0.7);\n",
       "    }\n",
       "\n",
       "    // Initialise the zooming.\n",
       "    function initZoom() {\n",
       "      svg.call(zoom);\n",
       "    }\n",
       "\n",
       "    initZoom();\n",
       "\n",
       "    // If dummyData is present (i.e. dev mode), display a message at the bottom.\n",
       "    if (dummyData) {\n",
       "      let div = document.createElement(\"div\");\n",
       "      div.innerHTML =\n",
       "        \"<h3>Note: currently in development mode using dummy data.</h3>\";\n",
       "      document.body.appendChild(div);\n",
       "    }\n",
       "  });\n",
       "</script>\n",
       "<!-- <script src=\"graphVisualisation.js\"></script> -->\n"
      ],
      "text/plain": [
       "<IPython.core.display.HTML object>"
      ]
     },
     "execution_count": 54,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "gqvis.visualise_cypher(\"\"\"\n",
    "MATCH (d:Document)<-[a:APPEARS_IN]-(o:Observation {name: \"leak\"})<-[r:HAS_OBSERVATION]-(e:Entity)\n",
    "RETURN d, a, o, r, e\n",
    "LIMIT 50\n",
    "\"\"\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Another example query could look at the activities that were performed when leaks occurred:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 53,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<!DOCTYPE html>\n",
       "<meta charset=\"utf-8\" />\n",
       "<link\n",
       "  href=\"https://fonts.googleapis.com/css2?family=Open+Sans&display=swap\"\n",
       "  rel=\"stylesheet\"\n",
       "/>\n",
       "<style>\n",
       "  circle {\n",
       "    cursor: pointer;\n",
       "\n",
       "  }\n",
       "  .not-selected {\n",
       "    opacity: 0.2;\n",
       "  }\n",
       "  text {\n",
       "    pointer-events: none;\n",
       "    font-family: \"Open Sans\", sans-serif;\n",
       "    font-size: 12;\n",
       "  }\n",
       "\n",
       "  g#links {\n",
       "    opacity: 0.3;\n",
       "  }\n",
       "\n",
       "  .tooltip {\n",
       "    background: #f5f5f5;\n",
       "\n",
       "    padding: 10px 10px;\n",
       "    font-family: \"Open Sans\", sans-serif;\n",
       "    box-sizing: border-box;\n",
       "    font-size: 0.8em;\n",
       "    position: absolute;\n",
       "    top: 1em;\n",
       "    left: 1em;\n",
       "    opacity: 0;\n",
       "    transition: opacity 0.3s ease;\n",
       "    pointer-events: none;\n",
       "    border: 2px solid #ddd;\n",
       "  }\n",
       "  .tooltip:after {\n",
       "    content: \" \";\n",
       "    position: absolute;\n",
       "    top: calc(50% - 6px);\n",
       "    left: -12px;\n",
       "    width: 0;\n",
       "    height: 0;\n",
       "    border-style: solid;\n",
       "    border-width: 6px 12px 6px 0;\n",
       "    border-color: transparent #f5f5f5 transparent transparent;\n",
       "  }\n",
       "  .tooltip:before {\n",
       "    content: \" \";\n",
       "    position: absolute;\n",
       "    top: calc(50% - 8px);\n",
       "    left: -16px;\n",
       "    width: 0;\n",
       "    height: 0;\n",
       "    border-style: solid;\n",
       "    border-width: 8px 16px 8px 0;\n",
       "    border-color: transparent #ddd transparent transparent;\n",
       "  }\n",
       "  .tooltip-table td {\n",
       "    padding: 0em 0.5em;\n",
       "  }\n",
       "  .tooltip-table tr td:first-child {\n",
       "    font-weight: bold;\n",
       "  }\n",
       "  .tooltip-table tr td:last-child {\n",
       "    text-align: left;\n",
       "  }\n",
       "\n",
       "  .d3-graph-wrapper {\n",
       "    width: 960px;\n",
       "    display: flex;\n",
       "    flex-direction: row;\n",
       "    border: 2px solid #ddd;\n",
       "    position: relative;\n",
       "  }\n",
       "</style>\n",
       "<div class=\"d3-graph-wrapper\">\n",
       "  <svg id=\"svg-chart\" width=\"960px\" height=\"600\"></svg>\n",
       "  <div id=\"tooltip\" class=\"tooltip\">\n",
       "    <table class=\"tooltip-table\"></table>\n",
       "  </div>\n",
       "</div>\n",
       "<!-- Note d3 is loaded via require.js -->\n",
       "<script src=\"https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.6/require.min.js\"></script>\n",
       "<!-- <script>\n",
       "  // This bit is a bit of a pain.\n",
       "  // I wanted a way to run this both directly in the browser (for developing),\n",
       "  // and in Jupyter.\n",
       "  // When developing, I needed some 'dummy data' to populate the graph.\n",
       "  // The following script tag attempts to load the file 'dummyData.js' (which\n",
       "  // contains the dummy data). It will fail when running on jupyter.\n",
       "  //\n",
       "  // Whether or not the dummyData file loads (and dummyData is not null) determines\n",
       "  // whether the CHART_SELECTOR (the id of the svg chart) will be fixed or\n",
       "  // dynamic based on template injection, and also whether the nodes and links are from\n",
       "  // the dummyData or dynamic via template injection.\n",
       "  dummyData = null;\n",
       "  console.log(\n",
       "    \"Attempting to load dummy data. This will fail if running via \" +\n",
       "      \"jupyter notebook, and may throw console errors - this is OK.\"\n",
       "  );\n",
       "</script>\n",
       "<script src=\"dummyData.js\"></script> -->\n",
       "<script>\n",
       "  require.config({\n",
       "    paths: {\n",
       "      d3: \"https://d3js.org/d3.v7.min\",\n",
       "    },\n",
       "  });\n",
       "\n",
       "  // Everything is wrapped in this require.js function - this way the variables don't\n",
       "  // go into the global scope and everything works even when multiple graphs are\n",
       "  // rendered.\n",
       "  require([\"d3\"], function (d3) {\n",
       "    dummyData = null;\n",
       "\n",
       "    console.log(\"Initialising GQVis...\")\n",
       "    const CHART_SELECTOR = dummyData ? \"#chart\" : \"#chart-916711\";\n",
       "    const TOOLTIP_SELECTOR = dummyData ? \"#tooltip\" : \"#tooltip-916711\";\n",
       "    const svg_chart = document.getElementById(\"svg-chart\");\n",
       "    const tooltip = document.getElementById(\"tooltip\");\n",
       "\n",
       "    // Maintain the svg element the tooltip is currently bound to.\n",
       "    let tooltipNode = null;\n",
       "    const tooltipTable = tooltip.querySelector(\".tooltip-table\");\n",
       "\n",
       "    // Maintain the currently selected node, if any, as well as all nodes/links\n",
       "    // related to it.\n",
       "    // When not null, it will have the following:\n",
       "    // {\n",
       "    //  baseNodeId: (the index of the base node being selected),\n",
       "    //  connectedNodeIds: (an array of all connected node ids),\n",
       "    //  connectedLinkIds: (an array of all connected link ids),\n",
       "    // };\n",
       "    let selectedNode = null;\n",
       "\n",
       "\n",
       "\n",
       "    // Dynamically set the id of the svg and tooltip.\n",
       "    // If in development mode (i.e. dummyData is not null), the id will just be\n",
       "    // \"#chart\" or \"#tooltip\" respectively.\n",
       "    svg_chart.id = CHART_SELECTOR.substring(1, CHART_SELECTOR.length);\n",
       "\n",
       "    console.log(\"SVG Chart ID: \" + svg_chart.id)\n",
       "    tooltip.id = TOOLTIP_SELECTOR.substring(1, TOOLTIP_SELECTOR.length);\n",
       "    let data = {};\n",
       "    if (dummyData) {\n",
       "      data = dummyData;\n",
       "    } else {\n",
       "      data = {\n",
       "        nodes: JSON.parse(\"[{'id': 1559, 'category': 'Activity', 'name': 'replace', '_id': 'replace__Activity'}, {'id': 2259, 'category': 'Document', 'date': 20060228, 'cost': '39400', 'name': 'replace leak fuel filter'}, {'id': 1356, 'category': 'Observation', 'name': 'leak', '_id': 'leak__Observation'}, {'id': 1459, 'category': 'Activity', 'name': 'repair', '_id': 'repair__Activity'}, {'id': 2116, 'category': 'Document', 'cost': '33200', 'name': 'repair leak air conditioner motor'}]\".replace(/'/g, '\"')),\n",
       "        links: JSON.parse(\"[{'source': 1559, 'target': 2259, 'type': 'APPEARS_IN'}, {'source': 1356, 'target': 2259, 'type': 'APPEARS_IN'}, {'source': 1459, 'target': 2116, 'type': 'APPEARS_IN'}, {'source': 1356, 'target': 2116, 'type': 'APPEARS_IN'}]\".replace(/'/g, '\"')),\n",
       "      };\n",
       "    }\n",
       "\n",
       "    if(data.nodes.length == 0) {\n",
       "      svg_chart.parentElement.innerHTML = \"No results to display.\";\n",
       "    }\n",
       "\n",
       "    /* Code found in a range of places, spliced together from the following:\n",
       "    https://observablehq.com/@brunolaranjeira/d3-v6-force-directed-graph-with-directional-straight-arrow\n",
       "    https://bl.ocks.org/mbostock/4062045\n",
       "    https://github.com/nlp-tlp/aquila/blob/master/views/visualisations/entity_linking_graph.jade\n",
       "    https://observablehq.com/@harrylove/draw-an-arrowhead-marker-connected-to-a-line-in-d3\n",
       "    */\n",
       "\n",
       "    // https://stackoverflow.com/questions/5560248/programmatically-lighten-or-darken-a-hex-color-or-rgb-and-blend-colors\n",
       "    function lightenDarkenColor(col, amt) {\n",
       "      let usePound = false;\n",
       "      if (col[0] == \"#\") {\n",
       "        col = col.slice(1);\n",
       "        usePound = true;\n",
       "      }\n",
       "\n",
       "      let num = parseInt(col, 16);\n",
       "\n",
       "      let r = (num >> 16) + amt;\n",
       "\n",
       "      if (r > 255) r = 255;\n",
       "      else if (r < 0) r = 0;\n",
       "\n",
       "      let b = ((num >> 8) & 0x00ff) + amt;\n",
       "\n",
       "      if (b > 255) b = 255;\n",
       "      else if (b < 0) b = 0;\n",
       "\n",
       "      let g = (num & 0x0000ff) + amt;\n",
       "\n",
       "      if (g > 255) g = 255;\n",
       "      else if (g < 0) g = 0;\n",
       "\n",
       "      return (usePound ? \"#\" : \"\") + (g | (b << 8) | (r << 16)).toString(16);\n",
       "    }\n",
       "\n",
       "    /**\n",
       "     * Set the tooltip (after hovering over a specific node). The tooltip, which appears\n",
       "     * on the right of the graph, will show the property (key, value) pairs of the\n",
       "     * selected node.\n",
       "     * @param {[type]} d The d3 data point.\n",
       "     * @param {[type]} i The object.\n",
       "     */\n",
       "    function setTooltip(d, i) {\n",
       "      var p = Object.getPrototypeOf(i);\n",
       "      const keys = Object.keys(p);\n",
       "      const vals = keys.map((key) => p[key]);\n",
       "\n",
       "      let table = \"\";\n",
       "      for (var j = 0; j < keys.length; j++) {\n",
       "        table += \"<tr>\";\n",
       "        table += `<td>${keys[j]}:</td>`;\n",
       "        table += `<td>${vals[j]}</td>`;\n",
       "        table += \"</tr>\";\n",
       "      }\n",
       "\n",
       "      tooltipTable.innerHTML = table;\n",
       "      tooltip.style.opacity = \"0.95\";\n",
       "\n",
       "      tooltipNode = d.target;\n",
       "      updateTooltipPosition();\n",
       "\n",
       "      return d;\n",
       "    }\n",
       "\n",
       "    /**\n",
       "     * Update the position (x and y coords) of the tooltip based on the location\n",
       "     * of the element it is bound to.\n",
       "     * @return {[type]} [description]\n",
       "     */\n",
       "    function updateTooltipPosition() {\n",
       "      if (!tooltipNode) return;\n",
       "      const rect = tooltipNode.getBoundingClientRect();\n",
       "      const tooltipRect = tooltip.getBoundingClientRect();\n",
       "      const svgRect = svg_chart.getBoundingClientRect();\n",
       "\n",
       "      tooltip.style.left = `${rect.right + 25 - svgRect.left}px`;\n",
       "      tooltip.style.top = `${\n",
       "        (rect.top + rect.bottom) / 2 - tooltipRect.height / 2 - svgRect.top\n",
       "      }px`;\n",
       "    }\n",
       "\n",
       "    /**\n",
       "     * Clear the tooltip by settings its opacity to 0.\n",
       "     * @return {[type]} [description]\n",
       "     */\n",
       "    function clearTooltip() {\n",
       "      tooltip.style.opacity = \"0\";\n",
       "    }\n",
       "\n",
       "    /**\n",
       "     * Allow the nodes to be moved around when dragged.\n",
       "     * @param  {[type]} simulation [description]\n",
       "     * @return {[type]}            [description]\n",
       "     */\n",
       "    let drag = (simulation) => {\n",
       "      function dragstarted(event) {\n",
       "        if (!event.active) simulation.alphaTarget(0.05).restart();\n",
       "        event.subject.fx = event.subject.x;\n",
       "        event.subject.fy = event.subject.y;\n",
       "      }\n",
       "\n",
       "      function dragged(event) {\n",
       "        event.subject.fx = event.x;\n",
       "        event.subject.fy = event.y;\n",
       "      }\n",
       "\n",
       "      function dragended(event) {\n",
       "        if (!event.active) simulation.alphaTarget(0);\n",
       "        event.subject.fx = null;\n",
       "        event.subject.fy = null;\n",
       "      }\n",
       "\n",
       "      return d3\n",
       "        .drag()\n",
       "        .on(\"start\", dragstarted)\n",
       "        .on(\"drag\", dragged)\n",
       "        .on(\"end\", dragended);\n",
       "    };\n",
       "\n",
       "    const scale = d3.scaleOrdinal(d3.schemeCategory10);\n",
       "\n",
       "    const nodeSize = 40;\n",
       "    let height = 600;\n",
       "    let width = 600;\n",
       "\n",
       "    const links = data.links.map((d) => Object.create(d));\n",
       "    const nodes = data.nodes.map((d) => Object.create(d));\n",
       "\n",
       "    // A list of colours that the colour map will be generated from.\n",
       "    const colours = [\n",
       "      \"#99ffcc\",\n",
       "      \"#ffcccc\",\n",
       "      \"#ccccff\",\n",
       "      \"#ccff99\",\n",
       "      \"#ccffcc\",\n",
       "      \"#ccffff\",\n",
       "      \"#ffcc99\",\n",
       "      \"#ffccff\",\n",
       "      \"#ffff99\",\n",
       "      \"#ffffcc\",\n",
       "      \"#cccc99\",\n",
       "      \"#fbafff\",\n",
       "    ];\n",
       "\n",
       "    /**\n",
       "     * Load the 'colour map' (i.e. mapping of category to colour).\n",
       "     * @param  {Array} nodes The node data.\n",
       "     * @return {Object}       The colour map.\n",
       "     */\n",
       "    function loadColourMap(nodes) {\n",
       "      let colourMap = {};\n",
       "      // Load the colour map\n",
       "      for (let i = 0; i < nodes.length; i++) {\n",
       "        const category = nodes[i].category;\n",
       "        if (!(category in colourMap)) {\n",
       "          colourMap[category] =\n",
       "            colours[Object.keys(colourMap).length % colours.length];\n",
       "        }\n",
       "      }\n",
       "      return colourMap;\n",
       "    }\n",
       "    colourMap = loadColourMap(nodes);\n",
       "    const getColour = (d) => {\n",
       "      return colourMap[d.category];\n",
       "    };\n",
       "\n",
       "    // Initialise some d3 forces etc to make the graph behave properly.\n",
       "    const simulation = d3\n",
       "      .forceSimulation(nodes)\n",
       "      .force(\n",
       "        \"link\",\n",
       "        d3.forceLink(links).id((d) => d.id)\n",
       "      )\n",
       "      // .force(\"charge\", d3.forceManyBody().strength(-200))\n",
       "      .force(\n",
       "        \"collide\",\n",
       "        d3.forceCollide((d) => nodeSize * 1.5)\n",
       "      )\n",
       "      .force(\"center\", d3.forceCenter(width / 2, height / 2));\n",
       "\n",
       "    // Svg: the main container for rendering the graph.\n",
       "    const svg = d3\n",
       "      .select(CHART_SELECTOR)\n",
       "      .attr(\"viewBox\", [0, 0, width, height]);\n",
       "\n",
       "    // svg_g: The 'g' within svg, which seems to make zooming/panning smoother\n",
       "    const svg_g = svg.append(\"g\");\n",
       "    const defs = svg_g.append(\"defs\");\n",
       "\n",
       "    // Marker: a definition for the triangles appearing at the end of each link.\n",
       "    const marker = defs\n",
       "      .selectAll(\"marker\")\n",
       "      .data([\"type_1\"])\n",
       "      .enter()\n",
       "      .append(\"svg:marker\")\n",
       "      .attr(\"id\", function (d, i) {\n",
       "        return `marker_${i}`;\n",
       "      })\n",
       "      .attr(\"viewBox\", \"0 -5 10 10\")\n",
       "      .attr(\"refX\", 10)\n",
       "      .attr(\"refY\", 0)\n",
       "      .attr(\"markerWidth\", 6)\n",
       "      .attr(\"markerHeight\", 6)\n",
       "      .attr(\"orient\", \"auto\")\n",
       "      .append(\"svg:path\")\n",
       "      .attr(\"fill\", \"#444\")\n",
       "      .attr(\"d\", \"M0,-5L10,0L0,5\");\n",
       "\n",
       "    // Link: The links between nodes.\n",
       "    const link = svg_g\n",
       "      .append(\"g\")\n",
       "      .attr(\"id\", \"links\")\n",
       "      .attr(\"fill\", \"none\")\n",
       "      .attr(\"stroke-width\", 1.5)\n",
       "      .selectAll(\"path\")\n",
       "      .data(links)\n",
       "      .enter()\n",
       "      .append(\"path\")\n",
       "      .attr(\"stroke\", \"#444\")\n",
       "      .attr(\"stroke-width\", 2)\n",
       "      .attr(\"marker-end\", function (d, i) {\n",
       "        return `url(\"#marker_0\")`;\n",
       "      })\n",
       "      // 'd' attr is calculated on tick, not here.\n",
       "\n",
       "    /**\n",
       "     * When the mouse is unclicked, clear the selectedNode.\n",
       "     * This will remove the 'hide' class from all nodes in the tick function.\n",
       "     */\n",
       "    function deselectNode() {\n",
       "      selectedNode = null;\n",
       "    }\n",
       "\n",
       "    /**\n",
       "     * When a node is clicked, update selectedNode to reflect the id of that node,\n",
       "     * as well as the id of all nodes and links connected to it.\n",
       "     * @param  {[type]} d [description]\n",
       "     * @param  {[type]} i [description]\n",
       "     * @return {Object}   The selectedNode\n",
       "     *                    (baseNodeId, connectedNodeIds, connectedLinkIds).\n",
       "     */\n",
       "    function selectNode(d, i) {\n",
       "      let connectedNodeIds = new Set();\n",
       "      let connectedLinkIds = new Set();\n",
       "      for (let link of links) {\n",
       "        if (link.source.index === i.index || link.target.index === i.index) {\n",
       "          connectedLinkIds.add(link.index);\n",
       "          if (link.source.index === i.index) {\n",
       "            connectedNodeIds.add(link.target.index);\n",
       "          } else if (link.target.index === i.index) {\n",
       "            connectedNodeIds.add(link.source.index);\n",
       "          }\n",
       "        }\n",
       "      }\n",
       "      selectedNode = {\n",
       "        baseNodeId: i.index,\n",
       "        connectedNodeIds: connectedNodeIds,\n",
       "        connectedLinkIds: connectedLinkIds,\n",
       "      };\n",
       "    }\n",
       "\n",
       "    // Node: The nodes.\n",
       "    const node = svg_g\n",
       "      .append(\"g\")\n",
       "      .attr(\"stroke-width\", 3)\n",
       "      .selectAll(\"circle\")\n",
       "      .data(nodes)\n",
       "      .join(\"circle\")\n",
       "      .attr(\"class\", \"node\")\n",
       "      .attr(\"r\", nodeSize)\n",
       "      .attr(\"fill\", getColour)\n",
       "      .attr(\"stroke\", function (d) {\n",
       "        return lightenDarkenColor(getColour(d), -15);\n",
       "      })\n",
       "      .on(\"mousedown\", selectNode)\n",
       "      .call(drag(simulation));\n",
       "\n",
       "    // When a node is hovered over, set the tooltip accordingly.\n",
       "    // Clear the tooltip when the mouse leaves a node.\n",
       "    d3.selectAll(\".node\").on(\"mouseover\", setTooltip);\n",
       "    d3.selectAll(\".node\").on(\"mouseleave\", clearTooltip);\n",
       "\n",
       "    // When mouse up event (or pointer up event) fires, deselect the\n",
       "    // selected node if there is one.\n",
       "    document.addEventListener(\"mouseup\", deselectNode);\n",
       "    document.addEventListener(\"pointerup\", deselectNode);\n",
       "\n",
       "    // Text: The text appearing on the nodes.\n",
       "    const text = svg_g\n",
       "      .append(\"g\")\n",
       "      .selectAll(\"text\")\n",
       "      .data(nodes)\n",
       "      .enter()\n",
       "      .append(\"text\")\n",
       "      .text((d) => d.name)\n",
       "      .attr(\"font-size\", 12)\n",
       "      .attr(\"text-anchor\", \"middle\")\n",
       "      .attr(\"dominant-baseline\", \"central\");\n",
       "\n",
       "    // Links text: The text appearing on the links.\n",
       "    const link_text = svg_g\n",
       "      .append(\"g\")\n",
       "      .selectAll(\"text\")\n",
       "      .data(links)\n",
       "      .enter()\n",
       "      .append(\"text\")\n",
       "      .text((d) => d.type)\n",
       "      .attr(\"font-size\", 10)\n",
       "      .attr(\"text-anchor\", \"middle\")\n",
       "      .attr(\"dominant-baseline\", \"central\");\n",
       "\n",
       "    // Every time the simulation ticks, update the path of the links,\n",
       "    // the location of the nodes, the location of the text, and also the\n",
       "    // tooltip position.\n",
       "    simulation.on(\"tick\", () => {\n",
       "\n",
       "      // Only draw the links starting from the edge of node 1 to node 2.\n",
       "      // This way, when the nodes go transparent, the links won't be visible underneath\n",
       "      // the nodes (which looks bad).\n",
       "      // Code for doing this was found here:\n",
       "      // https://www.appsloveworld.com/d3js/100/17/\n",
       "      // create-links-from-node-border-to-node-border-not-center-to-center\n",
       "      link.attr(\n",
       "        \"d\",\n",
       "        (d) => {\n",
       "          x1 = d.source.x + (Math.cos(Math.atan2(d.target.y - d.source.y, d.target.x - d.source.x)) * nodeSize);\n",
       "\n",
       "          y1 = d.source.y + (Math.sin(Math.atan2(d.target.y - d.source.y, d.target.x - d.source.x)) * nodeSize);\n",
       "\n",
       "          x2 = d.target.x - (Math.cos(Math.atan2(d.target.y - d.source.y, d.target.x - d.source.x)) * nodeSize);\n",
       "\n",
       "          y2 = d.target.y - (Math.sin(Math.atan2(d.target.y - d.source.y, d.target.x - d.source.x)) * nodeSize);\n",
       "          return `M${x1},${y1}A0,0 0 0,1 ${x2},${y2}`\n",
       "        }\n",
       "      );\n",
       "\n",
       "      node.attr(\"cx\", (d) => d.x).attr(\"cy\", (d) => d.y);\n",
       "      text.attr(\"x\", (d) => Math.floor(d.x)).attr(\"y\", (d) => Math.floor(d.y));\n",
       "      link_text\n",
       "        .attr(\"x\", (d) => (d.source.x + d.target.x) / 2)\n",
       "        .attr(\"y\", (d) => (d.source.y + d.target.y) / 2);\n",
       "      updateTooltipPosition();\n",
       "\n",
       "      // If a node is currently selected, add a class to the nodes that are not\n",
       "      // related to that node.\n",
       "      //\n",
       "\n",
       "      node.classed(\"not-selected\", function (d, i) {\n",
       "        return (\n",
       "          selectedNode &&\n",
       "          selectedNode.baseNodeId !== i &&\n",
       "          !selectedNode.connectedNodeIds.has(i)\n",
       "        );\n",
       "      });\n",
       "\n",
       "      text.classed(\"not-selected\", function (d, i) {\n",
       "        return (\n",
       "          selectedNode &&\n",
       "          selectedNode.baseNodeId !== i &&\n",
       "          !selectedNode.connectedNodeIds.has(i)\n",
       "        );\n",
       "      });\n",
       "\n",
       "      link.classed(\"not-selected\", function (d, i) {\n",
       "        return selectedNode && !selectedNode.connectedLinkIds.has(i);\n",
       "      });\n",
       "\n",
       "      link_text.classed(\"not-selected\", function (d, i) {\n",
       "        return selectedNode && !selectedNode.connectedLinkIds.has(i);\n",
       "      });\n",
       "    });\n",
       "\n",
       "    // Register the zoom handler.\n",
       "    let zoom = d3.zoom().on(\"zoom\", handleZoom);\n",
       "\n",
       "    /**\n",
       "     * A function to handle zooming/panning. Sets a transform on the svg_g container\n",
       "     * according to the zoom/pan level.\n",
       "     * @param  {[type]} e [description]\n",
       "     * @return {[type]}   [description]\n",
       "     */\n",
       "    function handleZoom(e) {\n",
       "      transform = e.transform;\n",
       "      svg_g.attr(\"transform\", e.transform);\n",
       "      text.attr(\"font-size\", 12 / e.transform.k ** 0.7);\n",
       "      link_text.attr(\"font-size\", 10 / e.transform.k ** 0.7);\n",
       "    }\n",
       "\n",
       "    // Initialise the zooming.\n",
       "    function initZoom() {\n",
       "      svg.call(zoom);\n",
       "    }\n",
       "\n",
       "    initZoom();\n",
       "\n",
       "    // If dummyData is present (i.e. dev mode), display a message at the bottom.\n",
       "    if (dummyData) {\n",
       "      let div = document.createElement(\"div\");\n",
       "      div.innerHTML =\n",
       "        \"<h3>Note: currently in development mode using dummy data.</h3>\";\n",
       "      document.body.appendChild(div);\n",
       "    }\n",
       "  });\n",
       "</script>\n",
       "<!-- <script src=\"graphVisualisation.js\"></script> -->\n"
      ],
      "text/plain": [
       "<IPython.core.display.HTML object>"
      ]
     },
     "execution_count": 53,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "gqvis.visualise_cypher(\"\"\"\n",
    "MATCH (a:Activity)-[r1:APPEARS_IN]->(d:Document)<-[r2:APPEARS_IN]-(o:Observation {name: 'leak'}) RETURN a, r1, d, r2, o\n",
    "\"\"\")\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note we can also query over structured data such as dates and costs. We will not be demonstrating this in the interest of time, but feel free to attempt the query yourself! Hint: The costs and dates are stored on the `Document` nodes, which are connected to the entities appearing in those documents via the `APPEARS_IN` relation."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# 10. What next?\n",
    "\n",
    "Feel free to use/adapt any of this code to build your own knowledge graphs. You might like to try running it on your own datasets, or designing your own `NERModel` or `REModel`.\n",
    "\n",
    "Here are some potential areas to explore after this tutorial.\n",
    "\n",
    "## 10.1. Improving the lexical normalisation model\n",
    "\n",
    "We only briefly touched on the lexical normalisation component of Knowledge Graph Construction from Text. There are plenty of neural models for lexical normalisation available that yield much better performance than our lexicon-based tagger.\n",
    "\n",
    "We have also developed a tool (Lexiclean) to support the rapid creation of training data for lexical normalisation - you can learn about it [here](https://aclanthology.org/2021.emnlp-demo.25/).\n",
    "\n",
    "## 10.2. Incorporating other structured data into the graph\n",
    "\n",
    "Graph databases are excellent at bringing together data from a wide range of sources. In a maintenance setting, there are two particular types of structured data that can be easily added to this knowledge graph schema: Downtime events, and Functional Locations.\n",
    "\n",
    "### Downtime events\n",
    "\n",
    "A downtime event is a point in time in which an asset is not operational. These events typically have costs and dates associated with them, and can be associated with particular `Item` entities.\n",
    "\n",
    "By modelling both work orders and downtime events in one graph, we can make queries about downtime events. Here is an example query for the __downtime events associated with assets appearing in work orders from 25 to 28 July (where the downtime events occurred in July)__:\n",
    "\n",
    "    MATCH (d:Document)<-[a:APPEARS_IN]-(e:Entity)-[r:HAS_EVENT]->(x:DowntimeEvent)\n",
    "    WHERE d.StartDate > 20050725\n",
    "    AND d.StartDate < 20050728\n",
    "    AND 20050700 <= x.StartDate <= 20050731\n",
    "    RETURN e, r, x\n",
    "\n",
    "We can of course extend this to specific assets, such as pumps:\n",
    "\n",
    "    MATCH (d:Document)<-[a:APPEARS_IN]-(e:Entity {name: \"pump\"})-[r:HAS_EVENT]->(x:DowntimeEvent)\n",
    "    WHERE d.StartDate > 20050725\n",
    "    AND d.StartDate < 20050728\n",
    "    AND 20050700 <= x.StartDate <= 20050731\n",
    "    RETURN e, r, x\n",
    "\n",
    "In larger graphs the downtime events could even be further queried based on duration, cost, lost feed, or date ranges.\n",
    "\n",
    "### Functional Locations (FLOCs)\n",
    "\n",
    "You may have noticed that our original `work_order_data.csv` has a column called \"FLOC\". This is the functional location of the asset being maintained. In the maintenance domain, this is often of greater interest to reliability engineers than the individual `Item` entities, and thus it would be ideal to create nodes to represent these functional locations in the graph. This way, we could run queries on the failure modes associated with particular FLOCs.\n",
    "\n",
    "If you are interested in continuing work on this small graph, the next best step would be to create nodes for the functional location data (`floc_data`) and to link the downtime events to those nodes as opposed to the Item nodes.\n",
    "\n",
    "![alt text](images/adding-flocs.png \"Adding FLOCs\")\n",
    "\n",
    "### Asset Hierarchies\n",
    "\n",
    "Incorporating asset hierarchy taxonomies such as ISO15926 allows for assets to be queried hierchically, e.g. querying over all rotating equipment, etc. Failure modes can also be grouped into specific failure mode categories in order to improve failure mode queries.\n",
    "\n",
    "## 10.3. Consolidating the training data for Named Entity Recognition + Relation Extraction\n",
    "\n",
    "You may have noticed that our training data is split into two parts for the NER and RE tasks, i.e. the NER is in CONLL format and the RE is in tabular format. It is possible to put both the NER and RE training data into a single file, using the mention format we showed previously. For example, each row of your training data could look like this:\n",
    "\n",
    "    { tokens: [<list of tokens>], mentions: [<list of mentions>], relations: [<list of relations>] }\n",
    "    \n",
    "... and you could have a script to 'wrangle' this into the CONLL and tabular format before feeding them into the NER and RE model respectively. If you use a tool like [QuickGraph](https://aclanthology.org/2022.acl-demo.27/) your data will be in a similar format to the above.\n",
    "\n",
    "## 10.4. Coreference resolution\n",
    "\n",
    "What happens if we ask our model to tag the following?\n",
    "\n",
    "    pump is broken . it needs fixing\n",
    "\n",
    "The word \"it\" will most likely not be tagged as an `Item` as it is not an item at all, but a preposition. Our knowledge graph will not capture the relationship between `pump` and `fixing` because of this.\n",
    "\n",
    "Coreference resolution is the process of automatically determining the coreferences of words in the text. In the example above, the word \"it\" is a coference for \"pump\", and thus running coreference resolution on this document would yield:\n",
    "\n",
    "    pump is broken . pump needs fixing\n",
    "    \n",
    "There is not much to gain from doing this on these short text records (as prepositions are few and far between), but on longer text records (such as maintenance long text, safety reports, etc), coreference resolution is a critical step in the information extraction task.\n",
    "\n",
    "There are neural models available to do coference resolution, such as `neuralcoref` in the `spaCy` package (see [here](https://spacy.io/universe/project/neuralcoref)).\n",
    "\n",
    "\n",
    "## 10.5. From Pipeline to End-to-End Knowledge Graph Construction from Text\n",
    "\n",
    "We have presented a \"pipeline\" for KGC here in this notebook. We wrote the notebook this way in order to be able to discuss each of the components (Lexical Normalisation, Named Entity Recognition and Relation Extraction) in isolation, thus making them easier to understand.\n",
    "\n",
    "However, the current state of the art in NLP/TLP is moving away from pipeline-based KGC models and towards end-to-end neural models, i.e. a single neural model that performs all of these steps simultaneously. If you are interested in learning about this, you might like to read some of the following papers:\n",
    "\n",
    "> Stewart, M., & Liu, W. (2020, July). Seq2kg: an end-to-end neural model for domain agnostic knowledge graph (not text graph) construction from text. In   Proceedings of the International Conference on Principles of Knowledge Representation and Reasoning (Vol. 17, No. 1, pp. 748-757).\n",
    "\n",
    "> Eberts, M., & Ulges, A. (2019). Span-based joint entity and relation extraction with transformer pre-training. arXiv preprint arXiv:1909.07755.\n",
    "\n",
    "> Cabot, P. L. H., & Navigli, R. (2021, November). REBEL: Relation extraction by end-to-end language generation. In Findings of the Association for Computational Linguistics: EMNLP 2021 (pp. 2370-2381).\n",
    "\n",
    "## 10.6. Other related areas\n",
    "\n",
    "We won't go into detail on them in this notebook, but the following are important areas that are related to knowledge graphs:\n",
    "\n",
    "- Community detection\n",
    "- Knowledge graph embeddings\n",
    "- Reasoning over knowledge graphs\n",
    "- Ontologies\n",
    "- RDF schema\n",
    "- Entity linking (highly applicable to large knowledge graphs i.e. dbpedia, Freebase, Wikidata)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Acknowledgment\n",
    "\n",
    "This work is supported by the Australian Research Council through the Centre for Transforming Maintenance through Data Science  (grant number IC180100030), funded by the Australian Government.\n",
    "\n",
    "I would like to thank Tyler Bikaun, Melinda Hodkiewicz and Wei Liu for their contributions to this notebook."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## References\n",
    "\n",
    "- Baldwin, Timothy, Marie-Catherine De Marneffe, Bo Han, Young-Bum Kim, Alan Ritter, and Wei Xu. \"Shared tasks of the 2015 workshop on noisy user-generated text: Twitter lexical normalization and named entity recognition.\" In Proceedings of the Workshop on Noisy User-generated Text, pp. 126-135. 2015.\n",
    "- Cabot, Pere-Lluís Huguet, and Roberto Navigli. \"REBEL: Relation extraction by end-to-end language generation.\" In Findings of the Association for Computational Linguistics: EMNLP 2021, pp. 2370-2381. 2021.\n",
    "- Eberts, Markus, and Adrian Ulges. \"Span-based joint entity and relation extraction with transformer pre-training.\" arXiv preprint arXiv:1909.07755 (2019).\n",
    "- Han, Bo, and Timothy Baldwin. \"Lexical normalisation of short text messages: Makn sens a# twitter.\" In Proceedings of the 49th annual meeting of the association for computational linguistics: Human language technologies, pp. 368-378. 2011.\n",
    "- Josifoski, Martin, Nicola De Cao, Maxime Peyrard, and Robert West. \"GenIE: generative information extraction.\" arXiv preprint arXiv:2112.08340 (2021).\n",
    "- Lourentzou, Ismini, Kabir Manghnani, and ChengXiang Zhai. \"Adapting sequence to sequence models for text normalization in social media.\" In Proceedings of the international AAAI conference on web and social media, vol. 13, pp. 335-345. 2019.\n",
    "- Muller, Benjamin, Benoît Sagot, and Djamé Seddah. \"Enhancing BERT for lexical normalization.\" In The 5th Workshop on Noisy User-generated Text (W-NUT). 2019.\n",
    "- Nguyen, Hoang, and Sandro Cavallari. \"Neural multi-task text normalization and sanitization with pointer-generator.\" In Proceedings of the First Workshop on Natural Language Interfaces, pp. 37-47. 2020.\n",
    "- Samuel, David, and Milan Straka. 2021. “ÚFAL at MultiLexNorm 2021: Improving Multilingual Lexical Normalization by Fine-Tuning ByT5.” In Proceedings of the Seventh Workshop on Noisy User-Generated Text (W-NUT 2021), 483–92. Stroudsburg, PA, USA: Association for Computational Linguistics.\n",
    "- Stewart, Michael, Wei Liu, Rachel Cardell-Oliver, and Rui Wang. \"Short-text lexical normalisation on industrial log data.\" In 2018 IEEE International Conference on Big Knowledge (ICBK), pp. 113-122. IEEE, 2018.\n",
    "- van der Goot, Rob, Alan Ramponi, Arkaitz Zubiaga, Barbara Plank, Benjamin Muller, Iñaki San Vicente Roncal, Nikola Ljubešić, et al. 2021. “MultiLexNorm: A Shared Task on Multilingual Lexical Normalization.” In Proceedings of the Seventh Workshop on Noisy User-Generated Text (W-NUT 2021), 493–509. Online: Association for Computational Linguistics.\n",
    "- van der Goot, Rob, and Gertjan van Noord. \"Monoise: Modeling noise using a modular normalization system.\" arXiv preprint arXiv:1710.03476 (2017).\n",
    "- van der Goot, Rob, Barbara Plank, and Malvina Nissim. \"To normalize, or not to normalize: The impact of normalization on part-of-speech tagging.\" arXiv preprint arXiv:1707.05116 (2017).\n",
    "- van der Goot, Rob, Rik van Noord, and Gertjan van Noord. 2018. “A Taxonomy for In-Depth Evaluation of Normalization for User Generated Content.” In Proceedings of the Eleventh International Conference on Language Resources and Evaluation (LREC 2018). Miyazaki, Japan: European Language Resources Association (ELRA). https://aclanthology.org/L18-1109.\n",
    "- Yamada, Ikuya and Asai, Akari and Shindo, Hiroyuki and Takeda, Hideaki and Matsumoto, Yuji. \"LUKE: Deep Contextualized Entity Representations with Entity-aware Self-attention\". Proceedings of the 2020 Conference on Empirical Methods in Natural Language Processing (EMNLP). 2020.\n",
    "- Yan, Hang, Tao Gui, Junqi Dai, Qipeng Guo, Zheng Zhang, and Xipeng Qiu. \"A Unified Generative Framework for Various NER Subtasks.\" In Proceedings of the 59th Annual Meeting of the Association for Computational Linguistics and the 11th International Joint Conference on Natural Language Processing (Volume 1: Long Papers), pp. 5808-5822. 2021."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Appendix\n",
    "\n",
    "## GQVis on Jupyter Lab\n",
    "\n",
    "GQVis works out of the box on Jupyter Notebook (which is recommended), but to get it working in Jupyter Lab, you'll need to run the following command prior to starting Jupyter lab:\n",
    "\n",
    "    jupyter labextension install jupyterlab_requirejs"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Installing Neo4j in Google Colab\n",
    "\n",
    "Neo4j should work OK on the Google Colab notebook, but I have noticed it randomly uninstalls from time to time. If it does, there will be an obvious error message that appears when you attempt to run any of the cells in Section 8 (building the graph) and Section 9 (querying the graph).\n",
    "\n",
    "To reinstall Neo4j, you can run the following code. After doing this the cells in Section 8 and 9 should work OK again."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!nj-4.4/bin/neo4j stop\n",
    "\n",
    "# https://gist.github.com/korakot/328aaac51d78e589b4a176228e4bb06f\n",
    "\n",
    "!curl http://dist.neo4j.org/neo4j-community-4.4.0-unix.tar.gz -o neo4j.tar.gz\n",
    "\n",
    "# decompress and rename\n",
    "!tar -xf neo4j.tar.gz  # or --strip-components=1\n",
    "!mv neo4j-community-4.4.0 nj-4.4\n",
    "\n",
    "# disable password, and start server\n",
    "!sed -i '/#dbms.security.auth_enabled/s/^#//g' nj-4.4/conf/neo4j.conf\n",
    "!nj-4.4/bin/neo4j start"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note that there are other options such as Neo4j Aura (which allows you to run Neo4j in a cloud environment), but `gqvis` is not yet able to interact with it."
   ]
  }
 ],
 "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"
  },
  "toc-showmarkdowntxt": false
 },
 "nbformat": 4,
 "nbformat_minor": 4
}