feat(corefs): adding corefs annotation support

Author: gerardobort

README.md

@@ -198,7 +198,7 @@ CoreNLP
       ParserAnnotator             # https://stanfordnlp.github.io/CoreNLP/parse.html
       DependencyParseAnnotator    # https://stanfordnlp.github.io/CoreNLP/depparse.html
       RelationExtractorAnnotator  # https://stanfordnlp.github.io/CoreNLP/relation.html
-      DeterministicCorefAnnotator # https://stanfordnlp.github.io/CoreNLP/coref.html
+      CorefAnnotator              # https://stanfordnlp.github.io/CoreNLP/coref.html
       SentimentAnnotator          # https://stanfordnlp.github.io/CoreNLP/sentiment.html - TODO
       RelationExtractorAnnotator  # https://stanfordnlp.github.io/CoreNLP/relation.html - TODO
       NaturalLogicAnnotator       # https://stanfordnlp.github.io/CoreNLP/natlog.html - TODO

examples/corefs.js

@@ -0,0 +1,36 @@
+// NOTE: run with babel-node
+import path from 'path';
+import CoreNLP, { Properties, Pipeline, ConnectorServer } from '../src';
+
+const props = new Properties();
+props.setProperty('annotators', 'tokenize,ssplit,coref');
+const doc = new CoreNLP.simple.Document(`
+  George is a good person. He is really smart. I heard he is also a great son.
+  Lisa is instead a sad girl, I never saw her happy.
+`);
+const pipeline = new Pipeline(props, 'English');
+
+pipeline.annotate(doc)
+  .then(doc => {
+    const corefChains = doc.corefs();
+    corefChains.forEach(chain => {
+      console.log('representative ->', chain.representative().token().word());
+      chain.nonRepresentatives().forEach(mention => {
+        console.log(' ref ->', mention.token().word(), mention.gender(), mention.number());
+      });
+    });
+  })
+  .catch(err => {
+    console.log('err', err);
+  });
+
+/*
+OUTPUT:
+representative -> George
+ ref -> He MALE SINGULAR
+ ref -> he MALE SINGULAR
+representative -> Lisa
+ ref -> her FEMALE SINGULAR
+representative -> I
+ ref -> I UNKNOWN SINGULAR
+*/

src/index.js

@@ -13,6 +13,7 @@ import ParserAnnotator from './simple/annotator/parse';
 import DependencyParseAnnotator from './simple/annotator/depparse';
 import RelationExtractorAnnotator from './simple/annotator/relation';
 import RegexNERAnnotator from './simple/annotator/regexner';
+import CorefAnnotator from './simple/annotator/coref';
 import Tree from './util/tree';
 import _Properties from './properties';
 import _Pipeline from './pipeline';
@@ -56,6 +57,7 @@ export default {
       DependencyParseAnnotator,
       RelationExtractorAnnotator,
       RegexNERAnnotator,
+      CorefAnnotator,
     },
   },
   /**

src/index.spec.js

@@ -18,6 +18,7 @@ import ParserAnnotator from './simple/annotator/parse';
 import DependencyParseAnnotator from './simple/annotator/depparse';
 import RelationExtractorAnnotator from './simple/annotator/relation';
 import RegexNERAnnotator from './simple/annotator/regexner';
+import CorefAnnotator from './simple/annotator/coref';
 import Tree from './util/tree';
 
 describe('CoreNLP Library entry point', () => {
@@ -71,6 +72,7 @@ describe('CoreNLP Library entry point', () => {
             DependencyParseAnnotator,
             RelationExtractorAnnotator,
             RegexNERAnnotator,
+            CorefAnnotator,
           });
         });
       });

src/pipeline.js

@@ -10,6 +10,7 @@ import parse from './simple/annotator/parse';
 import depparse from './simple/annotator/depparse';
 import relation from './simple/annotator/relation';
 import regexner from './simple/annotator/regexner';
+import coref from './simple/annotator/coref';
 import Document from './simple/document';
 
 import {
@@ -28,6 +29,7 @@ const ANNOTATORS_BY_KEY = {
   depparse,
   relation,
   regexner,
+  coref,
 };
 
 const LANGUAGE_TO_ISO2 = {

src/simple/annotator/coref.js

@@ -0,0 +1,32 @@
+import Annotator from '../annotator';
+import TokenizerAnnotator from './tokenize';
+import WordsToSentenceAnnotator from './ssplit';
+
+/**
+ * @class
+ * @classdesc Class representing an CorefAnnotator.
+ * @extends Annotator
+ * @memberof CoreNLP/simple/annotator
+ * @requires tokenize, ssplit, coref
+ * @see {@link https://stanfordnlp.github.io/CoreNLP/coref.html|CorefAnnotator}
+ */
+class CorefAnnotator extends Annotator {
+  /**
+   * Create an Annotator
+   * @param {Object} [options] a key-value map of options, without the annotator prefix
+   */
+  constructor(options = {}) {
+    super(
+      'coref',
+      {
+        ...options,
+      },
+      [
+        new TokenizerAnnotator(),
+        new WordsToSentenceAnnotator(),
+      ],
+    );
+  }
+}
+
+export default CorefAnnotator;

src/simple/annotator/coref.spec.js

@@ -0,0 +1,20 @@
+import CorefAnnotator from './coref';
+
+describe('Annotator', () => {
+  let annotator;
+
+  describe('CorefAnnotator', () => {
+    beforeEach(() => {
+      annotator = new CorefAnnotator();
+    });
+
+    it('should have a proper pipeline', () => {
+      expect(annotator.pipeline()).to.deep.equal(['tokenize', 'ssplit', 'coref']);
+    });
+
+    it('should have the proper default options', () => {
+      expect(annotator.options()).to.deep.equal({
+      });
+    });
+  });
+});

src/simple/coref-chain.js

@@ -0,0 +1,104 @@
+import CorefMention from './coref-mention';
+
+/**
+ * @class
+ * @classdesc Class representing an CorefChain
+ */
+class CorefChain {
+  /**
+   * Create an CorefChain
+   * @param {Array.<CorefMention>} mentions
+   */
+  constructor(mentions) {
+    this._mentions = mentions;
+  }
+
+  /**
+   * Retrieves all the contained CorefMention instances
+   * @returns {Array.<CorefMention>} mentions
+   */
+  mentions() {
+    return this._mentions;
+  }
+
+  /**
+   * Retrieves a CorefMention at the index specified
+   * @param {number} index
+   * @returns {CorefMention} mention
+   */
+  mention(index) {
+    return this._mentions[index];
+  }
+
+  /**
+   * Retrieves the first representative mention
+   * @returns {CorefMention} mention
+   */
+  representative() {
+    return this._mentions.find(mention => mention.isRepresentativeMention());
+  }
+
+  /**
+   * Retrieves all the non-representative mentions
+   * @returns {Array.<CorefMention>} mentions
+   */
+  nonRepresentatives() {
+    return this._mentions.filter(mention => !mention.isRepresentativeMention());
+  }
+
+  /**
+   * Gets or sets a Document reference for the current coref-chain
+   * @param {Document} doc
+   * @returns {Document} doc
+   */
+  document(doc = null) {
+    if (doc) {
+      this._document = doc;
+    }
+
+    return this._document;
+  }
+
+  /**
+   * Update an instance of CorefChain with Document references to Sentence(s) and their Token(s)
+   * @param {Document} doc - a Document object, the same one used to generate corefs annotations
+   * @returns {CorefChain} chain - The current chain instance
+   */
+  fromDocument(doc) {
+    this._mentions.forEach((mention) => {
+      const sentence = doc.sentence(mention.sentNum() - 1);
+      const token = sentence.token(mention.startIndex() - 1);
+      mention.sentence(sentence);
+      mention.token(token);
+    });
+    return this;
+  }
+
+  /**
+   * Update an instance of CorefChain with data provided by a JSON
+   * @param {Array.<CorefMentionJSON>} data - A sentence corefs mentions chain, as 
+   *  returned by CoreNLP API service
+   * @returns {CorefChain} chain - The current chain instance
+   */
+  fromJSON(data) {
+    this._mentions = data.map(mention => CorefMention.fromJSON(mention));
+    return this;
+  }
+
+  toJSON() {
+    return [...this._mentions];
+  }
+
+  /**
+   * Get an instance of CorefChain from a given JSON of sentence corefs
+   * @param {Array.<CorefMentionJSON>} data - The sentence corefs data, as
+   *  returned by CoreNLP API service
+   * @returns {CorefChain} sentenchain - A new CorefChain instance
+   */
+  static fromJSON(data) {
+    const instance = new this();
+    return instance.fromJSON(data);
+  }
+}
+
+export default CorefChain;

src/simple/coref-chain.spec.js

@@ -0,0 +1,24 @@
+import CorefChain from './coref-chain';
+
+describe('CorefChain', () => {
+  let chain;
+
+  beforeEach(() => {
+    chain = new CorefChain();
+  });
+
+  context('CorefChain interface', () => {
+    it('should follow the CorefChain contract', () => {
+      expect(chain).to.have.property('mentions').that.is.a('function');
+      expect(chain).to.have.property('mention').that.is.a('function');
+      expect(chain).to.have.property('representative').that.is.a('function');
+      expect(chain).to.have.property('nonRepresentatives').that.is.a('function');
+      expect(chain).to.have.property('document').that.is.a('function');
+      expect(chain).to.have.property('fromDocument').that.is.a('function');
+      expect(chain).to.have.property('fromJSON').that.is.a('function');
+    });
+
+    describe.skip('constructor', () => {
+    });
+  });
+});