You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Coreferences are situations where two or more words within a text refer to the same entity, e.g. *__John__ went home because __he__ was tired*. Resolving coreferences is an important general task within the natural language processing field.
33
37
34
-
Coreferee is a Python 3 library (tested with version 3.8.7) that is used together with [spaCy](https://spacy.io/) (tested with version 3.0.5) to resolve coreferences within English, German and Polish texts. It is designed so that it is easy to add support for new languages. It uses a mixture of neural networks and programmed rules.
38
+
Coreferee is a Python 3 library (tested with version 3.9.5) that is used together with [spaCy](https://spacy.io/) (tested with version 3.1.2) to resolve coreferences within English, German and Polish texts. It is designed so that it is easy to add support for new languages. It uses a mixture of neural networks and programmed rules.
35
39
36
40
<aid="getting-started"></a>
37
41
#### 1.2 Getting started
@@ -96,11 +100,11 @@ Then open a Python prompt (type `python3` or `python` at the command line):
96
100
>>> nlp.add_pipe('coreferee')
97
101
<coreferee.manager.CorefereeBroker object at 0x0000026E84C63B50>
98
102
>>>
99
-
>>> doc = nlp("Weil er mit seiner Arbeit sehr beschäftigt war, hatte Peter genug davon. Er und seine Frau haben entschieden, dass ihnen ein Urlaub gut tun würde. Sie sind nach Spanien gefahren, weil ihnen das Land sehr gefiel.")
103
+
>>> doc = nlp("Weil er mit seiner Arbeit sehr beschäftigt war, hatte Peter davon genug. Er und seine Frau haben entschieden, dass ihnen ein Urlaub gut tun würde. Sie sind nach Spanien gefahren, weil ihnen das Land sehr gefiel.")
<tr><tdalign="center">English</td><tdalign="center">en</td><tdalign="center"><i><b>My friend</b> came in. <b>He</b> was happy.</i><tdalign="center">-</td><tdalign="center">-</td><tdalign="center">Three singular (natural genders) and one plural class.</td><tdalign="center"><i><b>Peter and Mary</b></i></td><tdalign="center">-</td></tr>
201
205
<tr><tdalign="center">German</td><tdalign="center">de</td><tdalign="center"><i><b>Mein Freund</b> kam rein. <b>Er</b> war glücklich.</i><tdalign="center">-</td><tdalign="center"><i>Ich benutzte <b>das Auto</b> und hatte <b>damit</b> einige Probleme.</i></td><tdalign="center">Three singular (grammatical genders) and one plural class.</td><tdalign="center"><i><b>Peter und Maria</b></i></td><tdalign="center">-</td></tr>
202
-
<tr><tdalign="center">Polish</td><tdalign="center">pl</td><tdalign="center"><i>Wszedł <b>mój kolega</b>. <b>On</b> był szczęśliwy.</i><tdalign="center"><i>Wszedł <b>mój kolega</b>. Szczęśliwy <b>był</b>.<sup>1</sup></i></td><tdalign="center">-<sup>2</sup></td><tdalign="center">Three singular (grammatical genders) and two plural (natural genders) classes.</td><tdalign="center"><i><b>Piotr i Kasia</b></i></td><tdalign="center">1) <i><b>Piotr z Kasią</b> przyszli</i>; <br>2) <i>Widziałem Piotra i <b>przyszli z Kasią</i></b></td></tr>
206
+
<tr><tdalign="center">Polish</td><tdalign="center">pl</td><tdalign="center"><i>Wszedł <b>mój kolega</b>. Widzieliście, jaki <b>on</b> był szczęśliwy?</i><tdalign="center"><i>Wszedł <b>mój kolega</b>. Szczęśliwy <b>był</b>.<sup>1</sup></i></td><tdalign="center">-<sup>2</sup></td><tdalign="center">Three singular (grammatical genders) and two plural (natural genders) classes.</td><tdalign="center"><i><b>Piotr i Kasia</b></i></td><tdalign="center">1) <i><b>Piotr z Kasią</b> przyjechali do Warszawy</i>; <br>2) <i>Widziałem Piotra i <b>przyszli z Kasią</i></b></td></tr>
203
207
</table>
204
208
205
209
1. Only subject zero anaphors are covered. Object zero anaphors, e.g. <i>Wypiłeś <b>wodę</b>? Tak, <b>wypiłem.</b></i> are not in scope because they are mainly used colloquially and do not normally occur in the types of text for which [Coreferee is primarily designed](#background-information). Handling them would require creating or locating a detailed dictionary of verb valencies.
@@ -212,14 +216,14 @@ Coreferee started life to assist the [Holmes](https://github.com/msg-systems/hol
<tr><tdrowspan="2">Language</td><tdrowspan="2">ISO 639-1</td><tdrowspan="2">Training corpora</td><tdrowspan="2">Total words in training corpora</td><tdcolspan="2"><code>*_trf</code> models</td><tdcolspan="2"><code>*_lg</code> models</td><tdcolspan="2"><code>*_md</code> models</td><tdcolspan="2"><code>*_sm</code> models</td></tr>
214
218
<tr><tdalign="center">Anaphors in 20%</td><tdalign="center">Accuracy (%)</td><tdalign="center">Anaphors in 20%</td><tdalign="center">Accuracy (%)</td><tdalign="center">Anaphors in 20%</td><tdalign="center">Accuracy (%)</td><tdalign="center">Anaphors in 20%</td><tdalign="center">Accuracy (%)</td></tr>
Coreferee produces a range of neural-network models for each language corresponding to the various spaCy models for that language. The [neural network inputs](#the-neural-ensemble) include word vectors. With `_sm` (small) models, both spaCy and Coreferee use context-sensitive tensors as an alternative to word vectors. `_trf` (transformer-based) models, on the other hand, do not use or offer word vectors at all. To remedy this problem, the model configuration files (`config.cfg` in the directory for each language) allow a **vectors model** to be specified for use when a main model does not have its own vectors. Coreferee then combines the linguistic information generated by the main model with vector information returned for the individual words in each document by the vectors model.
221
225
222
-
Because the Coreferee models are rather large (70GB-80GB for the group of models for a given language) and because many users will only be interested in one language, the group of models for a given language is installed using `python3 -m coreferee install` as demonstrated in the introduction. All Coreferee models are more or less the same size; a larger spaCy model does not equate to a larger Coreferee model. As the figures above demonstrate, the accuracy of Coreferee corresponds closely to the size of the underlying spaCy model, and users are urged to use the larger spaCy models. It is in any case unclear whether there is a situation in which it would make sense to use Coreferee with an `_sm` model as the Coreferee model would then be considerably larger than the spaCy model!
226
+
Because the Coreferee models are rather large (70GB-80GB for the group of models for a given language) and because many users will only be interested in one language, the group of models for a given language is installed using `python3 -m coreferee install` as demonstrated in the introduction. All Coreferee models are more or less the same size; a larger spaCy model does not equate to a larger Coreferee model. As the figures above demonstrate, the accuracy of Coreferee corresponds closely to the size of the underlying spaCy model, and users are urged to use the larger spaCy models. It is in any case unclear whether there is a situation in which it would make sense to use Coreferee with an `_sm` model as the Coreferee model would then be considerably larger than the spaCy model! As this discrepancy is especially extreme for the Polish models, Coreferee no longer supports `pl_core_news_sm` from version 1.1.0 onwards.
223
227
224
228
Assessing and comparing the precision and recall of anaphor resolution algorithms is notoriously difficult. For one thing, two human annotators of the same data will not always agree (and, indeed, there are some cases where Coreferee and a training annotator disagree where Coreferee's interpretation seems the more plausible!) And the same algorithm may perform with wildly different accuracies with different test documents depending on how clearly the documents are written and how often there are competing interpretations of individual anaphors.
225
229
@@ -334,6 +338,13 @@ Each chain can also return the index number of the mention within it that is **m
334
338
335
339
This information is used as the basis for the `resolve()` method shown in the [initial example](#getting-started-en): the method traverses multiple chains to find the most specific mention or mentions within the text that describe a given anaphor or noun phrase head.
336
340
341
+
Note that a mention that heads a complex proper noun phrase only refers to the head of that phrase. Some users have expressed a requirement to retrieve all the tokens in such a phrase. Although this functionality is regarded as outside the main scope of Coreferee and is hence not available via the main data model, the information can be retrieved as follows:
15) Issue a pull request. We ask that you supply us with the zip file generated during training. Because this will contain a considerable amount of raw information from the training corpora, it will normally be preferable from a licensing viewpoint to <ahref="mailto:richard.hudson@msg.group">send it out of band</a> rather than attaching it to the pull request.
If you are using a custom spaCy model, you should generate a corresponding custom Coreferee model. Use points 2), 8), 9) and 10) from the [preceding section](#adding-support-for-a-new-language) as a guide. If you do not have your own training data, you can use the [same training data](#model-performance) that was used to generate the standard Coreferee models.
487
+
488
+
The language-specific rules expect specific entity tags as 'magic values'. This is unfortunate but there is no obvious alternative solution because there is no way of knowing which entities a new tag might refer to. The best advice is to use the same entity tags in your custom model as are used in the standard spaCy models when referring to similar entity classes.
489
+
490
+
For many entity tags, the impact will be minimal if you cannot adhere to this, but what is crucial is that you use the `PERSON` and `PER` tags to refer to people in English and German respectively. If this is not possible, change the language-specific-rule code and reinstall Coreferee locally (`python -m pip install .` from the root directory).
491
+
492
+
<aid="version-history"></a>
493
+
#### 6 Version history
494
+
495
+
<aid="version-100"></a>
496
+
##### 6.1 Version 1.0.0
497
+
498
+
The initial open-source version.
499
+
500
+
<aid="version-101"></a>
501
+
##### 6.2 Version 1.0.1
502
+
503
+
- Fixing of a bug where already installed models were reinstalled from `site-packages` rather than the new model being pulled from GitHub.
504
+
505
+
<aid="version-110"></a>
506
+
##### 6.3 Version 1.1.0
507
+
508
+
- Upgrade to Python 3.9 and spaCy 3.1
509
+
- Fixing of minor issues in all three rule-sets
510
+
- Regeneration of all models
511
+
- Improvement of the Polish examples in [section 1.4.1](#covered-relevant-linguistic-features) to make them more pragmatically correct - many thanks to Małgorzata Styś for her valuable advice on this.
512
+
472
513
<aid="open-issues"></a>
473
-
### 5. Open issues / requests for assistance
514
+
### 7. Open issues / requests for assistance
474
515
475
516
1) At present Coreferee uses Keras with TensorFlow, which leads to the limitation that `nlp.pipe()` cannot be called with `n_process > 1` with forked processes. It would be greatly preferable if Coreferee could be converted to use Thinc instead: this would get rid of this limitation and generally fit much better into the spaCy ecosystem.
Coreferences are situations where two or more words within a text refer to the same entity, e.g. *__John__ went home because __he__ was tired*. Resolving coreferences is an important general task within the natural language processing field.
2
2
3
-
<b>Coreferee</b> is a Python 3 library (tested with version 3.8.7) that is used together with [spaCy](https://spacy.io/) (tested with version 3.0.5) to resolve coreferences within English, German and Polish texts. It is designed so that it is easy to add support for new languages. It uses a mixture of neural networks and programmed rules.
3
+
<b>Coreferee</b> is a Python 3 library (tested with version 3.9.5) that is used together with [spaCy](https://spacy.io/) (tested with version 3.1.2) to resolve coreferences within English, German and Polish texts. It is designed so that it is easy to add support for new languages. It uses a mixture of neural networks and programmed rules.
4
4
5
5
For more information, please see the [main documentation on GitHub](https://github.com/msg-systems/coreferee).
0 commit comments