OPENNLP-855: SentimentAnalysisParser deriving sentiment from text

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

@@ -0,0 +1,65 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package opennlp.tools.sentiment;
+
+import opennlp.tools.util.Span;
+
+public interface SentimentDetector {
+
+  /**
+   * Conducts a sentiment prediction for the specifed sentence.
+   *
+   * @param sentence The text to be analysed for its sentiment.
+   * @return The predicted sentiment.
+   */
+  String predict(String sentence);
+
+  /**
+   * Conducts a sentiment prediction for the specifed sentence.
+   *
+   * @param tokens The text to be analysed for its sentiment.
+   * @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/SentimentEvaluationMonitor.java

@@ -0,0 +1,29 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package opennlp.tools.sentiment;
+
+import opennlp.tools.util.eval.EvaluationMonitor;
+
+/**
+ * An sentiment specific {@link EvaluationMonitor} to be used by the evaluator.
+ *
+ * @see SentimentSample
+ */
+public interface SentimentEvaluationMonitor extends EvaluationMonitor<SentimentSample> {
+
+}

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

@@ -0,0 +1,89 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package opennlp.tools.sentiment;
+
+import java.io.Serial;
+import java.util.List;
+
+import opennlp.tools.commons.Sample;
+
+/**
+ * Class for holding text used for sentiment analysis.
+ */
+public class SentimentSample implements Sample {
+
+  @Serial
+  private static final long serialVersionUID = 2477213313738337539L;
+
+  private final String sentiment;
+  private final List<String> sentence;
+  private final boolean isClearAdaptiveData;
+  private final String id = null;
+
+  /**
+   * Instantiates a {@link SentimentSample} object.
+   *
+   * @param sentiment
+   *          training sentiment
+   * @param sentence
+   *          training sentence
+   */
+  public SentimentSample(String sentiment, String[] sentence) {
+    this(sentiment, sentence, true);
+  }
+
+  public SentimentSample(String sentiment, String[] sentence,
+      boolean clearAdaptiveData) {
+    if (sentiment == null) {
+      throw new IllegalArgumentException("sentiment must not be null");
+    }
+    if (sentence == null) {
+      throw new IllegalArgumentException("sentence must not be null");
+    }
+
+    this.sentiment = sentiment;
+    this.sentence = List.of(sentence);
+    this.isClearAdaptiveData = clearAdaptiveData;
+  }
+
+  /**
+   * @return Returns the sentiment.
+   */
+  public String getSentiment() {
+    return sentiment;
+  }
+
+  /**
+   * @return Returns the sentence.
+   */
+  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;
+  }
+
+}

opennlp-core/opennlp-cli/src/main/java/opennlp/tools/cmdline/CLI.java

@@ -71,6 +71,9 @@
 import opennlp.tools.cmdline.sentdetect.SentenceDetectorEvaluatorTool;
 import opennlp.tools.cmdline.sentdetect.SentenceDetectorTool;
 import opennlp.tools.cmdline.sentdetect.SentenceDetectorTrainerTool;
+import opennlp.tools.cmdline.sentiment.SentimentCrossValidatorTool;
+import opennlp.tools.cmdline.sentiment.SentimentEvaluatorTool;
+import opennlp.tools.cmdline.sentiment.SentimentTrainerTool;
 import opennlp.tools.cmdline.tokenizer.DictionaryDetokenizerTool;
 import opennlp.tools.cmdline.tokenizer.SimpleTokenizerTool;
 import opennlp.tools.cmdline.tokenizer.TokenizerConverterTool;
@@ -165,6 +168,11 @@ public final class CLI {
 
     // Entity Linker
     tools.add(new EntityLinkerTool());
+
+    // Sentiment Analysis Parser
+    tools.add(new SentimentTrainerTool());
+    tools.add(new SentimentEvaluatorTool());
+    tools.add(new SentimentCrossValidatorTool());
 
     // Language Model
     tools.add(new NGramLanguageModelTool());

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

@@ -0,0 +1,118 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package opennlp.tools.cmdline.sentiment;
+
+import java.io.IOException;
+import java.util.LinkedList;
+import java.util.List;
+
+import opennlp.tools.cmdline.AbstractCrossValidatorTool;
+import opennlp.tools.cmdline.CmdLineUtil;
+import opennlp.tools.cmdline.TerminateToolException;
+import opennlp.tools.cmdline.params.BasicTrainingParams;
+import opennlp.tools.cmdline.params.CVParams;
+import opennlp.tools.cmdline.sentiment.SentimentCrossValidatorTool.CVToolParams;
+import opennlp.tools.sentiment.SentimentCrossValidator;
+import opennlp.tools.sentiment.SentimentEvaluationMonitor;
+import opennlp.tools.sentiment.SentimentFactory;
+import opennlp.tools.sentiment.SentimentSample;
+import opennlp.tools.util.eval.EvaluationMonitor;
+import opennlp.tools.util.model.ModelUtil;
+
+/**
+ * Class for helping perform cross validation on the Sentiment Analysis Parser.
+ */
+public class SentimentCrossValidatorTool
+    extends AbstractCrossValidatorTool<SentimentSample, CVToolParams> {
+
+  /**
+   * Interface for parameters
+   */
+  interface CVToolParams extends BasicTrainingParams, CVParams {
+
+  }
+
+  /**
+   * Constructor
+   */
+  public SentimentCrossValidatorTool() {
+    super(SentimentSample.class, CVToolParams.class);
+  }
+
+  /**
+   * Returns the short description of the tool
+   *
+   * @return short description
+   */
+  public String getShortDescription() {
+    return "K-fold cross validator for the learnable Sentiment Analysis Parser";
+  }
+
+  /**
+   * Runs the tool
+   *
+   * @param format
+   *          the format to be used
+   * @param args
+   *          the arguments
+   */
+  public void run(String format, String[] args) {
+    super.run(format, args);
+
+    mlParams = CmdLineUtil.loadTrainingParameters(params.getParams(), true);
+    if (mlParams == null) {
+      mlParams = ModelUtil.createDefaultTrainingParameters();
+    }
+
+    List<EvaluationMonitor<SentimentSample>> listeners = new LinkedList<>();
+    if (params.getMisclassified()) {
+      listeners.add(new SentimentEvaluationErrorListener());
+    }
+    SentimentDetailedFMeasureListener detailedFListener = null;
+    SentimentFactory sentimentFactory = new SentimentFactory();
+
+    SentimentCrossValidator validator;
+    try {
+      validator = new SentimentCrossValidator(params.getLang(), mlParams, sentimentFactory,
+          listeners.toArray(new SentimentEvaluationMonitor[listeners.size()]));
+      validator.evaluate(sampleStream, params.getFolds());
+    } catch (IOException e) {
+      throw new TerminateToolException(-1,
+          "IO error while reading training data or indexing data: "
+              + e.getMessage(),
+          e);
+    } finally {
+      try {
+        sampleStream.close();
+      } catch (IOException e) {
+        // sorry that this can fail
+      }
+    }
+
+    System.out.println("done");
+
+    System.out.println();
+
+    if (detailedFListener == null) {
+      System.out.println(validator.getFMeasure());
+    } else {
+      System.out.println(detailedFListener.toString());
+    }
+  }
+
+}

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

@@ -0,0 +1,43 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package opennlp.tools.cmdline.sentiment;
+
+import opennlp.tools.cmdline.DetailedFMeasureListener;
+import opennlp.tools.sentiment.SentimentEvaluationMonitor;
+import opennlp.tools.sentiment.SentimentSample;
+import opennlp.tools.util.Span;
+
+/**
+ * Class for creating a detailed F-Measure listener
+ */
+public class SentimentDetailedFMeasureListener
+    extends DetailedFMeasureListener<SentimentSample>
+    implements SentimentEvaluationMonitor {
+
+  /**
+   * Returns the sentiment sample as a span array
+   *
+   * @param sample
+   *          the sentiment sample to be returned
+   * @return span array of the sample
+   */
+  @Override
+  protected Span[] asSpanArray(SentimentSample sample) {
+    return null;
+  }
+}