edu.stanford.nlp.trees

Class GrammaticalRelation

java.lang.Object

edu.stanford.nlp.trees.GrammaticalRelation

All Implemented Interfaces:

java.io.Serializable, java.lang.Comparable<GrammaticalRelation>

public class GrammaticalRelation
extends java.lang.Object
implements java.lang.Comparable<GrammaticalRelation>, java.io.Serializable

GrammaticalRelation is used to define a standardized, hierarchical set of grammatical relations, together with patterns for identifying them in parse trees. Each GrammaticalRelation has:

• A String short name, which should be a lowercase abbreviation of some kind (in the fure mainly Universal Dependency names).
• A String long name, which should be descriptive.
• A parent in the GrammaticalRelation hierarchy.
• A {@code Pattern} called sourcePattern which matches (parent) nodes from which this GrammaticalRelation could hold. (Note: this is done with the Java regex Pattern matches() predicate. The pattern must match the whole node name, and ^ or $ aren't needed. Tregex constructions like __ do not work. Use ".*" to be applicable at all nodes. This prefiltering is used for efficiency.)
• A list of zero or more {@code TregexPattern}s called targetPatterns, which describe the local tree structure which must hold between the source node and a target node for the GrammaticalRelation to apply. (Note: tregex regular expressions match with the find() method, while literal string label descriptions that are not regular expressions must be equals().)

The targetPatterns associated with a GrammaticalRelation are designed as follows. In order to recognize a grammatical relation X holding between nodes A and B in a parse tree, we want to associate with GrammaticalRelation X a {@code TregexPattern} such that:

• the root of the pattern matches A, and
• the pattern includes a node labeled "target", which matches B.

For example, for the grammatical relation PREDICATE which holds between a clause and its primary verb phrase, we might want to use the pattern "S < VP=target", in which the root will match a clause and the node labeled "target" will match the verb phrase.

For a given grammatical relation, the method {@code getRelatedNodes()} takes a Tree node as an argument and attempts to return other nodes which have this grammatical relation to the argument node. By default, this method operates as follows: it steps through the patterns in the pattern list, trying to match each pattern against the argument node, until it finds some matches. If a pattern matches, all matching nodes (that is, each node which corresponds to node label "target" in some match) are returned as a list; otherwise the next pattern is tried.

For some grammatical relations, we need more sophisticated logic to identify related nodes. In such cases, {@code getRelatedNodes()} can be overridden on a per-relation basis using anonymous subclassing.

Author:

Bill MacCartney, Galen Andrew (refactoring English-specific stuff), Ilya Sherman (refactoring annotation-relation pairing, which is now gone)

See Also:

GrammaticalStructure, EnglishGrammaticalStructure, EnglishGrammaticalRelations, ChineseGrammaticalRelations, Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
static GrammaticalRelation	DEPENDENT The "dependent" grammatical relation, which is the inverse of "governor".
static GrammaticalRelation	GOVERNOR The "governor" grammatical relation, which is the inverse of "dependent".
static GrammaticalRelation	KILL Dummy relation, used while collapsing relations, e.g., in English & Chinese GrammaticalStructure
static GrammaticalRelation	ROOT The "root" grammatical relation between a faked "ROOT" node, and the root of the sentence.

Constructor Summary

Constructors

Constructor and Description
GrammaticalRelation(Language language, java.lang.String shortName, java.lang.String longName, GrammaticalRelation parent)
GrammaticalRelation(Language language, java.lang.String shortName, java.lang.String longName, GrammaticalRelation parent, java.lang.String specificString)
GrammaticalRelation(Language language, java.lang.String shortName, java.lang.String longName, GrammaticalRelation parent, java.lang.String sourcePattern, TregexPatternCompiler tregexCompiler, java.lang.String... targetPatterns)

Method Summary

Modifier and Type	Method and Description
int	compareTo(GrammaticalRelation o)
boolean	equals(java.lang.Object o) Grammatical relations are equal with other grammatical relations if they have the same shortName and specific (if present).
Language	getLanguage() Get the language of the grammatical relation.
java.lang.String	getLongName()
GrammaticalRelation	getParent() Returns the parent of this GrammaticalRelation.
java.util.Collection<TreeGraphNode>	getRelatedNodes(TreeGraphNode t, TreeGraphNode root, HeadFinder headFinder) Given a Tree node t, attempts to return a list of nodes to which node t has this grammatical relation, with t as the governor.
java.lang.String	getShortName()
java.lang.String	getSpecific()
int	hashCode()
boolean	isAncestor(GrammaticalRelation gr) Returns whether this is equal to or an ancestor of gr in the grammatical relations hierarchy.
boolean	isApplicable(Tree t) Returns true iff the value of Tree node t matches the sourcePattern for this GrammaticalRelation, indicating that this GrammaticalRelation is one that could hold between Tree node t and some other node.
boolean	isFromString() This function is used to determine whether the GrammaticalRelation in question is one that was created to be a thin wrapper around a String representation by valueOf(String), or whether it is a full-fledged GrammaticalRelation created by direct invocation of the constructor.
static void	main(java.lang.String[] args)
protected java.lang.Object	readResolve() When deserializing a GrammaticalRelation, it needs to be matched up with the existing singleton relation of the same type.
java.lang.String	toPrettyString() Returns a String representation of this GrammaticalRelation and the hierarchy below it, with one node per line, indented according to level.
java.lang.String	toString() Returns short name (abbreviation) for this GrammaticalRelation.
static GrammaticalRelation	valueOf(Language language, java.lang.String s) Convert from a String representation of a GrammaticalRelation to a GrammaticalRelation.
static GrammaticalRelation	valueOf(java.lang.String s)
static GrammaticalRelation	valueOf(java.lang.String s, java.util.Collection<GrammaticalRelation> values, java.util.concurrent.locks.Lock readValuesLock) Returns the GrammaticalRelation having the given string representation (e.g.
static GrammaticalRelation	valueOf(java.lang.String s, java.util.Map<java.lang.String,GrammaticalRelation> map) Returns the GrammaticalRelation having the given string representation (e.g.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

GOVERNOR

public static final GrammaticalRelation GOVERNOR

The "governor" grammatical relation, which is the inverse of "dependent".

Example: "the red car" → gov(red, car)

DEPENDENT

public static final GrammaticalRelation DEPENDENT

The "dependent" grammatical relation, which is the inverse of "governor".

Example: "the red car" → dep(car, red)

ROOT

public static final GrammaticalRelation ROOT

The "root" grammatical relation between a faked "ROOT" node, and the root of the sentence.

KILL

public static final GrammaticalRelation KILL

Dummy relation, used while collapsing relations, e.g., in English & Chinese GrammaticalStructure

Constructor Detail

GrammaticalRelation

public GrammaticalRelation(Language language,
                           java.lang.String shortName,
                           java.lang.String longName,
                           GrammaticalRelation parent,
                           java.lang.String sourcePattern,
                           TregexPatternCompiler tregexCompiler,
                           java.lang.String... targetPatterns)

GrammaticalRelation

public GrammaticalRelation(Language language,
                           java.lang.String shortName,
                           java.lang.String longName,
                           GrammaticalRelation parent)

GrammaticalRelation

public GrammaticalRelation(Language language,
                           java.lang.String shortName,
                           java.lang.String longName,
                           GrammaticalRelation parent,
                           java.lang.String specificString)

Method Detail

valueOf

public static GrammaticalRelation valueOf(java.lang.String s,
                                          java.util.Collection<GrammaticalRelation> values,
                                          java.util.concurrent.locks.Lock readValuesLock)

Returns the GrammaticalRelation having the given string representation (e.g. "nsubj"), or null if no such is found.

Parameters:

s - The short name of the GrammaticalRelation

values - The set of GrammaticalRelations to look for it among.

Returns:

The GrammaticalRelation with that name

valueOf

public static GrammaticalRelation valueOf(java.lang.String s,
                                          java.util.Map<java.lang.String,GrammaticalRelation> map)

Returns the GrammaticalRelation having the given string representation (e.g. "nsubj"), or null if no such is found.

Parameters:

s - The short name of the GrammaticalRelation

map - The map from string to GrammaticalRelation

Returns:

The GrammaticalRelation with that name

valueOf

public static GrammaticalRelation valueOf(Language language,
                                          java.lang.String s)

Convert from a String representation of a GrammaticalRelation to a GrammaticalRelation. Where possible, you should avoid using this method and simply work with true GrammaticalRelations rather than String representations. Correct behavior of this method depends on the underlying data structure resources used being kept in sync with the toString() and equals() methods. However, there is really no choice but to use this method when storing GrammaticalRelations to text files and then reading them back in, so this method is not deprecated.

Parameters:

s - The String representation of a GrammaticalRelation

Returns:

The grammatical relation represented by this String

valueOf

public static GrammaticalRelation valueOf(java.lang.String s)

isFromString

public boolean isFromString()

This function is used to determine whether the GrammaticalRelation in question is one that was created to be a thin wrapper around a String representation by valueOf(String), or whether it is a full-fledged GrammaticalRelation created by direct invocation of the constructor.

Returns:

Whether this relation is just a wrapper created by valueOf(String)

getRelatedNodes

public java.util.Collection<TreeGraphNode> getRelatedNodes(TreeGraphNode t,
                                                           TreeGraphNode root,
                                                           HeadFinder headFinder)

Given a Tree node t, attempts to return a list of nodes to which node t has this grammatical relation, with t as the governor.

Parameters:

t - Target for finding dependents of t related by this GR

root - The root of the Tree

Returns:

A Collection of dependent nodes to which t bears this GR

isApplicable

public boolean isApplicable(Tree t)

Returns true iff the value of Tree node t matches the sourcePattern for this GrammaticalRelation, indicating that this GrammaticalRelation is one that could hold between Tree node t and some other node.

isAncestor

public boolean isAncestor(GrammaticalRelation gr)

Returns whether this is equal to or an ancestor of gr in the grammatical relations hierarchy.

toString

public final java.lang.String toString()

Returns short name (abbreviation) for this GrammaticalRelation. toString() for collapsed relations will include the word that was collapsed.
Implementation note: Note that this method must be synced with the equals() and valueOf(String) methods

Overrides:

toString in class java.lang.Object

toPrettyString

public java.lang.String toPrettyString()

Returns a String representation of this GrammaticalRelation and the hierarchy below it, with one node per line, indented according to level.

Returns:

String representation of this GrammaticalRelation

equals

public boolean equals(java.lang.Object o)

Grammatical relations are equal with other grammatical relations if they have the same shortName and specific (if present). Implementation note: Note that this method must be synced with the toString() and valueOf(String) methods

Overrides:

equals in class java.lang.Object

Parameters:

o - Object to be compared

Returns:

Whether equal

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object

compareTo

public int compareTo(GrammaticalRelation o)

Specified by:

compareTo in interface java.lang.Comparable<GrammaticalRelation>

getLongName

public java.lang.String getLongName()

getShortName

public java.lang.String getShortName()

getLanguage

public Language getLanguage()

Get the language of the grammatical relation.

getSpecific

public java.lang.String getSpecific()

readResolve

protected java.lang.Object readResolve()
                                throws java.io.ObjectStreamException

When deserializing a GrammaticalRelation, it needs to be matched up with the existing singleton relation of the same type. TODO: there are a bunch of things wrong with this. For one thing, it's crazy slow, since it goes through all the existing relations in an array. For another, it would be cleaner to have subclasses for the English and Chinese relations

Throws:

java.io.ObjectStreamException

getParent

public GrammaticalRelation getParent()

Returns the parent of this GrammaticalRelation.

main

public static void main(java.lang.String[] args)