OPENNLP-855: Clean up Sentiment Analysis implementation and add tests

  - Remove broken sequence labeling code (find/predict2) from SentimentME
    and SentimentDetector; sentiment is a classification task, not sequence
    labeling
  - Remove getSentimentModel() from SentimentModel (wrapped MaxentModel in
    unused BeamSearch)
  - Add toString/equals/hashCode to SentimentSample, remove unused id field
  - Fix SentimentSampleTypeFilter to actually filter by sentiment type
  - Fix SentimentDetailedFMeasureListener.asSpanArray() returning null
  - Remove dead detailedFListener code in CLI tools
  - Add 44 unit tests covering all runtime sentiment classes

Author: rzo1

opennlp-api/src/main/java/opennlp/tools/sentiment/SentimentDetector.java

@@ -17,8 +17,6 @@
 
 package opennlp.tools.sentiment;
 
-import opennlp.tools.util.Span;
-
 public interface SentimentDetector {
 
   /**
@@ -36,30 +34,4 @@ public interface SentimentDetector {
    * @return The predicted sentiment.
    */
   String predict(String[] tokens);
-
-  /**
-   * Generates sentiment tags for the given sequence, typically a sentence,
-   * returning token spans for any identified sentiments.
-   *
-   * @param tokens
-   *          an array of the tokens or words of the sequence, typically a
-   *          sentence
-   * @return an array of spans for each of the names identified.
-   */
-  Span[] find(String[] tokens);
-
-  /**
-   * Generates sentiment tags for the given sequence, typically a sentence,
-   * returning token spans for any identified sentiments.
-   *
-   * @param tokens
-   *          an array of the tokens or words of the sequence, typically a
-   *          sentence.
-   * @param additionalContext
-   *          features which are based on context outside of the sentence but
-   *          which should also be used.
-   *
-   * @return an array of spans for each of the names identified.
-   */
-  Span[] find(String[] tokens, String[][] additionalContext);
 }

opennlp-api/src/main/java/opennlp/tools/sentiment/SentimentSample.java

@@ -19,6 +19,7 @@
 
 import java.io.Serial;
 import java.util.List;
+import java.util.Objects;
 
 import opennlp.tools.commons.Sample;
 
@@ -33,7 +34,6 @@ public class SentimentSample implements Sample {
   private final String sentiment;
   private final List<String> sentence;
   private final boolean isClearAdaptiveData;
-  private final String id = null;
 
   /**
    * Instantiates a {@link SentimentSample} object.
@@ -75,15 +75,34 @@ public String[] getSentence() {
     return sentence.toArray(new String[0]);
   }
 
-  public String getId() {
-    return id;
-  }
-
   /**
    * @return Returns the value of isClearAdaptiveData, {@code true} or {@code false}.
    */
   public boolean isClearAdaptiveDataSet() {
     return isClearAdaptiveData;
   }
 
+  @Override
+  public String toString() {
+    return sentiment + " " + String.join(" ", sentence);
+  }
+
+  @Override
+  public boolean equals(Object obj) {
+    if (this == obj) {
+      return true;
+    }
+    if (obj == null || getClass() != obj.getClass()) {
+      return false;
+    }
+    SentimentSample that = (SentimentSample) obj;
+    return Objects.equals(sentiment, that.sentiment)
+        && Objects.equals(sentence, that.sentence);
+  }
+
+  @Override
+  public int hashCode() {
+    return Objects.hash(sentiment, sentence);
+  }
+
 }

opennlp-core/opennlp-cli/src/main/java/opennlp/tools/cmdline/sentiment/SentimentCrossValidatorTool.java

@@ -83,7 +83,6 @@ public void run(String format, String[] args) {
     if (params.getMisclassified()) {
       listeners.add(new SentimentEvaluationErrorListener());
     }
-    SentimentDetailedFMeasureListener detailedFListener = null;
     SentimentFactory sentimentFactory = new SentimentFactory();
 
     SentimentCrossValidator validator;
@@ -107,12 +106,7 @@ public void run(String format, String[] args) {
     System.out.println("done");
 
     System.out.println();
-
-    if (detailedFListener == null) {
-      System.out.println(validator.getFMeasure());
-    } else {
-      System.out.println(detailedFListener.toString());
-    }
+    System.out.println(validator.getFMeasure());
   }
 
 }

opennlp-core/opennlp-cli/src/main/java/opennlp/tools/cmdline/sentiment/SentimentDetailedFMeasureListener.java

@@ -38,6 +38,6 @@ public class SentimentDetailedFMeasureListener
    */
   @Override
   protected Span[] asSpanArray(SentimentSample sample) {
-    return null;
+    return new Span[] { new Span(0, 0, sample.getSentiment()) };
   }
 }

opennlp-core/opennlp-cli/src/main/java/opennlp/tools/cmdline/sentiment/SentimentEvaluatorTool.java

@@ -89,8 +89,6 @@ public void run(String format, String[] args) {
     if (params.getMisclassified()) {
       listeners.add(new SentimentEvaluationErrorListener());
     }
-    SentimentDetailedFMeasureListener detailedFListener = null;
-
     if (params.getNameTypes() != null) {
       String[] nameTypes = params.getNameTypes().split(",");
       sampleStream = new SentimentSampleTypeFilter(nameTypes, sampleStream);
@@ -142,12 +140,7 @@ public void close() throws IOException {
     monitor.stopAndPrintFinalResult();
 
     System.out.println();
-
-    if (detailedFListener == null) {
-      System.out.println(evaluator.getFMeasure());
-    } else {
-      System.out.println(detailedFListener.toString());
-    }
+    System.out.println(evaluator.getFMeasure());
   }
 
 }

opennlp-core/opennlp-runtime/src/main/java/opennlp/tools/sentiment/SentimentCrossValidator.java

@@ -204,18 +204,14 @@ public void evaluate(ObjectStream<SentimentSample> samples, int nFolds)
     CrossValidationPartitioner<DocumentSample> partitioner = new CrossValidationPartitioner<>(
         new SentimentToDocumentSampleStream(samples), nFolds);
 
-    SentimentModel model = null;
-
     while (partitioner.hasNext()) {
 
       CrossValidationPartitioner.TrainingSampleStream<DocumentSample> trainingSampleStream = partitioner
           .next();
 
-      if (factory != null) {
-        model = SentimentME.train(languageCode,
-            new DocumentToSentimentSampleStream(trainingSampleStream), params,
-            factory);
-      }
+      SentimentModel model = SentimentME.train(languageCode,
+          new DocumentToSentimentSampleStream(trainingSampleStream), params,
+          factory);
 
       // do testing
       SentimentEvaluator evaluator = new SentimentEvaluator(

opennlp-core/opennlp-runtime/src/main/java/opennlp/tools/sentiment/SentimentME.java

@@ -19,23 +19,14 @@
 
 import java.io.IOException;
 import java.util.HashMap;
-import java.util.List;
 import java.util.Map;
 
 import opennlp.tools.ml.EventTrainer;
 import opennlp.tools.ml.TrainerFactory;
 import opennlp.tools.ml.model.Event;
 import opennlp.tools.ml.model.MaxentModel;
-import opennlp.tools.ml.model.SequenceClassificationModel;
-import opennlp.tools.namefind.BioCodec;
 import opennlp.tools.util.ObjectStream;
-import opennlp.tools.util.Sequence;
-import opennlp.tools.util.SequenceCodec;
-import opennlp.tools.util.SequenceValidator;
-import opennlp.tools.util.Span;
 import opennlp.tools.util.TrainingParameters;
-import opennlp.tools.util.featuregen.AdaptiveFeatureGenerator;
-import opennlp.tools.util.featuregen.AdditionalContextFeatureGenerator;
 
 /**
  * A {@link SentimentDetector} implementation for creating and using
@@ -45,22 +36,9 @@
  */
 public class SentimentME implements SentimentDetector {
 
-  public static final int DEFAULT_BEAM_SIZE = 3;
-
-  private static final String[][] EMPTY = new String[0][0];
-
-  protected SentimentContextGenerator contextGenerator;
-
-  private final AdditionalContextFeatureGenerator additionalContextFeatureGenerator =
-      new AdditionalContextFeatureGenerator();
-
-  private Sequence bestSequence;
-  private SequenceValidator<String> sequenceValidator;
-  private final SequenceClassificationModel model;
+  private final SentimentContextGenerator contextGenerator;
   private final SentimentFactory factory;
   private final MaxentModel maxentModel;
-  private final SequenceCodec<String> seqCodec = new BioCodec();
-  private AdaptiveFeatureGenerator[] featureGenerators;
 
   /**
    * Instantiates a {@link SentimentME} with the specified model.
@@ -73,7 +51,6 @@ public SentimentME(SentimentModel sentModel) {
     if (sentModel == null) {
       throw new IllegalArgumentException("SentimentModel must not be null!");
     }
-    this.model = sentModel.getSentimentModel();
     maxentModel = sentModel.getMaxentModel();
     factory = sentModel.getFactory();
     contextGenerator = factory.createContextGenerator();
@@ -91,22 +68,22 @@ public SentimentME(SentimentModel sentModel) {
    * @param factory
    *          a Sentiment Analysis factory
    * @return A valid {@link SentimentModel}.
+   * @throws IOException Thrown if IO errors occurred during training.
    */
   public static SentimentModel train(String languageCode, ObjectStream<SentimentSample> samples,
                                      TrainingParameters trainParams, SentimentFactory factory)
           throws IOException {
 
     Map<String, String> entries = new HashMap<>();
-    MaxentModel sentimentModel;
 
     ObjectStream<Event> eventStream = new SentimentEventStream(samples, factory.createContextGenerator());
 
     EventTrainer<TrainingParameters> trainer = TrainerFactory.getEventTrainer(trainParams, entries);
-    sentimentModel = trainer.train(eventStream);
+    MaxentModel sentimentModel = trainer.train(eventStream);
 
-    return new SentimentModel(languageCode, sentimentModel, new HashMap<>(), factory);
+    return new SentimentModel(languageCode, sentimentModel, entries, factory);
   }
-  
+
   @Override
   public String predict(String sentence) {
     String[] tokens = factory.getTokenizer().tokenize(sentence);
@@ -120,126 +97,22 @@ public String predict(String[] tokens) {
   }
 
   /**
-   * Returns the best chosen sentiment for the text predicted on
+   * Returns the best chosen sentiment for the given probability distribution.
    *
-   * @param outcome
-   *          the outcome
-   * @return the best sentiment
+   * @param outcome the probability distribution over outcomes.
+   * @return the best sentiment label.
    */
   public String getBestSentiment(double[] outcome) {
     return maxentModel.getBestOutcome(outcome);
   }
 
   /**
-   * Returns the analysis probabilities
+   * Returns the probability distribution over sentiment labels for the given tokens.
    *
-   * @param text
-   *          the text to categorize
+   * @param text the tokens to classify.
+   * @return the probability distribution over sentiment labels.
    */
   public double[] probabilities(String[] text) {
     return maxentModel.eval(contextGenerator.getContext(text));
   }
-
-  /**
-   * Returns an array of probabilities for each of the specified spans which is
-   * the arithmetic mean of the probabilities for each of the outcomes which
-   * make up the span.
-   *
-   * @param spans
-   *          The spans of the sentiments for which probabilities are desired.
-   * @return an array of probabilities for each of the specified spans.
-   */
-  public double[] probs(Span[] spans) {
-
-    double[] sprobs = new double[spans.length];
-    double[] probs = bestSequence.getProbs();
-
-    for (int si = 0; si < spans.length; si++) {
-
-      double p = 0;
-
-      for (int oi = spans[si].getStart(); oi < spans[si].getEnd(); oi++) {
-        p += probs[oi];
-      }
-
-      p /= spans[si].length();
-
-      sprobs[si] = p;
-    }
-
-    return sprobs;
-  }
-
-  /**
-   * Sets the probs for the spans
-   *
-   * @param spans
-   *          the spans to be analysed
-   * @return the span of probs
-   */
-  private Span[] setProbs(Span[] spans) {
-    double[] probs = probs(spans);
-    if (probs != null) {
-
-      for (int i = 0; i < probs.length; i++) {
-        double prob = probs[i];
-        spans[i] = new Span(spans[i], prob);
-      }
-    }
-    return spans;
-  }
-
-  @Override
-  public Span[] find(String[] tokens) {
-    return find(tokens, EMPTY);
-  }
-
-  @Override
-  public Span[] find(String[] tokens, String[][] additionalContext) {
-
-    additionalContextFeatureGenerator.setCurrentContext(additionalContext);
-
-    bestSequence = model.bestSequence(tokens, additionalContext,
-        contextGenerator, sequenceValidator);
-
-    List<String> c = bestSequence.getOutcomes();
-
-    contextGenerator.updateAdaptiveData(tokens, c.toArray(new String[0]));
-    Span[] spans = seqCodec.decode(c);
-    spans = setProbs(spans);
-    return spans;
-  }
-
-  /**
-   * Makes a sentiment prediction by calling the helper method
-   *
-   * @param tokens
-   *          the text to be analysed for its sentiment
-   * @return the prediction made by the helper method
-   */
-  public Span[] predict2(String[] tokens) {
-    return predict2(tokens, EMPTY);
-  }
-
-  /**
-   * Makes a sentiment prediction
-   *
-   * @param tokens
-   *          the text to be analysed for its sentiment
-   * @param additionalContext
-   *          any required additional context
-   * @return the predictions
-   */
-  public Span[] predict2(String[] tokens, String[][] additionalContext) {
-
-    additionalContextFeatureGenerator.setCurrentContext(additionalContext);
-
-    bestSequence = model.bestSequence(tokens, additionalContext,
-        contextGenerator, sequenceValidator);
-
-    List<String> c = bestSequence.getOutcomes();
-
-    return seqCodec.decode(c);
-  }
-
 }