You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@opennlp.apache.org by ma...@apache.org on 2024/12/19 15:44:11 UTC
(opennlp-sandbox) branch OPENNLP-789-Extend-JavaDoc-for-WSD-component created (now ef94ce6)
This is an automated email from the ASF dual-hosted git repository.
mawiesne pushed a change to branch OPENNLP-789-Extend-JavaDoc-for-WSD-component
in repository https://gitbox.apache.org/repos/asf/opennlp-sandbox.git
at ef94ce6 OPENNLP-789 Extend JavaDoc for WSD component
This branch includes the following new commits:
new ef94ce6 OPENNLP-789 Extend JavaDoc for WSD component
The 1 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
(opennlp-sandbox) 01/01: OPENNLP-789 Extend JavaDoc for WSD component
Posted by ma...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
mawiesne pushed a commit to branch OPENNLP-789-Extend-JavaDoc-for-WSD-component
in repository https://gitbox.apache.org/repos/asf/opennlp-sandbox.git
commit ef94ce615bbe34d21b4aeb89177e3ca3847e888a
Author: Martin Wiesner <ma...@hs-heilbronn.de>
AuthorDate: Thu Dec 19 16:44:04 2024 +0100
OPENNLP-789 Extend JavaDoc for WSD component
---
.../disambiguator/AbstractWSDisambiguator.java | 8 +-
.../opennlp/tools/disambiguator/Disambiguator.java | 43 ++--
.../tools/disambiguator/FeaturesExtractor.java | 51 ++--
.../disambiguator/IMSWSDContextGenerator.java | 13 +-
.../disambiguator/IMSWSDSequenceValidator.java | 13 +
.../java/opennlp/tools/disambiguator/Lesk.java | 269 +++++++--------------
.../tools/disambiguator/LeskParameters.java | 23 +-
.../main/java/opennlp/tools/disambiguator/MFS.java | 4 -
.../java/opennlp/tools/disambiguator/SynNode.java | 13 +-
.../tools/disambiguator/WSDContextGenerator.java | 6 +-
.../tools/disambiguator/WSDDefaultParameters.java | 47 ++--
.../tools/disambiguator/WSDEvaluationMonitor.java | 5 +-
.../opennlp/tools/disambiguator/WSDEvaluator.java | 21 +-
.../opennlp/tools/disambiguator/WSDHelper.java | 4 +
.../java/opennlp/tools/disambiguator/WSDModel.java | 12 +
.../opennlp/tools/disambiguator/WSDParameters.java | 22 +-
.../opennlp/tools/disambiguator/WSDSample.java | 10 +-
.../disambiguator/WSDisambiguatorFactory.java | 11 +
.../java/opennlp/tools/disambiguator/WTDIMS.java | 18 +-
.../java/opennlp/tools/disambiguator/WordPOS.java | 17 +-
.../opennlp/tools/disambiguator/WordSense.java | 50 +++-
21 files changed, 357 insertions(+), 303 deletions(-)
diff --git a/opennlp-wsd/src/main/java/opennlp/tools/disambiguator/AbstractWSDisambiguator.java b/opennlp-wsd/src/main/java/opennlp/tools/disambiguator/AbstractWSDisambiguator.java
index de8cbad..bff03d0 100644
--- a/opennlp-wsd/src/main/java/opennlp/tools/disambiguator/AbstractWSDisambiguator.java
+++ b/opennlp-wsd/src/main/java/opennlp/tools/disambiguator/AbstractWSDisambiguator.java
@@ -33,9 +33,13 @@ import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
/**
- * A base implementation of {@link Disambiguator}
+ * A base implementation of {@link Disambiguator}.
+ * <p>
+ * Hint:<br/>
+ * Examples on how to use different implementation approaches are provided
+ * in the corresponding tests.
*
- * @implNote Examples on how to use each approach are provided in the test section.
+ * @implNote For the moment the source of sense definitions is from WordNet.
*
* @see Disambiguator
* @see WSDParameters
diff --git a/opennlp-wsd/src/main/java/opennlp/tools/disambiguator/Disambiguator.java b/opennlp-wsd/src/main/java/opennlp/tools/disambiguator/Disambiguator.java
index ecabbdf..0cda028 100644
--- a/opennlp-wsd/src/main/java/opennlp/tools/disambiguator/Disambiguator.java
+++ b/opennlp-wsd/src/main/java/opennlp/tools/disambiguator/Disambiguator.java
@@ -24,21 +24,29 @@ import opennlp.tools.util.Span;
import java.util.List;
/**
- * A word sense disambiguator that determines which sense of a word is meant in
- * a particular context. It is a classification task, where the classes are the
- * different senses of the ambiguous word. Disambiguation can be achieved in
- * either supervised or un-supervised approaches. A {@link Disambiguator} returns
- * a sense ID.
+ * Describes a word sense disambiguator that determines which sense of a word is
+ * meant in a particular context.
+ * It is a classification task, where the classes are the different senses of
+ * the ambiguous word. Disambiguation can be achieved in either supervised or
+ * un-supervised approaches. A {@link Disambiguator} returns a sense ID.
* <p>
* <b>How it works:</b><br/>
- * Just supply the context as an array of tokens and the
- * index of the target word to the disambiguate method.
+ * Just supply the {@code context} as an array of tokens and the index of the
+ * {@code target word} to the disambiguate method.
* <p>
- * Otherwise, for multiple words, you can set a word span instead of simply one
- * index. For the moment the source of sense definitions is from WordNet.
+ * Otherwise, for multiple words, you can set a word {@link Span} instead of
+ * a single target index.
*/
public interface Disambiguator {
+ /**
+ * Conducts disambiguation for a {@link WSDSample} context.
+ *
+ * @param sample The {@link WSDSample} containing the word and POS tags to use.
+ * @return The sense of the {@code sample} to disambiguate.
+ */
+ String disambiguate(WSDSample sample);
+
/**
* Conducts disambiguation for a single word located at {@code ambiguousTokenIndex}.
*
@@ -47,26 +55,27 @@ public interface Disambiguator {
* @param lemmas The lemmas of ALL the words in the context.
* @param ambiguousTokenIndex The index of the word to disambiguate.
* Must not be less or equal to zero.
- * @return The senses of the word to disambiguate.
+ * @return The sense of the word to disambiguate.
*/
String disambiguate(String[] tokenizedContext, String[] tokenTags,
String[] lemmas, int ambiguousTokenIndex);
/**
- * Conducts disambiguation for a single word located at {@code ambiguousTokenIndex}.
+ * Conducts disambiguation for all word located at {@code ambiguousTokenSpan}.
*
* @param tokenizedContext The text containing the word to disambiguate.
* @param tokenTags The tags corresponding to the context.
* @param lemmas The lemmas of ALL the words in the context.
* @param ambiguousTokenSpan The {@link Span} of the word(s) to disambiguate.
* Must not be {@code null}.
- * @return The senses of the word to disambiguate
+ * @return A List of senses, each corresponding to the senses of each word of
+ * the context which are to be disambiguated.
*/
List<String> disambiguate(String[] tokenizedContext, String[] tokenTags,
String[] lemmas, Span ambiguousTokenSpan);
/**
- * Conducts disambiguation for all the words of the context.
+ * Conducts disambiguation for all the words of the {@code tokenizedContext}.
*
* @param tokenizedContext The text containing the word to disambiguate.
* @param tokenTags The tags corresponding to the context.
@@ -77,12 +86,4 @@ public interface Disambiguator {
List<String> disambiguate(String[] tokenizedContext, String[] tokenTags,
String[] lemmas);
- /**
- * Conducts disambiguation for a {@link WSDSample} context.
- *
- * @param sample The {@link WSDSample} containing the word and POS tags to use.
- * @return The senses of the {@code sample} to disambiguate.
- */
- String disambiguate(WSDSample sample);
-
}
diff --git a/opennlp-wsd/src/main/java/opennlp/tools/disambiguator/FeaturesExtractor.java b/opennlp-wsd/src/main/java/opennlp/tools/disambiguator/FeaturesExtractor.java
index 3008297..2ce9fe6 100644
--- a/opennlp-wsd/src/main/java/opennlp/tools/disambiguator/FeaturesExtractor.java
+++ b/opennlp-wsd/src/main/java/opennlp/tools/disambiguator/FeaturesExtractor.java
@@ -40,9 +40,12 @@ import java.util.Map;
* </ul>
*
* The first methods serve to extract the features for the IMS algorithm. Three
- * families of features are to be extracted: - PoS of Surrounding Words: it
- * requires one parameter: "Window size" - Surrounding Words: no parameters are
- * required - Local Collocations: it requires one parameter: "the n-gram"
+ * families of features are to be extracted:
+ * <ul>
+ * <li>PoS of Surrounding Words: it requires one parameter: "Window size"</li>
+ * <li>Surrounding Words: no parameters are required</li>
+ * <li>Local Collocations: it requires one parameter: the "n-gram" number</li>
+ * </ul>
*
* @see WTDIMS
* @see <a href="https://aclanthology.org/P10-4014.pdf">
@@ -52,7 +55,7 @@ import java.util.Map;
public class FeaturesExtractor {
/*
- * Extracts POS tags of surrounding words of a given WTDIMS instance.
+ * Extracts POS tags of surrounding words of a given wordToDisambiguate instance.
*/
private String[] extractPosOfSurroundingWords(WTDIMS wordToDisambiguate, int windowSize) {
@@ -75,7 +78,7 @@ public class FeaturesExtractor {
}
/*
- * Extracts surrounding lemmas of a given WTDIMS instance.
+ * Extracts surrounding lemmas of a given wordToDisambiguate instance.
* Irrelevant stop words are skipped.
*/
private String[] extractSurroundingWords(WTDIMS wordToDisambiguate) {
@@ -131,13 +134,13 @@ public class FeaturesExtractor {
}
/**
- * Generates the full list of surrounding words, from the
- * training data. These data will be later used for the generation of the
- * features qualified of "Surrounding words".
+ * Generates the full list of surrounding words for the specified
+ * {@code trainingData}.
+ * These data will be used for the generation of features
+ * qualified for "Surrounding words".
*
- * @param trainingData
- * list of the training samples (type {@link WTDIMS}
- * @return the list of all the surrounding words from all the training data
+ * @param trainingData A list of the training samples (type {@link WTDIMS}.
+ * @return A list of all the surrounding words for the {@code trainingData}.
*/
public List<String> extractTrainingSurroundingWords(List<WTDIMS> trainingData) {
@@ -155,31 +158,43 @@ public class FeaturesExtractor {
}
/**
- * This method generates the different set of features related to the IMS
- * approach and store them in the corresponding attributes of the {@link WTDIMS}.
+ * Generates the different set of features related to the IMS
+ * approach and puts them in the corresponding attributes of
+ * the {@link WTDIMS word to disambiguate} object.
*
* @param wtd The {@link WTDIMS word to disambiguate}.
* @param windowSize The parameter required to generate the features qualified of
* "PoS of Surrounding Words".
* @param ngram The parameter required to generate the features qualified of
* "Local Collocations".
+ *
+ * @throws IllegalArgumentException Thrown if parameters were invalid.
*/
public void extractIMSFeatures(WTDIMS wtd, int windowSize, int ngram) {
+ if (wtd == null) {
+ throw new IllegalArgumentException("WTD must not be null");
+ }
wtd.setPosOfSurroundingWords(extractPosOfSurroundingWords(wtd, windowSize));
wtd.setSurroundingWords(extractSurroundingWords(wtd));
wtd.setLocalCollocations(extractLocalCollocations(wtd, ngram));
}
/**
- * This generates the context of IMS. It supposes that the features have
- * already been extracted and stored in the {@link WTDIMS} object, therefore it
- * doesn't require any parameters.
+ * Generates the context for the {@link WTDIMS word to disambiguate}.
+ *
+ * @implNote It is assumed that the features have already been extracted and
+ * wrapped in the {@link WTDIMS word to disambiguate}.
+ * Therefore, it doesn't require any parameters.
*
- * @param wtd The {@link WTDIMS wtd to disambiguate}.
+ * @param wtd The {@link WTDIMS word to disambiguate}.
* @param listSurrWords The full list of surrounding words of the training data.
+ *
+ * @throws IllegalArgumentException Thrown if parameters were invalid.
*/
public void serializeIMSFeatures(WTDIMS wtd, List<String> listSurrWords) {
-
+ if (wtd == null) {
+ throw new IllegalArgumentException("WTD must not be null");
+ }
String[] posOfSurroundingWords = wtd.getPosOfSurroundingWords();
List<String> surroundingWords = new ArrayList<>(
Arrays.asList(wtd.getSurroundingWords()));
diff --git a/opennlp-wsd/src/main/java/opennlp/tools/disambiguator/IMSWSDContextGenerator.java b/opennlp-wsd/src/main/java/opennlp/tools/disambiguator/IMSWSDContextGenerator.java
index fe89933..76d50c8 100644
--- a/opennlp-wsd/src/main/java/opennlp/tools/disambiguator/IMSWSDContextGenerator.java
+++ b/opennlp-wsd/src/main/java/opennlp/tools/disambiguator/IMSWSDContextGenerator.java
@@ -24,12 +24,17 @@ import java.util.List;
import java.util.Set;
/**
- * The default Context Generator of the IMS approach.
+ * The default Context Generator of the
+ * <a href="https://aclanthology.org/P10-4014.pdf"> IMS (It Makes Sense)</a> approach.
*
* @see WSDContextGenerator
*/
public class IMSWSDContextGenerator implements WSDContextGenerator {
+ /*
+ * Extracts POS tags of surrounding words for the word at the specified index
+ * within the windowSize.
+ */
private String[] extractPosOfSurroundingWords(int index, String[] tags, int windowSize) {
String[] windowTags = new String[2 * windowSize + 1];
@@ -96,6 +101,9 @@ public class IMSWSDContextGenerator implements WSDContextGenerator {
return res;
}
+ /**
+ * {@inheritDoc}
+ */
@Override
public String[] getContext(int index, String[] tokens,
String[] tags, String[] lemmas, int ngram, int windowSize, List<String> model) {
@@ -131,6 +139,9 @@ public class IMSWSDContextGenerator implements WSDContextGenerator {
return serializedFeatures;
}
+ /**
+ * {@inheritDoc}
+ */
@Override
public String[] getContext(WSDSample sample, int ngram, int windowSize,
List<String> model) {
diff --git a/opennlp-wsd/src/main/java/opennlp/tools/disambiguator/IMSWSDSequenceValidator.java b/opennlp-wsd/src/main/java/opennlp/tools/disambiguator/IMSWSDSequenceValidator.java
index 0818447..c910fea 100644
--- a/opennlp-wsd/src/main/java/opennlp/tools/disambiguator/IMSWSDSequenceValidator.java
+++ b/opennlp-wsd/src/main/java/opennlp/tools/disambiguator/IMSWSDSequenceValidator.java
@@ -17,6 +17,10 @@
package opennlp.tools.disambiguator;
+/**
+ * A {@link opennlp.tools.util.SequenceValidator} variant to check whether
+ * IMS-based sequence outcomes are valid or not.
+ */
public class IMSWSDSequenceValidator {
private boolean validOutcome(String outcome, String prevOutcome) {
@@ -43,6 +47,15 @@ public class IMSWSDSequenceValidator {
return validOutcome(outcome, prevOutcome);
}
+ /**
+ * Validates the provided {@code outcome} is valid in the context of
+ * the sequence {@code s}.
+ *
+ * @param outcome The candidate result to check.
+ * @param s The tokens that cover the sequence {@code outcome}
+ * shall be valid for.
+ * @return {@code True} if {@code outcome} is valid, {@code false} otherwise.
+ */
public boolean validSequence(String outcome, String[] s) {
return validOutcome(outcome, s);
}
diff --git a/opennlp-wsd/src/main/java/opennlp/tools/disambiguator/Lesk.java b/opennlp-wsd/src/main/java/opennlp/tools/disambiguator/Lesk.java
index 19e7ac7..ea2a8e4 100644
--- a/opennlp-wsd/src/main/java/opennlp/tools/disambiguator/Lesk.java
+++ b/opennlp-wsd/src/main/java/opennlp/tools/disambiguator/Lesk.java
@@ -36,7 +36,22 @@ import opennlp.tools.tokenize.Tokenizer;
* The main idea is to check for word overlaps in the sense definitions
* of the surrounding context. An overlap is when two words have similar stems.
* The more overlaps a word has the higher its score. Different variations of
- * the approach are included in this class.
+ * the approach are included in this class, as defined in {@link LeskParameters.LeskType}.
+ * <p>
+ * Ten features are possible for Lesk.
+ * <ul>
+ * <li>0: Synonyms</li>
+ * <li>1: Hypernyms</li>
+ * <li>2: Hyponyms</li>
+ * <li>3: Meronyms</li>
+ * <li>4: Holonyms</li>
+ * <li>5: Entailments</li>
+ * <li>6: Coordinate Terms</li>
+ * <li>7: Causes</li>
+ * <li>8: Attributes</li>
+ * <li>9: Pertainyms</li>
+ * </ul>
+ * Those are defined via {@link LeskParameters#features}.
*
* @see Disambiguator
* @see LeskParameters
@@ -90,7 +105,7 @@ public class Lesk extends AbstractWSDisambiguator {
if (params.areValid()) {
this.params = (LeskParameters) params;
} else {
- throw new IllegalArgumentException("wrong params");
+ throw new IllegalArgumentException("Detected incorrect LeskParameter values!");
}
}
}
@@ -105,10 +120,9 @@ public class Lesk extends AbstractWSDisambiguator {
/**
* The basic Lesk method where the entire context is considered for overlaps
- *
- * @param sample
- * the word sample to disambiguate
- * @return The array of WordSenses with their scores
+ *
+ * @param sample The {@link WSDSample} to disambiguate.
+ * @return The list of {@link WordSense word senses} with their scores.
*/
public List<WordSense> basic(WSDSample sample) {
@@ -150,10 +164,9 @@ public class Lesk extends AbstractWSDisambiguator {
/**
* The basic Lesk method but applied to a default context windows
- *
- * @param sample
- * the word sample to disambiguate
- * @return The array of WordSenses with their scores
+ *
+ * @param sample The {@link WSDSample} to disambiguate.
+ * @return The list of {@link WordSense word senses} with their scores.
*/
public List<WordSense> basicContextual(WSDSample sample) {
@@ -207,10 +220,9 @@ public class Lesk extends AbstractWSDisambiguator {
* An extended version of the Lesk approach that takes into consideration
* semantically related feature overlaps across the entire context The scoring
* function uses linear weights.
- *
- * @param sample
- * the word sample to disambiguate
- * @return the list of WordSenses with their scores
+ *
+ * @param sample The {@link WSDSample} to disambiguate.
+ * @return The list of {@link WordSense word senses} with their scores.
*/
public List<WordSense> extended(WSDSample sample) {
params.setWinBSize(0);
@@ -222,10 +234,9 @@ public class Lesk extends AbstractWSDisambiguator {
* An extended version of the Lesk approach that takes into consideration
* semantically related feature overlaps in a default context window The
* scoring function uses linear weights.
- *
- * @param sample
- * the word sample to disambiguate
- * @return the list of WordSenses with their scores
+ *
+ * @param sample The {@link WSDSample} to disambiguate.
+ * @return The list of {@link WordSense word senses} with their scores.
*/
public List<WordSense> extendedContextual(WSDSample sample) {
List<WordSense> scoredSenses;
@@ -234,81 +245,65 @@ public class Lesk extends AbstractWSDisambiguator {
} else {
scoredSenses = basicContextual(sample);
}
- for (WordSense wordSense : scoredSenses) {
-
- if (getParams().getFeatures()[0]) {
- wordSense.setScore(wordSense.getScore() + getParams().depth_weight
- * assessSynonyms(wordSense.getNode().getSynonyms(), contextWords));
+ for (WordSense ws : scoredSenses) {
+ final SynNode synNode = ws.getNode();
+ final Synset synset = synNode.synset;
+ if (params.getFeatures()[0]) {
+ ws.setScore(ws.getScore() + params.depth_weight
+ * assessSynonyms(synNode.getSynonyms(), contextWords));
}
-
- if (getParams().getFeatures()[1]) {
- fathomHypernyms(wordSense, wordSense.getNode().synset, contextWords,
+ if (params.getFeatures()[1]) {
+ fathomHypernyms(ws, synset, contextWords,
params.depth, params.depth, params.depth_weight);
}
-
- if (getParams().getFeatures()[2]) {
- fathomHyponyms(wordSense, wordSense.getNode().synset, contextWords,
+ if (params.getFeatures()[2]) {
+ fathomHyponyms(ws, synset, contextWords,
params.depth, params.depth, params.depth_weight);
}
-
- if (getParams().getFeatures()[3]) {
- fathomMeronyms(wordSense, wordSense.getNode().synset, contextWords,
+ if (params.getFeatures()[3]) {
+ fathomMeronyms(ws, synset, contextWords,
params.depth, params.depth, params.depth_weight);
-
}
-
- if (getParams().getFeatures()[4]) {
- fathomHolonyms(wordSense, wordSense.getNode().synset, contextWords,
+ if (params.getFeatures()[4]) {
+ fathomHolonyms(ws, synset, contextWords,
params.depth, params.depth, params.depth_weight);
-
}
-
- if (getParams().getFeatures()[5]) {
- fathomEntailments(wordSense, wordSense.getNode().synset, contextWords,
+ if (params.getFeatures()[5]) {
+ fathomEntailments(ws, synset, contextWords,
params.depth, params.depth, params.depth_weight);
-
}
- if (getParams().getFeatures()[6]) {
- fathomCoordinateTerms(wordSense, wordSense.getNode().synset,
+ if (params.getFeatures()[6]) {
+ fathomCoordinateTerms(ws, synset,
contextWords, params.depth, params.depth, params.depth_weight);
-
}
- if (getParams().getFeatures()[7]) {
- fathomCauses(wordSense, wordSense.getNode().synset, contextWords,
+ if (params.getFeatures()[7]) {
+ fathomCauses(ws, synset, contextWords,
params.depth, params.depth, params.depth_weight);
-
}
- if (getParams().getFeatures()[8]) {
- fathomAttributes(wordSense, wordSense.getNode().synset, contextWords,
+ if (params.getFeatures()[8]) {
+ fathomAttributes(ws, synset, contextWords,
params.depth, params.depth, params.depth_weight);
-
}
- if (getParams().getFeatures()[9]) {
- fathomPertainyms(wordSense, wordSense.getNode().synset, contextWords,
+ if (params.getFeatures()[9]) {
+ fathomPertainyms(ws, synset, contextWords,
params.depth, params.depth, params.depth_weight);
-
}
-
}
-
return scoredSenses;
-
}
/**
* An extended version of the Lesk approach that takes into consideration
* semantically related feature overlaps in all the context. The scoring
* function uses exponential weights.
- *
- * @param sample the word sample to disambiguate
- *
- * @return A list of {@link WordSense word senses} with their scores.
+ *
+ * @param sample The {@link WSDSample} to disambiguate.
+ * @return The list of {@link WordSense word senses} with their scores.
*/
public List<WordSense> extendedExponential(WSDSample sample) {
params.setWinBSize(0);
params.setWinFSize(0);
return extendedExponentialContextual(sample);
-
}
/**
@@ -316,9 +311,8 @@ public class Lesk extends AbstractWSDisambiguator {
* semantically related feature overlaps in a custom window in the context.
* The scoring function uses exponential weights.
*
- * @param sample
- * the word sample to disambiguate
- * @return the list of WordSenses with their scores
+ * @param sample The {@link WSDSample} to disambiguate.
+ * @return The list of {@link WordSense word senses} with their scores.
*/
public List<WordSense> extendedExponentialContextual(WSDSample sample) {
List<WordSense> scoredSenses;
@@ -328,74 +322,53 @@ public class Lesk extends AbstractWSDisambiguator {
scoredSenses = basicContextual(sample);
}
- for (WordSense wordSense : scoredSenses) {
-
+ for (WordSense ws : scoredSenses) {
+ final SynNode synNode = ws.getNode();
+ final Synset synset = synNode.synset;
if (params.features[0]) {
- wordSense.setScore(wordSense.getScore() + Math.pow(
- assessSynonyms(wordSense.getNode().getSynonyms(), contextWords),
- params.iexp));
+ ws.setScore(ws.getScore() + Math.pow(assessSynonyms(
+ synNode.getSynonyms(), contextWords), params.iexp));
}
-
if (params.features[1]) {
- fathomHypernymsExponential(wordSense, wordSense.getNode().synset,
- contextWords, params.depth, params.depth, params.iexp, params.dexp);
+ fathomHypernymsExponential(ws, synset, contextWords,
+ params.depth, params.depth, params.iexp, params.dexp);
}
-
if (params.features[2]) {
- fathomHyponymsExponential(wordSense, wordSense.getNode().synset,
- contextWords, params.depth, params.depth, params.iexp, params.dexp);
+ fathomHyponymsExponential(ws, synset, contextWords,
+ params.depth, params.depth, params.iexp, params.dexp);
}
-
if (params.features[3]) {
- fathomMeronymsExponential(wordSense, wordSense.getNode().synset,
- contextWords, params.depth, params.depth, params.iexp, params.dexp);
-
+ fathomMeronymsExponential(ws, synset, contextWords,
+ params.depth, params.depth, params.iexp, params.dexp);
}
-
if (params.features[4]) {
- fathomHolonymsExponential(wordSense, wordSense.getNode().synset,
- contextWords, params.depth, params.depth, params.iexp, params.dexp);
-
+ fathomHolonymsExponential(ws, synset, contextWords,
+ params.depth, params.depth, params.iexp, params.dexp);
}
-
if (params.features[5]) {
- fathomEntailmentsExponential(wordSense, wordSense.getNode().synset,
- contextWords, params.depth, params.depth, params.iexp, params.dexp);
+ fathomEntailmentsExponential(ws, synset, contextWords,
+ params.depth, params.depth, params.iexp, params.dexp);
}
-
if (params.features[6]) {
- fathomCoordinateTermsExponential(wordSense, wordSense.getNode().synset,
- contextWords, params.depth, params.depth, params.iexp, params.dexp);
-
+ fathomCoordinateTermsExponential(ws, synset, contextWords,
+ params.depth, params.depth, params.iexp, params.dexp);
}
if (params.features[7]) {
- fathomCausesExponential(wordSense, wordSense.getNode().synset,
- contextWords, params.depth, params.depth, params.iexp, params.dexp);
-
+ fathomCausesExponential(ws, synset, contextWords,
+ params.depth, params.depth, params.iexp, params.dexp);
}
if (params.features[8]) {
- fathomAttributesExponential(wordSense, wordSense.getNode().synset,
- contextWords, params.depth, params.depth, params.iexp, params.dexp);
-
+ fathomAttributesExponential(ws, synset, contextWords,
+ params.depth, params.depth, params.iexp, params.dexp);
}
if (params.features[9]) {
- fathomPertainymsExponential(wordSense, wordSense.getNode().synset,
- contextWords, params.depth, params.depth, params.iexp, params.dexp);
+ fathomPertainymsExponential(ws, synset, contextWords,
+ params.depth, params.depth, params.iexp, params.dexp);
}
}
return scoredSenses;
}
- /**
- * Recursively score the hypernym tree linearly.
- *
- * @param wordSense
- * @param child
- * @param relvWords
- * @param depth
- * @param maxDepth
- * @param depthScoreWeight
- */
private void fathomHypernyms(WordSense wordSense, Synset child, List<WordPOS> relvWords,
int depth, int maxDepth, double depthScoreWeight) {
if (depth == 0)
@@ -415,17 +388,6 @@ public class Lesk extends AbstractWSDisambiguator {
}
}
- /**
- * Recursively score the hypernym tree exponentially.
- *
- * @param wordSense
- * @param child
- * @param relvWords
- * @param depth
- * @param maxDepth
- * @param intersectionExponent
- * @param depthScoreExponent
- */
private void fathomHypernymsExponential(WordSense wordSense, Synset child, List<WordPOS> relvWords,
int depth, int maxDepth, double intersectionExponent,
double depthScoreExponent) {
@@ -446,16 +408,6 @@ public class Lesk extends AbstractWSDisambiguator {
}
}
- /**
- * Recursively score the hyponym tree linearly.
- *
- * @param wordSense
- * @param child
- * @param relvWords
- * @param depth
- * @param maxDepth
- * @param depthScoreWeight
- */
private void fathomHyponyms(WordSense wordSense, Synset child, List<WordPOS> relvWords,
int depth, int maxDepth, double depthScoreWeight) {
if (depth == 0)
@@ -476,17 +428,6 @@ public class Lesk extends AbstractWSDisambiguator {
}
}
- /**
- * Recursively score the hyponym tree exponentially.
- *
- * @param wordSense
- * @param child
- * @param relvWords
- * @param depth
- * @param maxDepth
- * @param intersectionExponent
- * @param depthScoreExponent
- */
private void fathomHyponymsExponential(WordSense wordSense, Synset child, List<WordPOS> relvWords,
int depth, int maxDepth, double intersectionExponent, double depthScoreExponent) {
if (depth == 0)
@@ -508,16 +449,6 @@ public class Lesk extends AbstractWSDisambiguator {
}
}
- /**
- * Recursively score the meronym tree linearly.
- *
- * @param wordSense
- * @param child
- * @param relvWords
- * @param depth
- * @param maxDepth
- * @param depthScoreWeight
- */
private void fathomMeronyms(WordSense wordSense, Synset child, List<WordPOS> relvWords,
int depth, int maxDepth, double depthScoreWeight) {
if (depth == 0)
@@ -539,17 +470,6 @@ public class Lesk extends AbstractWSDisambiguator {
}
}
- /**
- * Recursively score the meronym tree exponentially.
- *
- * @param wordSense
- * @param child
- * @param relvWords
- * @param depth
- * @param maxDepth
- * @param intersectionExponent
- * @param depthScoreExponent
- */
private void fathomMeronymsExponential(WordSense wordSense, Synset child, List<WordPOS> relvWords,
int depth, int maxDepth, double intersectionExponent, double depthScoreExponent) {
if (depth == 0)
@@ -569,16 +489,6 @@ public class Lesk extends AbstractWSDisambiguator {
}
}
- /**
- * Recursively score the holonym tree linearly.
- *
- * @param wordSense
- * @param child
- * @param relvWords
- * @param depth
- * @param maxDepth
- * @param depthScoreWeight
- */
private void fathomHolonyms(WordSense wordSense, Synset child, List<WordPOS> relvWords,
int depth, int maxDepth, double depthScoreWeight) {
if (depth == 0)
@@ -598,17 +508,6 @@ public class Lesk extends AbstractWSDisambiguator {
}
}
- /**
- * Recursively score the holonym tree exponentially.
- *
- * @param wordSense
- * @param child
- * @param relvWords
- * @param depth
- * @param maxDepth
- * @param intersectionExponent
- * @param depthScoreExponent
- */
private void fathomHolonymsExponential(WordSense wordSense, Synset child, List<WordPOS> relvWords,
int depth, int maxDepth, double intersectionExponent, double depthScoreExponent) {
if (depth == 0)
@@ -829,7 +728,7 @@ public class Lesk extends AbstractWSDisambiguator {
}
- /**
+ /*
* Checks if the feature should be counted in the score.
*
* @param featureSynsets
@@ -839,7 +738,7 @@ public class Lesk extends AbstractWSDisambiguator {
private int assessFeature(List<Synset> featureSynsets, List<WordPOS> relevantWords) {
int count = 0;
for (Synset synset : featureSynsets) {
- SynNode subNode = new SynNode(synset, relevantWords);
+ final SynNode subNode = new SynNode(synset, relevantWords);
String[] tokenizedSense = tokenizer.tokenize(subNode.getGloss());
List<WordPOS> relvSenseWords = WSDHelper.getAllRelevantWords(tokenizedSense);
@@ -855,7 +754,7 @@ public class Lesk extends AbstractWSDisambiguator {
return count;
}
- /**
+ /*
* Checks if the synonyms should be counted in the score.
*
* @param synonyms
diff --git a/opennlp-wsd/src/main/java/opennlp/tools/disambiguator/LeskParameters.java b/opennlp-wsd/src/main/java/opennlp/tools/disambiguator/LeskParameters.java
index a3d275f..deaba4f 100644
--- a/opennlp-wsd/src/main/java/opennlp/tools/disambiguator/LeskParameters.java
+++ b/opennlp-wsd/src/main/java/opennlp/tools/disambiguator/LeskParameters.java
@@ -20,14 +20,14 @@
package opennlp.tools.disambiguator;
/**
- * Lesk specific parameter set.
+ * Lesk specific {@link WSDParameters parameter set}.
*
* @see WSDParameters
*/
public class LeskParameters extends WSDParameters {
/**
- * Enum of all types of implemented variations of Lesk
+ * Enum of all types of implemented variations of Lesk.
*/
public enum LeskType {
LESK_BASIC, LESK_BASIC_CTXT, LESK_EXT, LESK_EXT_CTXT, LESK_EXT_EXP, LESK_EXT_EXP_CTXT
@@ -77,7 +77,7 @@ public class LeskParameters extends WSDParameters {
return type;
}
- public void setType(LeskType type) {
+ void setType(LeskType type) {
this.type = type;
}
@@ -85,7 +85,7 @@ public class LeskParameters extends WSDParameters {
return winFSize;
}
- public void setWinFSize(int winFSize) {
+ void setWinFSize(int winFSize) {
this.winFSize = winFSize;
}
@@ -93,7 +93,7 @@ public class LeskParameters extends WSDParameters {
return winBSize;
}
- public void setWinBSize(int winBSize) {
+ void setWinBSize(int winBSize) {
this.winBSize = winBSize;
}
@@ -101,7 +101,7 @@ public class LeskParameters extends WSDParameters {
return depth;
}
- public void setDepth(int depth) {
+ void setDepth(int depth) {
this.depth = depth;
}
@@ -109,7 +109,7 @@ public class LeskParameters extends WSDParameters {
return depth_weight;
}
- public void setDepth_weight(double depth_weight) {
+ void setDepth_weight(double depth_weight) {
this.depth_weight = depth_weight;
}
@@ -117,7 +117,7 @@ public class LeskParameters extends WSDParameters {
return iexp;
}
- public void setIexp(double iexp) {
+ void setIexp(double iexp) {
this.iexp = iexp;
}
@@ -125,7 +125,7 @@ public class LeskParameters extends WSDParameters {
return dexp;
}
- public void setDexp(double dexp) {
+ void setDexp(double dexp) {
this.dexp = dexp;
}
@@ -138,7 +138,7 @@ public class LeskParameters extends WSDParameters {
}
/**
- * Sets default parameters
+ * Activates default Lesk feature parameters.
*/
void setDefaults() {
setType(LeskParameters.DFLT_LESK_TYPE);
@@ -153,6 +153,9 @@ public class LeskParameters extends WSDParameters {
{ true, true, true, true, true, true, true, true, true, true };
}
+ /**
+ * {@inheritDoc}
+ */
@Override
public boolean areValid() {
diff --git a/opennlp-wsd/src/main/java/opennlp/tools/disambiguator/MFS.java b/opennlp-wsd/src/main/java/opennlp/tools/disambiguator/MFS.java
index 966c3a5..1d51f3b 100644
--- a/opennlp-wsd/src/main/java/opennlp/tools/disambiguator/MFS.java
+++ b/opennlp-wsd/src/main/java/opennlp/tools/disambiguator/MFS.java
@@ -42,10 +42,6 @@ public class MFS extends AbstractWSDisambiguator {
public static final String NONESENSE = "nonesense";
- public MFS() {
- super();
- }
-
/**
* Extracts the most frequent sense for a specified {@link WSDSample}.
*
diff --git a/opennlp-wsd/src/main/java/opennlp/tools/disambiguator/SynNode.java b/opennlp-wsd/src/main/java/opennlp/tools/disambiguator/SynNode.java
index 28517fb..87641a0 100644
--- a/opennlp-wsd/src/main/java/opennlp/tools/disambiguator/SynNode.java
+++ b/opennlp-wsd/src/main/java/opennlp/tools/disambiguator/SynNode.java
@@ -34,6 +34,9 @@ import opennlp.tools.tokenize.Tokenizer;
/**
* Convenience class to access some features via {@link Synset synsets}.
+ * A {@link Synset} represents a concept, and contains a set of words, each of which
+ * has a sense for that concept. Each element is thus synonymous with the other
+ * words contained in the Synset.
*
* @see Synset
*/
@@ -80,6 +83,9 @@ public class SynNode {
this.parent = parent;
}
+ /**
+ * @return Retrieves the associated {@link WordPOS elements}.
+ */
public List<WordPOS> getSenseRelevantWords() {
return senseRelevantWords;
}
@@ -246,10 +252,10 @@ public class SynNode {
}
/**
- * Gets the senses of the nodes
+ * Retrieves associated {@link WordSense senses} for specified {@code nodes}.
*
- * @param nodes
- * @return senses from the nodes
+ * @param nodes A list of {@link SynNode nodes} to score.
+ * @return The {@link WordSense senses} obtained for the {@code nodes}.
*/
public static List<WordSense> updateSenses(List<SynNode> nodes) {
List<WordSense> scoredSenses = new ArrayList<>();
@@ -262,6 +268,5 @@ public class SynNode {
scoredSenses.add(wordSense);
}
return scoredSenses;
-
}
}
diff --git a/opennlp-wsd/src/main/java/opennlp/tools/disambiguator/WSDContextGenerator.java b/opennlp-wsd/src/main/java/opennlp/tools/disambiguator/WSDContextGenerator.java
index 14ba92f..10581ed 100644
--- a/opennlp-wsd/src/main/java/opennlp/tools/disambiguator/WSDContextGenerator.java
+++ b/opennlp-wsd/src/main/java/opennlp/tools/disambiguator/WSDContextGenerator.java
@@ -23,7 +23,7 @@ import java.util.List;
import java.util.regex.Pattern;
/**
- * Interface for {@link AbstractWSDisambiguator} context generators.
+ * Describes a context generator for word sense disambiguation.
*/
public interface WSDContextGenerator {
@@ -39,7 +39,7 @@ public interface WSDContextGenerator {
* @param ngram The ngram to consider for context. Must be greater than {@code 0}.
* @param windowSize The context window. Must be greater than {@code 0}.
* @param model The list of unigrams.
- * @return The IMS context of the word to disambiguate.
+ * @return The context of the word to disambiguate at {@code index} in {@code toks}.
*/
String[] getContext(int index, String[] toks, String[] tags, String[] lemmas,
int ngram, int windowSize, List<String> model);
@@ -51,7 +51,7 @@ public interface WSDContextGenerator {
* @param ngram The ngram to consider for context. Must be greater than {@code 0}.
* @param windowSize The context window. Must be greater than {@code 0}.
* @param model The list of unigrams.
- * @return The IMS context of the word to disambiguate.
+ * @return The context of the word to disambiguate at {@code index} in {@code sample}.
*/
String[] getContext(WSDSample sample, int ngram, int windowSize, List<String> model);
diff --git a/opennlp-wsd/src/main/java/opennlp/tools/disambiguator/WSDDefaultParameters.java b/opennlp-wsd/src/main/java/opennlp/tools/disambiguator/WSDDefaultParameters.java
index 9f6c28f..5fce6df 100644
--- a/opennlp-wsd/src/main/java/opennlp/tools/disambiguator/WSDDefaultParameters.java
+++ b/opennlp-wsd/src/main/java/opennlp/tools/disambiguator/WSDDefaultParameters.java
@@ -23,32 +23,35 @@ import java.io.File;
import java.nio.file.Path;
/**
- * This class contains the parameters for the IMS approach as well as the
+ * Defines the parameters for the <a href="https://aclanthology.org/P10-4014.pdf">
+ * IMS (It Makes Sense)</a> approach, as well as the
* directories containing the files used
+ *
+ * @see WSDParameters
*/
public class WSDDefaultParameters extends WSDParameters {
- protected String languageCode;
- protected int windowSize;
- protected int ngram;
+ public static final int DFLT_WIN_SIZE = 3;
+ public static final int DFLT_NGRAM = 2;
+ public static final String DFLT_LANG_CODE = "en";
+ public static final SenseSource DFLT_SOURCE = SenseSource.WORDNET;
- protected Path trainingDataDir;
+ private final Path trainingDataDir;
- protected static final int DFLT_WIN_SIZE = 3;
- protected static final int DFLT_NGRAM = 2;
- protected static final String DFLT_LANG_CODE = "en";
- protected static final SenseSource DFLT_SOURCE = SenseSource.WORDNET;
+ private final String languageCode;
+ protected int windowSize;
+ protected int ngram;
/**
* Initializes a new set of {@link WSDDefaultParameters}.
- * The default language used is <i>English</i>.
+ * The default language used is '<i>en</i>' (English).
*
- * @param windowSize the size of the window used for the extraction of the features
- * qualified of Surrounding Words
- * @param ngram the number words used for the extraction of features qualified of
- * Local Collocations
- * @param senseSource the source of the training data
- * @param trainingDataDir The {@link Path} where to place or lookup trained models.
+ * @param windowSize The size of the window used for the extraction of the features
+ * qualified of Surrounding Words.
+ * @param ngram The number words used for the extraction of features qualified of
+ * Local Collocations.
+ * @param senseSource The {@link SenseSource source} of the training data
+ * @param trainingDataDir The {@link Path} where to store or read trained models from.
*/
public WSDDefaultParameters(int windowSize, int ngram, SenseSource senseSource, Path trainingDataDir) {
this.languageCode = DFLT_LANG_CODE;
@@ -65,8 +68,10 @@ public class WSDDefaultParameters extends WSDParameters {
/**
* Initializes a new set of {@link WSDDefaultParameters}.
- * The default language used is <i>English</i>, the window size is {@link #DFLT_WIN_SIZE},
+ * The default language used is '<i>en</i>' (English), the window size is {@link #DFLT_WIN_SIZE},
* and the ngram length is initialized as {@link #DFLT_NGRAM}.
+ *
+ * @implNote The training directory will be unset.
*/
public WSDDefaultParameters() {
this(DFLT_WIN_SIZE, DFLT_NGRAM, DFLT_SOURCE, null);
@@ -74,7 +79,7 @@ public class WSDDefaultParameters extends WSDParameters {
/**
* Initializes a new set of {@link WSDDefaultParameters}.
- * The default language used is <i>English</i>, the window size is {@link #DFLT_WIN_SIZE},
+ * The default language used is '<i>en</i>' (English), the window size is {@link #DFLT_WIN_SIZE},
* and the ngram length is initialized as {@link #DFLT_NGRAM}.
*
* @param trainingDataDir The {@link Path} where to place or lookup trained models.
@@ -95,10 +100,16 @@ public class WSDDefaultParameters extends WSDParameters {
return ngram;
}
+ /**
+ * @return The {@link Path} where to place or lookup trained models. May be {@code null}!
+ */
public Path getTrainingDataDirectory() {
return trainingDataDir;
}
+ /**
+ * {@inheritDoc}
+ */
@Override
public boolean areValid() {
return true;
diff --git a/opennlp-wsd/src/main/java/opennlp/tools/disambiguator/WSDEvaluationMonitor.java b/opennlp-wsd/src/main/java/opennlp/tools/disambiguator/WSDEvaluationMonitor.java
index ddc2cac..1775e5c 100644
--- a/opennlp-wsd/src/main/java/opennlp/tools/disambiguator/WSDEvaluationMonitor.java
+++ b/opennlp-wsd/src/main/java/opennlp/tools/disambiguator/WSDEvaluationMonitor.java
@@ -20,7 +20,10 @@ package opennlp.tools.disambiguator;
import opennlp.tools.util.eval.EvaluationMonitor;
/**
- * A marker interface for evaluating {@link AbstractWSDisambiguator disambiguators}.
+ * A marker interface for evaluating {@link Disambiguator disambiguators}.
+ *
+ * @see WSDSample
+ * @see EvaluationMonitor
*/
public interface WSDEvaluationMonitor extends EvaluationMonitor<WSDSample> {
diff --git a/opennlp-wsd/src/main/java/opennlp/tools/disambiguator/WSDEvaluator.java b/opennlp-wsd/src/main/java/opennlp/tools/disambiguator/WSDEvaluator.java
index 6b71c79..4e0d502 100644
--- a/opennlp-wsd/src/main/java/opennlp/tools/disambiguator/WSDEvaluator.java
+++ b/opennlp-wsd/src/main/java/opennlp/tools/disambiguator/WSDEvaluator.java
@@ -43,18 +43,19 @@ public class WSDEvaluator extends Evaluator<WSDSample> {
private final Disambiguator disambiguator;
/**
- * Initializes the current instance with the given {@link AbstractWSDisambiguator}.
+ * Initializes a {@link WSDEvaluator} with the given {@link Disambiguator}.
*
- * @param disambiguator
- * the {@link AbstractWSDisambiguator} to evaluate.
- * @param listeners
- * evaluation sample listeners
+ * @param disambiguator The {@link Disambiguator} to evaluate.
+ * @param listeners The (optional) {@link WSDEvaluationMonitor evaluation sample listeners}.
*/
public WSDEvaluator(Disambiguator disambiguator, WSDEvaluationMonitor... listeners) {
super(listeners);
this.disambiguator = disambiguator;
}
+ /**
+ * {@inheritDoc}
+ */
@Override
protected WSDSample processSample(WSDSample ref) {
@@ -82,20 +83,16 @@ public class WSDEvaluator extends Evaluator<WSDSample> {
}
/**
- * Retrieves the WSD accuracy.
- * <p>
- * This is defined as: WSD accuracy = correctly disambiguated / total words
+ * @implNote WSD accuracy = correctly disambiguated / total words
*
- * @return the WSD accuracy
+ * @return Retrieves the WSD accuracy.
*/
public double getAccuracy() {
return accuracy.mean();
}
/**
- * Retrieves the total number of words considered in the evaluation.
- *
- * @return the word count
+ * @return Retrieves the total number of words considered in the evaluation
*/
public long getWordCount() {
return accuracy.count();
diff --git a/opennlp-wsd/src/main/java/opennlp/tools/disambiguator/WSDHelper.java b/opennlp-wsd/src/main/java/opennlp/tools/disambiguator/WSDHelper.java
index d462947..3613c0d 100644
--- a/opennlp-wsd/src/main/java/opennlp/tools/disambiguator/WSDHelper.java
+++ b/opennlp-wsd/src/main/java/opennlp/tools/disambiguator/WSDHelper.java
@@ -42,6 +42,10 @@ import opennlp.tools.tokenize.ThreadSafeTokenizerME;
import opennlp.tools.tokenize.Tokenizer;
import opennlp.tools.util.DownloadUtil;
+/**
+ * A helper class that loads and organizes resources, and provides helper methods
+ * to avoid multiple copies of dealing with certain resources.
+ */
public class WSDHelper {
private static final Logger LOG = LoggerFactory.getLogger(WSDHelper.class);
diff --git a/opennlp-wsd/src/main/java/opennlp/tools/disambiguator/WSDModel.java b/opennlp-wsd/src/main/java/opennlp/tools/disambiguator/WSDModel.java
index 984c41b..87bc3d2 100644
--- a/opennlp-wsd/src/main/java/opennlp/tools/disambiguator/WSDModel.java
+++ b/opennlp-wsd/src/main/java/opennlp/tools/disambiguator/WSDModel.java
@@ -159,11 +159,17 @@ public class WSDModel extends BaseModel {
return getManifestProperty(WORDTAG);
}
+ /**
+ * {@inheritDoc}
+ */
@Override
protected Class<? extends BaseToolFactory> getDefaultFactory() {
return WSDisambiguatorFactory.class;
}
+ /**
+ * {@inheritDoc}
+ */
@Override
protected void validateArtifactMap() throws InvalidFormatException {
super.validateArtifactMap();
@@ -186,11 +192,17 @@ public class WSDModel extends BaseModel {
this.contextEntries = Arrays.asList(surroundings.split(","));
}
+ /**
+ * {@inheritDoc}
+ */
@Override
public int hashCode() {
return Objects.hash(artifactMap.get(MANIFEST_ENTRY), artifactMap.get(WSD_MODEL_ENTRY));
}
+ /**
+ * {@inheritDoc}
+ */
@Override
public boolean equals(Object obj) {
if (obj == this) {
diff --git a/opennlp-wsd/src/main/java/opennlp/tools/disambiguator/WSDParameters.java b/opennlp-wsd/src/main/java/opennlp/tools/disambiguator/WSDParameters.java
index 36f0abf..912f6a5 100644
--- a/opennlp-wsd/src/main/java/opennlp/tools/disambiguator/WSDParameters.java
+++ b/opennlp-wsd/src/main/java/opennlp/tools/disambiguator/WSDParameters.java
@@ -20,8 +20,7 @@
package opennlp.tools.disambiguator;
/**
- * Disambiguation Parameters
- *
+ * Describes a set of parameters to configure word sense disambiguation.
*/
public abstract class WSDParameters {
@@ -32,19 +31,24 @@ public abstract class WSDParameters {
protected SenseSource senseSource;
/**
- * @return if the disambiguation type is coarse grained or fine-grained
+ * Initializes a default set of {@link WSDParameters} and chooses
+ * the {@link SenseSource#WORDNET} by default.
*/
+ public WSDParameters() {
+ this.senseSource = SenseSource.WORDNET;
+ }
+ /**
+ * @return if the disambiguation type is coarse grained or fine-grained
+ */
public SenseSource getSenseSource() {
return senseSource;
}
- public WSDParameters() {
- this.senseSource = SenseSource.WORDNET;
- }
-
- /*
- * @return checks if the parameters are valid or not
+ /**
+ * Checks if the parameters are valid or not.
+ *
+ * @return {@code true} if valid, {@code false} otherwise.
*/
public abstract boolean areValid();
diff --git a/opennlp-wsd/src/main/java/opennlp/tools/disambiguator/WSDSample.java b/opennlp-wsd/src/main/java/opennlp/tools/disambiguator/WSDSample.java
index 5360a1d..e6984ff 100644
--- a/opennlp-wsd/src/main/java/opennlp/tools/disambiguator/WSDSample.java
+++ b/opennlp-wsd/src/main/java/opennlp/tools/disambiguator/WSDSample.java
@@ -217,6 +217,9 @@ public class WSDSample implements Sample {
return ref;
}
+ /**
+ * {@inheritDoc}
+ */
@Override
public boolean equals(Object obj) {
if (this == obj) {
@@ -230,6 +233,9 @@ public class WSDSample implements Sample {
}
}
+ /**
+ * {@inheritDoc}
+ */
@Override
public int hashCode() {
int result = Objects.hash(targetPosition);
@@ -238,6 +244,9 @@ public class WSDSample implements Sample {
return result;
}
+ /**
+ * {@inheritDoc}
+ */
@Override
public String toString() {
StringBuilder result = new StringBuilder();
@@ -255,7 +264,6 @@ public class WSDSample implements Sample {
// get rid of last space
result.setLength(result.length() - 1);
}
-
return result.toString();
}
diff --git a/opennlp-wsd/src/main/java/opennlp/tools/disambiguator/WSDisambiguatorFactory.java b/opennlp-wsd/src/main/java/opennlp/tools/disambiguator/WSDisambiguatorFactory.java
index 5a656b7..f48d628 100644
--- a/opennlp-wsd/src/main/java/opennlp/tools/disambiguator/WSDisambiguatorFactory.java
+++ b/opennlp-wsd/src/main/java/opennlp/tools/disambiguator/WSDisambiguatorFactory.java
@@ -21,6 +21,9 @@ import opennlp.tools.util.BaseToolFactory;
import opennlp.tools.util.InvalidFormatException;
import opennlp.tools.util.ext.ExtensionLoader;
+/**
+ * Implements a word sense disambiguation related {@link BaseToolFactory}.
+ */
public class WSDisambiguatorFactory extends BaseToolFactory {
/**
@@ -58,11 +61,19 @@ public class WSDisambiguatorFactory extends BaseToolFactory {
}
}
+ /**
+ * {@inheritDoc}
+ */
@Override
public void validateArtifactMap() throws InvalidFormatException {
// no additional artifacts
}
+ /**
+ * @implNote By default, an {@link IMSWSDContextGenerator} will be instantiated.
+ *
+ * @return Retrieves the active {@link WSDContextGenerator}.
+ */
public WSDContextGenerator getContextGenerator() {
// default can be IMS
return new IMSWSDContextGenerator();
diff --git a/opennlp-wsd/src/main/java/opennlp/tools/disambiguator/WTDIMS.java b/opennlp-wsd/src/main/java/opennlp/tools/disambiguator/WTDIMS.java
index d3c5dea..496d543 100644
--- a/opennlp-wsd/src/main/java/opennlp/tools/disambiguator/WTDIMS.java
+++ b/opennlp-wsd/src/main/java/opennlp/tools/disambiguator/WTDIMS.java
@@ -123,7 +123,7 @@ public class WTDIMS {
return sentence;
}
- public void setSentence(String[] sentence) {
+ private void setSentence(String[] sentence) {
this.sentence = sentence;
}
@@ -131,7 +131,7 @@ public class WTDIMS {
return posTags;
}
- public void setPosTags(String[] posTags) {
+ private void setPosTags(String[] posTags) {
this.posTags = posTags;
}
@@ -139,7 +139,7 @@ public class WTDIMS {
return wordIndex;
}
- public void setWordIndex(int wordIndex) {
+ private void setWordIndex(int wordIndex) {
this.wordIndex = wordIndex;
}
@@ -147,7 +147,7 @@ public class WTDIMS {
return lemmas;
}
- public void setLemmas(String[] lemmas) {
+ private void setLemmas(String[] lemmas) {
this.lemmas = lemmas;
}
@@ -163,7 +163,7 @@ public class WTDIMS {
return senseIDs;
}
- public void setSenseIDs(String[] senseIDs) {
+ private void setSenseIDs(String[] senseIDs) {
this.senseIDs = senseIDs;
}
@@ -201,7 +201,7 @@ public class WTDIMS {
return posOfSurroundingWords;
}
- public void setPosOfSurroundingWords(String[] posOfSurroundingWords) {
+ protected void setPosOfSurroundingWords(String[] posOfSurroundingWords) {
this.posOfSurroundingWords = posOfSurroundingWords;
}
@@ -209,7 +209,7 @@ public class WTDIMS {
return surroundingWords;
}
- public void setSurroundingWords(String[] surroundingWords) {
+ protected void setSurroundingWords(String[] surroundingWords) {
this.surroundingWords = surroundingWords;
}
@@ -217,7 +217,7 @@ public class WTDIMS {
return localCollocations;
}
- public void setLocalCollocations(String[] localCollocations) {
+ protected void setLocalCollocations(String[] localCollocations) {
this.localCollocations = localCollocations;
}
@@ -225,7 +225,7 @@ public class WTDIMS {
return this.features;
}
- public void setFeatures(String[] features) {
+ protected void setFeatures(String[] features) {
this.features = features;
}
diff --git a/opennlp-wsd/src/main/java/opennlp/tools/disambiguator/WordPOS.java b/opennlp-wsd/src/main/java/opennlp/tools/disambiguator/WordPOS.java
index 91c2d48..118c306 100644
--- a/opennlp-wsd/src/main/java/opennlp/tools/disambiguator/WordPOS.java
+++ b/opennlp-wsd/src/main/java/opennlp/tools/disambiguator/WordPOS.java
@@ -30,7 +30,12 @@ import net.sf.extjwnl.data.Synset;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
-// TODO extend Word instead
+/**
+ * A container class that holds a token (word) and it's related POS tag.
+ * It provides methods to get {@link Synset synsets} or stem forms for it.
+ *
+ * @see POS
+ */
public class WordPOS {
private static final Logger LOG = LoggerFactory.getLogger(WordPOS.class);
@@ -45,6 +50,7 @@ public class WordPOS {
*
* @param word The token to use. It must not be {@code null}.
* @param tag The POS tag to use. It must not be {@code null}.
+ *
* @throws IllegalArgumentException Thrown if parameters are invalid.
*/
public WordPOS(String word, String tag) {
@@ -56,6 +62,7 @@ public class WordPOS {
*
* @param word The token to use. It must not be {@code null} and not be empty.
* @param pos The {@link POS pos tag} to use. It must not be {@code null}.
+ *
* @throws IllegalArgumentException Thrown if parameters are invalid.
*/
public WordPOS(String word, POS pos) {
@@ -108,7 +115,13 @@ public class WordPOS {
return Collections.emptyList();
}
- // uses Stemming to check if two words are equivalent
+ /**
+ * Applies stemming to check whether {@code wordToCompare} is equivalent
+ * to the current {@link WordPOS} instance.
+ *
+ * @param wordToCompare The {@link WordPOS} instance to compare against.
+ */
+ // TODO check the performance of the current implementation (!)
public boolean isStemEquivalent(WordPOS wordToCompare) {
// check if there is intersection in the stems;
List<String> listToCompare = wordToCompare.getStems();
diff --git a/opennlp-wsd/src/main/java/opennlp/tools/disambiguator/WordSense.java b/opennlp-wsd/src/main/java/opennlp/tools/disambiguator/WordSense.java
index da52e9a..91a6863 100644
--- a/opennlp-wsd/src/main/java/opennlp/tools/disambiguator/WordSense.java
+++ b/opennlp-wsd/src/main/java/opennlp/tools/disambiguator/WordSense.java
@@ -19,51 +19,95 @@
package opennlp.tools.disambiguator;
+/**
+ * Represents a type that associates {@link WSDSample samples} with a
+ * {@link SynNode syn node} which holds one or more senses.
+ * Elements of this type can be scored and thereby be ranked. This is
+ * why {@link WordSense} implements {@link Comparable}.
+ *
+ * @see SynNode
+ * @see WSDSample
+ */
public class WordSense implements Comparable<WordSense> {
- private final SynNode node;
private final int id;
+ private final SynNode node;
private WSDSample sample;
private double score;
+ /**
+ * Initializes a {@link WordSense} via a numerical {@code id} and
+ * a {@link SynNode} instance.
+ *
+ * @param id Must be a positive number.
+ * @param node The {@link SynNode node} to link senses to.
+ */
public WordSense(int id, SynNode node) {
this.id = id;
this.node = node;
}
+ /**
+ * Initializes a {@link WordSense} via a {@link WSDSample} and
+ * a {@link SynNode} instance.
+ *
+ * @param sample The {@link WSDSample word sample} to associate.
+ * @param node The {@link SynNode node} to link senses to.
+ */
public WordSense(WSDSample sample, SynNode node) {
this(sample.getSenseID(), node);
this.sample = sample;
}
+ /**
+ * @return Retrieves to numerical identifier.
+ */
public int getId() {
return id;
}
+ /**
+ * @return Retrieves the gloss available via WordNet.
+ */
public String getGloss() {
return node.getGloss();
}
+ /**
+ * @return Retrieves {@link SynNode syn node} instance.
+ */
public SynNode getNode() {
return node;
}
+ /**
+ * @return Retrieves {@link WSDSample word sample} instance.
+ */
public WSDSample getWSDSample() {
return sample;
}
- public void setWSDSample(WSDSample sample) {
+ void setWSDSample(WSDSample sample) {
this.sample = sample;
}
+ /**
+ * @return Retrieves numerical score. The value might be undefined, aka not set.
+ */
public double getScore() {
return score;
}
- public void setScore(double score) {
+ /**
+ * @param score The score to assign. No restrictions on this parameter.
+ */
+ void setScore(double score) {
this.score = score;
}
+ /**
+ * {@inheritDoc}
+ */
@Override
public int compareTo(WordSense o) {
return Double.compare(this.score, o.score);