DependencyMatcher
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:
| Name | Description |
|---|---|
LEFT_ID | The name of the left-hand node in the relation, which has been defined in an earlier node. str |
REL_OP | An operator that describes how the two nodes are related. str |
RIGHT_ID | A unique name for the right-hand node in the relation. str |
RIGHT_ATTRS | The 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:
| Symbol | Description |
|---|---|
A < B | A is the immediate dependent of B. |
A > B | A is the immediate head of B. |
A << B | A is the dependent in a chain to B following dep → head paths. |
A >> B | A is the head in a chain to B following head → dep paths. |
A . B | A immediately precedes B, i.e. A.i == B.i - 1, and both are within the same dependency tree. |
A .* B | A precedes B, i.e. A.i < B.i, and both are within the same dependency tree (Semgrex counterpart: ..). |
A ; B | A immediately follows B, i.e. A.i == B.i + 1, and both are within the same dependency tree (Semgrex counterpart: -). |
A ;* B | A follows B, i.e. A.i > B.i, and both are within the same dependency tree (Semgrex counterpart: --). |
A $+ B | B is a right immediate sibling of A, i.e. A and B have the same parent and A.i == B.i - 1. |
A $- B | B is a left immediate sibling of A, i.e. A and B have the same parent and A.i == B.i + 1. |
A $++ B | B is a right sibling of A, i.e. A and B have the same parent and A.i < B.i. |
A $-- B | B is a left sibling of A, i.e. A and B have the same parent and A.i > B.i. |
A >+ B v3.5.1 | B is a right immediate child of A, i.e. A is a parent of B and A.i == B.i - 1 (not in Semgrex). |
A >- B v3.5.1 | B is a left immediate child of A, i.e. A is a parent of B and A.i == B.i + 1 (not in Semgrex). |
A >++ B | B is a right child of A, i.e. A is a parent of B and A.i < B.i. |
A >-- B | B is a left child of A, i.e. A is a parent of B and A.i > B.i. |
A <+ B v3.5.1 | B is a right immediate parent of A, i.e. A is a child of B and A.i == B.i - 1 (not in Semgrex). |
A <- B v3.5.1 | B is a left immediate parent of A, i.e. A is a child of B and A.i == B.i + 1 (not in Semgrex). |
A <++ B | B is a right parent of A, i.e. A is a child of B and A.i < B.i. |
A <-- B | B is a left parent of A, i.e. A is a child of B and A.i > B.i. |
DependencyMatcher.__init__ method
Create a DependencyMatcher.
| Name | Description |
|---|---|
vocab | The vocabulary object, which must be shared with the documents the matcher will operate on. Vocab |
| keyword-only | |
validate | Validate all patterns added to this matcher. bool |
DependencyMatcher.__call__ method
Find all tokens matching the supplied patterns on the Doc or Span.
| Name | Description |
|---|---|
doclike | The Doc or Span to match over. Union[Doc,Span] |
| RETURNS | A list of (match_id, token_ids) tuples, describing the matches. The match_id is the ID of the match pattern and token_ids is a list of token indices matched by the pattern, where the position of each token in the list corresponds to the position of the node specification in the pattern. List[Tuple[int, List[int]]] |
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.
| Name | Description |
|---|---|
| RETURNS | The number of rules. int |
DependencyMatcher.__contains__ method
Check whether the matcher contains rules for a match ID.
| Name | Description |
|---|---|
key | The match ID. str |
| RETURNS | Whether the matcher contains rules for this match ID. bool |
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.
| Name | Description |
|---|---|
match_id | An ID for the patterns. str |
patterns | A 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_match | Callback 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.
| Name | Description |
|---|---|
key | The ID of the match rule. str |
| RETURNS | The rule, as an (on_match, patterns) tuple. Tuple[Optional[Callable], List[List[Union[Dict, Tuple]]]] |
DependencyMatcher.remove method
Remove a rule from the dependency matcher. A KeyError is raised if the match
ID does not exist.
| Name | Description |
|---|---|
key | The ID of the match rule. str |