Matchers

DependencyMatcher

classv3
Match subtrees within a dependency parse

The DependencyMatcher follows the same API as the Matcher and PhraseMatcher and lets you match on dependency trees using Semgrex operators. It requires a pretrained DependencyParser or other component that sets the Token.dep and Token.head attributes. See the usage guide for examples.

Pattern format

A pattern added to the DependencyMatcher consists of a list of dictionaries, with each dictionary describing a token to match. Except for the first dictionary, which defines an anchor token using only RIGHT_ID and RIGHT_ATTRS, each pattern should have the following keys:

NameDescription
LEFT_IDThe name of the left-hand node in the relation, which has been defined in an earlier node. str
REL_OPAn operator that describes how the two nodes are related. str
RIGHT_IDA unique name for the right-hand node in the relation. str
RIGHT_ATTRSThe token attributes to match for the right-hand node in the same format as patterns provided to the regular token-based Matcher. Dict[str, Any]

Operators

The following operators are supported by the DependencyMatcher, most of which come directly from Semgrex:

SymbolDescription
A < BA is the immediate dependent of B.
A > BA is the immediate head of B.
A << BA is the dependent in a chain to B following dep head paths.
A >> BA is the head in a chain to B following head dep paths.
A . BA immediately precedes B, i.e. A.i == B.i - 1, and both are within the same dependency tree.
A .* BA precedes B, i.e. A.i < B.i, and both are within the same dependency tree (not in Semgrex).
A ; BA immediately follows B, i.e. A.i == B.i + 1, and both are within the same dependency tree (not in Semgrex).
A ;* BA follows B, i.e. A.i > B.i, and both are within the same dependency tree (not in Semgrex).
A $+ BB is a right immediate sibling of A, i.e. A and B have the same parent and A.i == B.i - 1.
A $- BB is a left immediate sibling of A, i.e. A and B have the same parent and A.i == B.i + 1.
A $++ BB is a right sibling of A, i.e. A and B have the same parent and A.i < B.i.
A $-- BB is a left sibling of A, i.e. A and B have the same parent and A.i > B.i.

DependencyMatcher.__init__ method

Create a DependencyMatcher.

NameDescription
vocabThe vocabulary object, which must be shared with the documents the matcher will operate on. Vocab
keyword-only
validateValidate all patterns added to this matcher. bool

DependencyMatcher._call__ method

Find all tokens matching the supplied patterns on the Doc or Span.

NameDescription
doclikeThe Doc or Span to match over. Union[Doc, Span]

DependencyMatcher.__len__ method

Get the number of rules added to the dependency matcher. Note that this only returns the number of rules (identical with the number of IDs), not the number of individual patterns.

NameDescription

DependencyMatcher.__contains__ method

Check whether the matcher contains rules for a match ID.

NameDescription
keyThe match ID. str

DependencyMatcher.add method

Add a rule to the matcher, consisting of an ID key, one or more patterns, and an optional callback function to act on the matches. The callback function will receive the arguments matcher, doc, i and matches. If a pattern already exists for the given ID, the patterns will be extended. An on_match callback will be overwritten.

NameDescription
match_idAn ID for the patterns. str
patternsA list of match patterns. A pattern consists of a list of dicts, where each dict describes a token in the tree. List[List[Dict[str, Union[str, Dict]]]]
keyword-only
on_matchCallback function to act on matches. Takes the arguments matcher, doc, i and matches. Optional[Callable[[DependencyMatcher, Doc, int, List[Tuple], Any]]

DependencyMatcher.get method

Retrieve the pattern stored for a key. Returns the rule as an (on_match, patterns) tuple containing the callback and available patterns.

NameDescription
keyThe ID of the match rule. str

DependencyMatcher.remove method

Remove a rule from the dependency matcher. A KeyError is raised if the match ID does not exist.

NameDescription
keyThe ID of the match rule. str