Pipeline component for rule-based named entity recognition
entity_ruler
false
The entity ruler lets you add spans to the Doc.ents using
token-based rules or exact phrase matches. It can be combined with the
statistical EntityRecognizer to boost accuracy, or
used on its own to implement a purely rule-based entity recognition system. For
usage examples, see the docs on
rule-based entity recognition.
Config and implementation
The default config is defined by the pipeline component factory and describes
how the component should be configured. You can override its settings via the
config argument on nlp.add_pipe or in your
config.cfg for training.
Optional attribute name match on for the internal PhraseMatcher, e.g. LOWER to match on the lowercase token text. Defaults to None. Optional[Union[int, str]]
validate
Whether patterns should be validated (passed to the Matcher and PhraseMatcher). Defaults to False. bool
overwrite_ents
If existing entities are present, e.g. entities added by the model, overwrite them by matches if necessary. Defaults to False. bool
ent_id_sep
Separator used internally for entity IDs. Defaults to `"
%%GITHUB_SPACY/spacy/pipeline/entityruler.py
EntityRuler.__init__
Initialize the entity ruler. If patterns are supplied here, they need to be a
list of dictionaries with a "label" and "pattern" key. A pattern can either
be a token pattern (list) or a phrase pattern (string). For example:
{"label": "ORG", "pattern": "Apple"}.
Example
# Construction via add_piperuler=nlp.add_pipe("entity_ruler")# Construction from classfromspacy.pipelineimportEntityRulerruler=EntityRuler(nlp,overwrite_ents=True)
Name
Description
nlp
The shared nlp object to pass the vocab to the matchers and process phrase patterns. Language
name 3
Instance name of the current pipeline component. Typically passed in automatically from the factory when the component is added. Used to disable the current entity ruler while creating phrase patterns with the nlp object. str
keyword-only
phrase_matcher_attr
Optional attribute name match on for the internal PhraseMatcher, e.g. LOWER to match on the lowercase token text. Defaults to None. Optional[Union[int, str]]
validate
Whether patterns should be validated, passed to Matcher and PhraseMatcher as validate. Defaults to False. bool
overwrite_ents
If existing entities are present, e.g. entities added by the model, overwrite them by matches if necessary. Defaults to False. bool
ent_id_sep
Separator used internally for entity IDs. Defaults to `"
patterns
Optional patterns to load in on initialization. Optional[List[Dict[str, Union[str, List[dict]]]]]
EntityRuler.initialize
Initialize the component with data and used before training to load in rules
from a file. This method is typically called by
Language.initialize and lets you customize
arguments it receives via the
[initialize.components] block in the
config.
Find matches in the Doc and add them to the doc.ents. Typically, this
happens automatically after the component has been added to the pipeline using
nlp.add_pipe. If the entity ruler was initialized
with overwrite_ents=True, existing entities will be replaced if they overlap
with the matches. When matches overlap in a Doc, the entity ruler prioritizes
longer patterns over shorter, and if equal the match occuring first in the Doc
is chosen.
Example
ruler=nlp.add_pipe("entity_ruler")ruler.add_patterns([{"label":"ORG","pattern":"Apple"}])doc=nlp("A text about Apple.")ents=[(ent.text,ent.label_)forentindoc.ents]assertents==[("Apple","ORG")]
Name
Description
doc
The Doc object to process, e.g. the Doc in the pipeline. Doc
RETURNS
The modified Doc with added entities, if available. Doc
EntityRuler.add_patterns
Add patterns to the entity ruler. A pattern can either be a token pattern (list
of dicts) or a phrase pattern (string). For more details, see the usage guide on
rule-based matching.
The patterns to add. List[Dict[str, Union[str, List[dict]]]]
EntityRuler.to_disk
Save the entity ruler patterns to a directory. The patterns will be saved as
newline-delimited JSON (JSONL). If a file with the suffix .jsonl is provided,
only the patterns are saved as JSONL. If a directory name is provided, a
patterns.jsonl and cfg file with the component configuration is exported.
Example
ruler=nlp.add_pipe("entity_ruler")ruler.to_disk("/path/to/patterns.jsonl")# saves patterns onlyruler.to_disk("/path/to/entity_ruler")# saves patterns and config
Name
Description
path
A path to a JSONL file or directory, which will be created if it doesn't exist. Paths may be either strings or Path-like objects. Union[str, Path]
EntityRuler.from_disk
Load the entity ruler from a path. Expects either a file containing
newline-delimited JSON (JSONL) with one entry per line, or a directory
containing a patterns.jsonl file and a cfg file with the component
configuration.
Example
ruler=nlp.add_pipe("entity_ruler")ruler.from_disk("/path/to/patterns.jsonl")# loads patterns onlyruler.from_disk("/path/to/entity_ruler")# loads patterns and config
Name
Description
path
A path to a JSONL file or directory. Paths may be either strings or Path-like objects. Union[str, Path]
RETURNS
The modified EntityRuler object. EntityRuler
EntityRuler.to_bytes
Serialize the entity ruler patterns to a bytestring.