//- 💫 DOCS > USAGE > NAMED ENTITY RECOGNITION include ../../_includes/_mixins p | spaCy features an extremely fast statistical entity recognition system, | that assigns labels to contiguous spans of tokens. The default model | identifies a variety of named and numeric entities, including companies, | locations, organizations and products. You can add arbitrary classes to | the entity recognition system, and update the model with new examples. +h(2, "101") Named Entity Recognition 101 +tag-model("named entities") include _spacy-101/_named-entities +h(2, "accessing") Accessing entity annotations p | The standard way to access entity annotations is the | #[+api("doc#ents") #[code doc.ents]] property, which produces a sequence | of #[+api("span") #[code Span]] objects. The entity type is accessible | either as an integer ID or as a string, using the attributes | #[code ent.label] and #[code ent.label_]. The #[code Span] object acts | as a sequence of tokens, so you can iterate over the entity or index into | it. You can also get the text form of the whole entity, as though it were | a single token. p | You can also access token entity annotations using the | #[+api("token#attributes") #[code token.ent_iob]] and | #[+api("token#attributes") #[code token.ent_type]] attributes. | #[code token.ent_iob] indicates whether an entity starts, continues or | ends on the tag. If no entity type is set on a token, it will return an | empty string. +aside("IOB Scheme") | #[code I] – Token is inside an entity.#[br] | #[code O] – Token is outside an entity.#[br] | #[code B] – Token is the beginning of an entity.#[br] +code("Example"). doc = nlp(u'San Francisco considers banning sidewalk delivery robots') # document level ents = [(e.text, e.start_char, e.end_char, e.label_) for e in doc.ents] assert ents == [(u'San Francisco', 0, 13, u'GPE')] # token level ent_san = [doc[0].text, doc[0].ent_iob_, doc[0].ent_type_] ent_francisco = [doc[1].text, doc[1].ent_iob_, doc[1].ent_type_] assert ent_san == [u'San', u'B', u'GPE'] assert ent_francisco == [u'Francisco', u'I', u'GPE'] +table(["Text", "ent_iob", "ent_iob_", "ent_type", "ent_type_", "Description"]) - var style = [0, 1, 1, 1, 1, 0] +annotation-row(["San", 3, "B", 381, "GPE", "beginning of an entity"], style) +annotation-row(["Francisco", 1, "I", 381, "GPE", "inside an entity"], style) +annotation-row(["considers", 2, "O", 0, '""', "outside an entity"], style) +annotation-row(["banning", 2, "O", 0, '""', "outside an entity"], style) +annotation-row(["sidewalk", 2, "O", 0, '""', "outside an entity"], style) +annotation-row(["delivery", 2, "O", 0, '""', "outside an entity"], style) +annotation-row(["robots", 2, "O", 0, '""', "outside an entity"], style) +h(2, "setting") Setting entity annotations p | To ensure that the sequence of token annotations remains consistent, you | have to set entity annotations #[strong at the document level]. However, | you can't write directly to the #[code token.ent_iob] or | #[code token.ent_type] attributes, so the easiest way to set entities is | to assign to the #[+api("doc#ents") #[code doc.ents]] attribute | and create the new entity as a #[+api("span") #[code Span]]. +code("Example"). from spacy.tokens import Span doc = nlp(u'Netflix is hiring a new VP of global policy') # the model didn't recognise any entities :( ORG = doc.vocab.strings[u'ORG'] # get integer ID of entity label netflix_ent = Span(doc, 0, 1, label=ORG) # create a Span for the new entity doc.ents = [netflix_ent] ents = [(e.text, e.start_char, e.end_char, e.label_) for e in doc.ents] assert ents = [(u'Netflix', 0, 7, u'ORG')] p | Keep in mind that you need to create a #[code Span] with the start and | end index of the #[strong token], not the start and end index of the | entity in the document. In this case, "Netflix" is token #[code (0, 1)] – | but at the document level, the entity will have the start and end | indices #[code (0, 7)]. +h(3, "setting-from-array") Setting entity annotations from array p | You can also assign entity annotations using the | #[+api("doc#from_array") #[code doc.from_array()]] method. To do this, | you should include both the #[code ENT_TYPE] and the #[code ENT_IOB] | attributes in the array you're importing from. +code. import numpy from spacy.attrs import ENT_IOB, ENT_TYPE doc = nlp.make_doc(u'London is a big city in the United Kingdom.') assert list(doc.ents) == [] header = [ENT_IOB, ENT_TYPE] attr_array = numpy.zeros((len(doc), len(header))) attr_array[0, 0] = 2 # B attr_array[0, 1] = doc.vocab.strings[u'GPE'] doc.from_array(header, attr_array) assert list(doc.ents)[0].text == u'London' +h(3, "setting-cython") Setting entity annotations in Cython p | Finally, you can always write to the underlying struct, if you compile | a #[+a("http://cython.org/") Cython] function. This is easy to do, and | allows you to write efficient native code. +code. # cython: infer_types=True from spacy.tokens.doc cimport Doc cpdef set_entity(Doc doc, int start, int end, int ent_type): for i in range(start, end): doc.c[i].ent_type = ent_type doc.c[start].ent_iob = 3 for i in range(start+1, end): doc.c[i].ent_iob = 2 p | Obviously, if you write directly to the array of #[code TokenC*] structs, | you'll have responsibility for ensuring that the data is left in a | consistent state. +h(2, "entity-types") Built-in entity types +aside("Tip: Understanding entity types") | You can also use #[code spacy.explain()] to get the description for the | string representation of an entity label. For example, | #[code spacy.explain("LANGUAGE")] will return "any named language". include ../api/_annotation/_named-entities +h(2, "updating") Training and updating p | To provide training examples to the entity recogniser, you'll first need | to create an instance of the #[+api("goldparse") #[code GoldParse]] class. | You can specify your annotations in a stand-off format or as token tags. +code. import random import spacy from spacy.gold import GoldParse from spacy.pipeline import EntityRecognizer train_data = [('Who is Chaka Khan?', [(7, 17, 'PERSON')]), ('I like London and Berlin.', [(7, 13, 'LOC'), (18, 24, 'LOC')])] nlp = spacy.load('en', entity=False, parser=False) ner = EntityRecognizer(nlp.vocab, entity_types=['PERSON', 'LOC']) for itn in range(5): random.shuffle(train_data) for raw_text, entity_offsets in train_data: doc = nlp.make_doc(raw_text) gold = GoldParse(doc, entities=entity_offsets) nlp.tagger(doc) ner.update(doc, gold) ner.model.end_training() p | If a character offset in your entity annotations don't fall on a token | boundary, the #[code GoldParse] class will treat that annotation as a | missing value. This allows for more realistic training, because the | entity recogniser is allowed to learn from examples that may feature | tokenizer errors. +aside-code("Example"). doc = Doc(nlp.vocab, [u'rats', u'make', u'good', u'pets']) gold = GoldParse(doc, [u'U-ANIMAL', u'O', u'O', u'O']) ner = EntityRecognizer(nlp.vocab, entity_types=['ANIMAL']) ner.update(doc, gold) p | You can also provide token-level entity annotation, using the | following tagging scheme to describe the entity boundaries: +table([ "Tag", "Description" ]) +row +cell #[code #[span.u-color-theme B] EGIN] +cell The first token of a multi-token entity. +row +cell #[code #[span.u-color-theme I] N] +cell An inner token of a multi-token entity. +row +cell #[code #[span.u-color-theme L] AST] +cell The final token of a multi-token entity. +row +cell #[code #[span.u-color-theme U] NIT] +cell A single-token entity. +row +cell #[code #[span.u-color-theme O] UT] +cell A non-entity token. +aside("Why BILUO, not IOB?") | There are several coding schemes for encoding entity annotations as | token tags. These coding schemes are equally expressive, but not | necessarily equally learnable. | #[+a("http://www.aclweb.org/anthology/W09-1119") Ratinov and Roth] | showed that the minimal #[strong Begin], #[strong In], #[strong Out] | scheme was more difficult to learn than the #[strong BILUO] scheme that | we use, which explicitly marks boundary tokens. p | spaCy translates the character offsets into this scheme, in order to | decide the cost of each action given the current state of the entity | recogniser. The costs are then used to calculate the gradient of the | loss, to train the model. The exact algorithm is a pastiche of | well-known methods, and is not currently described in any single | publication. The model is a greedy transition-based parser guided by a | linear model whose weights are learned using the averaged perceptron | loss, via the #[+a("http://www.aclweb.org/anthology/C12-1059") dynamic oracle] | imitation learning strategy. The transition system is equivalent to the | BILOU tagging scheme. +h(2, "displacy") Visualizing named entities p | The #[+a(DEMOS_URL + "/displacy-ent/") displaCy #[sup ENT] visualizer] | lets you explore an entity recognition model's behaviour interactively. | If you're training a model, it's very useful to run the visualization | yourself. To help you do that, spaCy v2.0+ comes with a visualization | module. Simply pass a #[code Doc] or a list of #[code Doc] objects to | displaCy and run #[+api("displacy#serve") #[code displacy.serve]] to | run the web server, or #[+api("displacy#render") #[code displacy.render]] | to generate the raw markup. p | For more details and examples, see the | #[+a("/docs/usage/visualizers") usage guide on visualizing spaCy]. +code("Named Entity example"). import spacy from spacy import displacy text = """But Google is starting from behind. The company made a late push into hardware, and Apple’s Siri, available on iPhones, and Amazon’s Alexa software, which runs on its Echo and Dot devices, have clear leads in consumer adoption.""" nlp = spacy.load('custom_ner_model') doc = nlp(text) displacy.serve(doc, style='ent') +codepen("a73f8b68f9af3157855962b283b364e4", 345)