02_01_entityruler.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# <center>Using SpaCy's EntityRuler</center>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<center>Dr. W.J.B. Mattingly</center>\n",
    "\n",
    "<center>Smithsonian Data Science Lab and United States Holocaust Memorial Museum</center>\n",
    "\n",
    "<center>January 2021</center>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Key Concepts in this Notebook"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "1) pipe<br>\n",
    "2) factory<br>\n",
    "3) EntityRuler<br>\n",
    "4) PhraseMatcher<br>\n",
    "5) Matcher<br>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Introduction to Spacy's EntityRuler"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The Python library spaCy offers a few different methods for performing rules-based NER. One such method is via its EntityRuler.\n",
    "\n",
    "The **EntityRuler** is a spaCy factory that allows one to create a set of patterns with corresponding labels. A **factory** in spaCy is a set of classes and functions preloaded in spaCy that perform set tasks. In the case of the EntityRuler, the factory at hand allows the user to create an EntityRuler, give it a set of instructions, and then use this instructions to find and label entities.\n",
    "\n",
    "Once the user has created the EntityRuler and given it a set of instructions, the user can then add it to the spaCy pipeline as a new pipe. I have spoken in the past notebooks briefly about pipes, but perhaps it is good to address them in more detail here.\n",
    "\n",
    "A **pipe** is a component of a **pipeline**. A pipeline's purpose is to take input data, perform some sort of operations on that input data, and then output those operations either as a new data or extracted metadata. A pipe is an individual component of a pipeline. In the case of spaCy, there are a few different pipes that perform different tasks. The tokenizer, tokenizes the text into individual tokens; the parser, parses the text, and the NER identifies entities and labels them accordingly. All of this data is stored in the Doc object as we saw in Notebook 01_01 of this series.\n",
    "\n",
    "It is important to remember that pipelines are sequential. This means that components earlier in a pipeline affect what later components receive. Sometimes this sequence is essential, meaning later pipes depend on earlier pipes. At other times, this sequence is not essential, meaning later pipes can function without earlier pipes. It is important to keep this in mind as you create custom spaCy models (or any pipeline for that matter).\n",
    "\n",
    "In this notebook, we will be looking closely at the EntityRuler as a component of a spaCy model's pipeline. Off-the-shelf spaCy models come preloaded with an NER model; they do not, however, come with an EntityRuler. In order to incorperate an EntityRuler into a spaCy model, it must be created as a new pipe, given instructions, and then added to the model. Once this is complete, the user can save that new model with the EntityRuler to the disk.\n",
    "\n",
    "The full documentation of spaCy EntityRuler can be found here: https://spacy.io/api/entityruler .\n",
    "\n",
    "This notebook with synthesize this documentation for non-specialists and provide some examples of it in action."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Demonstration of EntityRuler in Action"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In the code below, we will introduce a new pipe into spaCy's off-the-shelf small English model. The purpose of this EntityRuler will be to identify small villages in Poland correctly."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Treblinka GPE\n",
      "Poland GPE\n"
     ]
    }
   ],
   "source": [
    "#Import the requisite library\n",
    "import spacy\n",
    "\n",
    "#Build upon the spaCy Small Model\n",
    "nlp = spacy.load(\"en_core_web_sm\")\n",
    "\n",
    "#Sample text\n",
    "text = \"The village of Treblinka is in Poland. Treblinka was also an extermination camp.\"\n",
    "\n",
    "#Create the Doc object\n",
    "doc = nlp(text)\n",
    "\n",
    "#extract entities\n",
    "for ent in doc.ents:\n",
    "    print (ent.text, ent.label_)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "*Depending on the version of model you are using, some results may vary.*\n",
    "\n",
    "The output from the code above demonstrates spaCy's small model's to identify Treblinka, which is a small village in Poland. As the sample text indicates, it was also an extermination camp during WWII. In the first sentence, the spaCy model tagged Treblinka as an LOC (location) and in the second it was missed entirely. Both are either imprecise or wrong. I would have accepted ORG for the second sentence, as spaCy's model does not know how to classify an extermination camp, but what these results demonstrate is the model's failure to generalize on data. The reason? There are a few, but I suspect the model never encountered the word Treblinka.\n",
    "\n",
    "This is a common problem in NLP for specific domains. Often times the domains in which we wish to deploy models, off-the-shelf models will fail because they have not been trained on domain-specific texts. We can resolve this, however, either via spaCy's EntityRuler or via training a new model. As we will see over the next few notebooks, we can use spaCy's EntityRuler to easily achieve both.\n",
    "\n",
    "For now, let's first remedy the issue by giving the model instructions for correctly identifying Treblinka. For simplicity, we will use spaCy's GPE label. In a later notebook, we will teach a model to correctly identify Treblinka in the latter context as a concentration camp."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Treblinka LOC\n",
      "Poland GPE\n",
      "Treblinka GPE\n"
     ]
    }
   ],
   "source": [
    "#Import the requisite library\n",
    "import spacy\n",
    "\n",
    "#Build upon the spaCy Small Model\n",
    "nlp = spacy.load(\"en_core_web_sm\")\n",
    "\n",
    "#Sample text\n",
    "text = \"The village of Treblinka is in Poland. Treblinka was also an extermination camp.\"\n",
    "\n",
    "#Create the EntityRuler\n",
    "ruler = nlp.add_pipe(\"entity_ruler\")\n",
    "\n",
    "#List of Entities and Patterns\n",
    "patterns = [\n",
    "                {\"label\": \"GPE\", \"pattern\": \"Treblinka\"}\n",
    "            ]\n",
    "\n",
    "ruler.add_patterns(patterns)\n",
    "\n",
    "\n",
    "doc = nlp(text)\n",
    "\n",
    "#extract entities\n",
    "for ent in doc.ents:\n",
    "    print (ent.text, ent.label_)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If you executed the code above and found that you had the same output, then you did everything correctly. This method has failed. Why? The answer comes back to the concept of pipelines. We created and added the EntityRuler to the spaCy model's pipeline, but by default, spaCy add's a new pipe to the end of the pipeline. In order to visualize the pipeline, let's use spaCy's analyze_pipes()."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'summary': {'tok2vec': {'assigns': ['doc.tensor'],\n",
       "   'requires': [],\n",
       "   'scores': [],\n",
       "   'retokenizes': False},\n",
       "  'tagger': {'assigns': ['token.tag'],\n",
       "   'requires': [],\n",
       "   'scores': ['tag_acc'],\n",
       "   'retokenizes': False},\n",
       "  'parser': {'assigns': ['token.dep',\n",
       "    'token.head',\n",
       "    'token.is_sent_start',\n",
       "    'doc.sents'],\n",
       "   'requires': [],\n",
       "   'scores': ['dep_uas',\n",
       "    'dep_las',\n",
       "    'dep_las_per_type',\n",
       "    'sents_p',\n",
       "    'sents_r',\n",
       "    'sents_f'],\n",
       "   'retokenizes': False},\n",
       "  'attribute_ruler': {'assigns': [],\n",
       "   'requires': [],\n",
       "   'scores': [],\n",
       "   'retokenizes': False},\n",
       "  'lemmatizer': {'assigns': ['token.lemma'],\n",
       "   'requires': [],\n",
       "   'scores': ['lemma_acc'],\n",
       "   'retokenizes': False},\n",
       "  'ner': {'assigns': ['doc.ents', 'token.ent_iob', 'token.ent_type'],\n",
       "   'requires': [],\n",
       "   'scores': ['ents_f', 'ents_p', 'ents_r', 'ents_per_type'],\n",
       "   'retokenizes': False},\n",
       "  'entity_ruler': {'assigns': ['doc.ents', 'token.ent_type', 'token.ent_iob'],\n",
       "   'requires': [],\n",
       "   'scores': ['ents_f', 'ents_p', 'ents_r', 'ents_per_type'],\n",
       "   'retokenizes': False}},\n",
       " 'problems': {'tok2vec': [],\n",
       "  'tagger': [],\n",
       "  'parser': [],\n",
       "  'attribute_ruler': [],\n",
       "  'lemmatizer': [],\n",
       "  'ner': [],\n",
       "  'entity_ruler': []},\n",
       " 'attrs': {'token.ent_iob': {'assigns': ['ner', 'entity_ruler'],\n",
       "   'requires': []},\n",
       "  'token.tag': {'assigns': ['tagger'], 'requires': []},\n",
       "  'token.dep': {'assigns': ['parser'], 'requires': []},\n",
       "  'token.is_sent_start': {'assigns': ['parser'], 'requires': []},\n",
       "  'token.lemma': {'assigns': ['lemmatizer'], 'requires': []},\n",
       "  'token.ent_type': {'assigns': ['ner', 'entity_ruler'], 'requires': []},\n",
       "  'doc.sents': {'assigns': ['parser'], 'requires': []},\n",
       "  'token.head': {'assigns': ['parser'], 'requires': []},\n",
       "  'doc.tensor': {'assigns': ['tok2vec'], 'requires': []},\n",
       "  'doc.ents': {'assigns': ['ner', 'entity_ruler'], 'requires': []}}}"
      ]
     },
     "execution_count": 16,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "nlp.analyze_pipes()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This can be a bit difficult to read at first, but what it shows us is the order in which our pipes are set up and a few other key pieces of information about each pipe. If we locate \"ner\", we notice that \"entity_ruler\" sits behind it.\n",
    "\n",
    "In order for our EntityRuler to have primacy, we have to assign it to after the \"ner\" pipe, as the example below shows in this line:\n",
    "\n",
    "ruler = nlp.add_pipe(\"entity_ruler\", **after=\"ner\"**)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Treblinka GPE\n",
      "Poland GPE\n",
      "Treblinka GPE\n"
     ]
    }
   ],
   "source": [
    "#Build upon the spaCy Small Model\n",
    "nlp = spacy.load(\"en_core_web_sm\")\n",
    "\n",
    "#Sample text\n",
    "text = \"The village of Treblinka is in Poland. Treblinka was also an extermination camp.\"\n",
    "\n",
    "#Create the EntityRuler\n",
    "ruler = nlp.add_pipe(\"entity_ruler\", after=\"ner\")\n",
    "\n",
    "#List of Entities and Patterns\n",
    "patterns = [\n",
    "                {\"label\": \"GPE\", \"pattern\": \"Treblinka\"}\n",
    "            ]\n",
    "\n",
    "ruler.add_patterns(patterns)\n",
    "\n",
    "\n",
    "doc = nlp(text)\n",
    "\n",
    "#extract entities\n",
    "for ent in doc.ents:\n",
    "    print (ent.text, ent.label_)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Notice now that our EntityRuler is functioning before the \"ner\" pipe and is, therefore, prefinding entities and labeling them before the NER gets to them. Because it comes earlier in the pipeline, its metadata holds primacy over the later \"ner\" pipe."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Introducing Complex Rules and Variance to the EntityRuler (Advanced)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In some instances, labels may have a set type of variance that follow a distinct pattern or sets of patterns. One such example (included in the spaCy documentation) is phone numbers. In the United States, phone numbers have a few forms. The standard formal method is (xxx)-xxx-xxxx, but it is not uncommon to see xxx-xxx-xxxx or xxxxxxxxxx. If the owner of the phone number is giving that same number to someone outside the US, then +1(xxx)-xxx-xxxx.\n",
    "\n",
    "If you are working within a United States domain, you can pass RegEx formulas to the pattern matcher to grab all of these instances.\n",
    "\n",
    "The spaCy EntityRuler also allows the user to introduce a variety of complex rules and variances (via, among other things, RegEx) by passing the rules to the pattern. There are many arguments that one can pass to the patterns. For a complete list, see: https://spacy.io/usage/rule-based-matching . To expiremnet with how these work, I recommend using the spaCy Matcher demo: https://explosion.ai/demos/matcher .\n",
    "\n",
    "In the example below we work with one example from the spaCy documentation in which we extract a phone number from a text. This same task can be done via RegEx as well."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "(555) 555-5555 PHONE_NUMBER\n"
     ]
    }
   ],
   "source": [
    "#Import the requisite library\n",
    "import spacy\n",
    "\n",
    "#Sample text\n",
    "text = \"This is a sample number (555) 555-5555.\"\n",
    "\n",
    "#Build upon the spaCy Small Model\n",
    "nlp = spacy.blank(\"en\")\n",
    "\n",
    "#Create the Ruler and Add it\n",
    "ruler = nlp.add_pipe(\"entity_ruler\")\n",
    "\n",
    "#List of Entities and Patterns (source: https://spacy.io/usage/rule-based-matching)\n",
    "patterns = [\n",
    "                {\"label\": \"PHONE_NUMBER\", \"pattern\": [{\"ORTH\": \"(\"}, {\"SHAPE\": \"ddd\"}, {\"ORTH\": \")\"}, {\"SHAPE\": \"ddd\"},\n",
    "                {\"ORTH\": \"-\", \"OP\": \"?\"}, {\"SHAPE\": \"dddd\"}]}\n",
    "            ]\n",
    "#add patterns to ruler\n",
    "ruler.add_patterns(patterns)\n",
    "\n",
    "\n",
    "\n",
    "#create the doc\n",
    "doc = nlp(text)\n",
    "\n",
    "#extract entities\n",
    "for ent in doc.ents:\n",
    "    print (ent.text, ent.label_)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Other Rules-Based Matching Techniques in spaCy."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "There are two other rules-based methods in spaCy: Matcher and PhraseMatcher. We have already met the Matcher in **01.03: Rules-Based Matching**. We will be meeting other more complex rules-based matching methods in the next few notebooks."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Exercise"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For the exercise for this notebook, try and develop a custom EntityRuler to find a custom entity in your own domain-specific texts."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Video"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Check out the video below in which we explore an entire use-case for spaCy's EntityRuler to find Harry Potter characters in the first book of Harry Potter."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div align=\"center\">\n",
       "<iframe width=\"560\" height=\"315\" src=\"https://www.youtube.com/embed/wpyCzodvO3A\" frameborder=\"0\" allow=\"accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture\" allowfullscreen></iframe>\n",
       "</div>\n"
      ],
      "text/plain": [
       "<IPython.core.display.HTML object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "%%html\n",
    "<div align=\"center\">\n",
    "<iframe width=\"560\" height=\"315\" src=\"https://www.youtube.com/embed/wpyCzodvO3A\" frameborder=\"0\" allow=\"accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture\" allowfullscreen></iframe>\n",
    "</div>"
   ]
  }
 ],
 "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.9.2"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}