opennlp.tools.coref.resolver
Class MaxentResolver

java.lang.Object
  opennlp.tools.coref.resolver.AbstractResolver
      opennlp.tools.coref.resolver.MaxentResolver

All Implemented Interfaces:

Resolver

Direct Known Subclasses:

CommonNounResolver, DefiniteNounResolver, IsAResolver, PluralNounResolver, PluralPronounResolver, ProperNounResolver, SingularPronounResolver, SpeechPronounResolver

public abstract class MaxentResolver
extends AbstractResolver

Provides common functionality used by classes which implement the Resolver class and use maximum entropy models to make resolution decisions.

Field Summary

static String	DEFAULT Default feature value.
static String	DIFF Outcome when two mentions are not coreferent.
protected NonReferentialResolver	nonReferentialResolver The model for computing non-referential probabilities.
protected boolean	pairedSampleSelection When true, this designates that training should consist of a single positive and a single negative example (when possible) for each mention.
protected boolean	preferFirstReferent When true, this designates that the resolver should use the first referent encountered which it more preferable than non-reference.
static String	SAME Outcomes when two mentions are coreferent.
protected boolean	useSameModelForNonRef When true, this designates that the same maximum entropy model should be used non-reference events (the pairing of a mention and the "null" reference) as is used for potentially referential pairs.

Fields inherited from class opennlp.tools.coref.resolver.AbstractResolver

distances, numEntitiesBack, numSentencesBack, showExclusions

Constructor Summary

protected	MaxentResolver(int numberOfEntitiesBack, boolean preferFirstReferent) Creates a maximum-entropy-based resolver which will look the specified number of entities back for a referent.
	MaxentResolver(String modelDirectory, String modelName, ResolverMode mode, int numberEntitiesBack) Creates a maximum-entropy-based resolver with the specified model name, using the specified mode, which will look the specified number of entities back for a referent.
	MaxentResolver(String modelDirectory, String modelName, ResolverMode mode, int numberEntitiesBack, boolean preferFirstReferent)
	MaxentResolver(String modelDirectory, String modelName, ResolverMode mode, int numberEntitiesBack, boolean preferFirstReferent, double nonReferentialProbability)
	MaxentResolver(String modelDirectory, String name, ResolverMode mode, int numberOfEntitiesBack, boolean preferFirstReferent, NonReferentialResolver nonReferentialResolver) Creates a maximum-entropy-based resolver with the specified model name, using the specified mode, which will look the specified number of entities back for a referent and prefer the first referent if specified.
	MaxentResolver(String modelDirectory, String modelName, ResolverMode mode, int numberEntitiesBack, NonReferentialResolver nonReferentialResolver)

Method Summary

protected boolean	defaultReferent(DiscourseEntity de) Returns whether the specified entity satisfies the criteria for being a default referent.
protected boolean	excluded(MentionContext ec, DiscourseEntity de) Excludes entities which you are not compatible with the entity under consideration.
protected List<String>	getFeatures(MentionContext mention, DiscourseEntity entity) Returns a list of features for deciding whether the specified mention refers to the specified discourse entity.
DiscourseEntity	resolve(MentionContext ec, DiscourseModel dm) Resolve this referring expression to a discourse entity in the discourse model.
DiscourseEntity	retain(MentionContext mention, DiscourseModel dm) Uses the specified mention and discourse model to train this resolver.
static void	setSimilarityModel(TestSimilarityModel sm)
void	train() Retrains model on examples for which retain was called.

Methods inherited from class opennlp.tools.coref.resolver.AbstractResolver

featureString, getHead, getHeadIndex, getHeadString, getNumEntities, getNumEntities, outOfRange, setNumberSentencesBack

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface opennlp.tools.coref.resolver.Resolver

canResolve

Field Detail

SAME

public static final String SAME

Outcomes when two mentions are coreferent.

See Also:

Constant Field Values

DIFF

public static final String DIFF

Outcome when two mentions are not coreferent.

See Also:

Constant Field Values

DEFAULT

public static final String DEFAULT

Default feature value.

See Also:

Constant Field Values

preferFirstReferent

protected boolean preferFirstReferent

When true, this designates that the resolver should use the first referent encountered which it more preferable than non-reference. When false all non-excluded referents within this resolvers range are considered.

pairedSampleSelection

protected boolean pairedSampleSelection

When true, this designates that training should consist of a single positive and a single negative example (when possible) for each mention.

useSameModelForNonRef

protected boolean useSameModelForNonRef

When true, this designates that the same maximum entropy model should be used non-reference events (the pairing of a mention and the "null" reference) as is used for potentially referential pairs. When false a separate model is created for these events.

nonReferentialResolver

protected NonReferentialResolver nonReferentialResolver

The model for computing non-referential probabilities.

Constructor Detail

MaxentResolver

protected MaxentResolver(int numberOfEntitiesBack,
                         boolean preferFirstReferent)

Creates a maximum-entropy-based resolver which will look the specified number of entities back for a referent. This constructor is only used for unit testing.

Parameters:

numberOfEntitiesBack -

preferFirstReferent -

MaxentResolver

public MaxentResolver(String modelDirectory,
                      String name,
                      ResolverMode mode,
                      int numberOfEntitiesBack,
                      boolean preferFirstReferent,
                      NonReferentialResolver nonReferentialResolver)
               throws IOException

Creates a maximum-entropy-based resolver with the specified model name, using the specified mode, which will look the specified number of entities back for a referent and prefer the first referent if specified.

Parameters:

modelDirectory - The name of the directory where the resolver models are stored.

name - The name of the file where this model will be read or written.

mode - The mode this resolver is being using in (training, testing).

numberOfEntitiesBack - The number of entities back in the text that this resolver will look for a referent.

preferFirstReferent - Set to true if the resolver should prefer the first referent which is more likely than non-reference. This only affects testing.

nonReferentialResolver - Determines how likely it is that this entity is non-referential.

Throws:

IOException - If the model file is not found or can not be written to.

MaxentResolver

public MaxentResolver(String modelDirectory,
                      String modelName,
                      ResolverMode mode,
                      int numberEntitiesBack)
               throws IOException

Creates a maximum-entropy-based resolver with the specified model name, using the specified mode, which will look the specified number of entities back for a referent.

Parameters:

modelDirectory - The name of the directory where the resover models are stored.

modelName - The name of the file where this model will be read or written.

mode - The mode this resolver is being using in (training, testing).

numberEntitiesBack - The number of entities back in the text that this resolver will look for a referent.

Throws:

IOException - If the model file is not found or can not be written to.

MaxentResolver

public MaxentResolver(String modelDirectory,
                      String modelName,
                      ResolverMode mode,
                      int numberEntitiesBack,
                      NonReferentialResolver nonReferentialResolver)
               throws IOException

Throws:

IOException

MaxentResolver

public MaxentResolver(String modelDirectory,
                      String modelName,
                      ResolverMode mode,
                      int numberEntitiesBack,
                      boolean preferFirstReferent)
               throws IOException

Throws:

IOException

MaxentResolver

public MaxentResolver(String modelDirectory,
                      String modelName,
                      ResolverMode mode,
                      int numberEntitiesBack,
                      boolean preferFirstReferent,
                      double nonReferentialProbability)
               throws IOException

Throws:

IOException

Method Detail

resolve

public DiscourseEntity resolve(MentionContext ec,
                               DiscourseModel dm)

Description copied from interface: Resolver

Resolve this referring expression to a discourse entity in the discourse model.

Parameters:

ec - the referring expression.

dm - the discourse model.

Returns:

the discourse entity which the resolver believes this referring expression refers to or null if no discourse entity is coreferent with the referring expression.

defaultReferent

protected boolean defaultReferent(DiscourseEntity de)

Returns whether the specified entity satisfies the criteria for being a default referent. This criteria is used to perform sample selection on the training data and to select a single non-referent entity. Typically the criteria is a heuristic for a likely referent.

Parameters:

de - The discourse entity being considered for non-reference.

Returns:

True if the entity should be used as a default referent, false otherwise.

retain

public DiscourseEntity retain(MentionContext mention,
                              DiscourseModel dm)

Description copied from interface: Resolver

Uses the specified mention and discourse model to train this resolver. All mentions sent to this method need to have their id fields set to indicate coreference relationships.

Specified by:

retain in interface Resolver

Overrides:

retain in class AbstractResolver

Parameters:

mention - The mention which is being used for training.

dm - the discourse model.

Returns:

the discourse entity which is referred to by the referring expression or null if no discourse entity is referenced.

getFeatures

protected List<String> getFeatures(MentionContext mention,
                                   DiscourseEntity entity)

Returns a list of features for deciding whether the specified mention refers to the specified discourse entity.

Parameters:

mention - the mention being considers as possibly referential.

entity - The discourse entity with which the mention is being considered referential.

Returns:

a list of features used to predict reference between the specified mention and entity.

train

public void train()
           throws IOException

Description copied from interface: Resolver

Retrains model on examples for which retain was called.

Specified by:

train in interface Resolver

Overrides:

train in class AbstractResolver

Throws:

IOException

setSimilarityModel

public static void setSimilarityModel(TestSimilarityModel sm)

excluded

protected boolean excluded(MentionContext ec,
                           DiscourseEntity de)

Description copied from class: AbstractResolver

Excludes entities which you are not compatible with the entity under consideration. The default implementation excludes entities whose last extent contains the extent under consideration. This prevents possessive pronouns from referring to the noun phrases they modify and other undesirable things.

Overrides:

excluded in class AbstractResolver

Parameters:

ec - The mention which is being considered as referential.

de - The entity to which the mention is to be resolved.

Returns:

true if the entity should be excluded, false otherwise.