Update README.md

README.md

@@ -9,32 +9,131 @@ datasets:
 inference: false
 ---
 
-## Flair NER model `en-ner-conll03-v0.4.pt`
+## English NER in Flair (default model)
 
-Imported from https://nlp.informatik.hu-berlin.de/resources/models/ner/
+This is the standard 4-class NER model for German that ships with [Flair](https://github.com/flairNLP/flair/).
+
+F1-Score: **87,94** (CoNLL-03 German revised)
+
+Predicts 4 tags:
+
+| **tag**                        | **meaning** |
+|---------------------------------|-----------|
+| PER         | person name | 
+| LOC         | location name | 
+| ORG         | organization name | 
+| MISC         | other name | 
+
+Based on [Flair embeddings](https://www.aclweb.org/anthology/C18-1139/) and LSTM-CRF.
+
+---
 
 ### Demo: How to use in Flair
 
+Requires: **[Flair](https://github.com/flairNLP/flair/)** (`pip install flair`)
+
 ```python
 from flair.data import Sentence
 from flair.models import SequenceTagger
 
-sentence = Sentence(
-	"My name is Julien, I currently live in Paris, I work at Hugging Face, Inc."
-)
-
-tagger = SequenceTagger.load("julien-c/flair-ner")
+# load tagger
+tagger = SequenceTagger.load("flair/ner-german")
 
+# make example sentence
+sentence = Sentence("George Washington ging nach Washington")
 
 # predict NER tags
 tagger.predict(sentence)
 
-# print sentence with predicted tags
-print(sentence.to_tagged_string())
+# print sentence
+print(sentence)
+
+# print predicted NER spans
+print('The following NER tags are found:')
+# iterate over entities and print
+for entity in sentence.get_spans('ner'):
+    print(entity)
+
+```
+
+This yields the following output:
+```
+Span [1,2]: "George Washington"   [− Labels: PER (0.9968)]
+Span [5]: "Washington"   [− Labels: LOC (0.9994)]
+```
+
+So, the entities "*George Washington*" (labeled as a **person**) and "*Washington*" (labeled as a **location**) are found in the sentence "*George Washington went to Washington*". 
+
+
+---
+
+### Training: Script to train this model
+
+The following Flair script was used to train this model: 
 
+```python
+from flair.data import Corpus
+from flair.datasets import CONLL_03_GERMAN
+from flair.embeddings import WordEmbeddings, StackedEmbeddings, FlairEmbeddings
+
+# 1. get the corpus
+corpus: Corpus = CONLL_03_GERMAN()
+
+# 2. what tag do we want to predict?
+tag_type = 'ner'
+
+# 3. make the tag dictionary from the corpus
+tag_dictionary = corpus.make_tag_dictionary(tag_type=tag_type)
+
+# 4. initialize each embedding we use
+embedding_types = [
+
+    # GloVe embeddings
+    WordEmbeddings('de'),
+
+    # contextual string embeddings, forward
+    FlairEmbeddings('de-forward'),
+
+    # contextual string embeddings, backward
+    FlairEmbeddings('de-backward'),
+]
+
+# embedding stack consists of Flair and GloVe embeddings
+embeddings = StackedEmbeddings(embeddings=embedding_types)
+
+# 5. initialize sequence tagger
+from flair.models import SequenceTagger
+
+tagger = SequenceTagger(hidden_size=256,
+                        embeddings=embeddings,
+                        tag_dictionary=tag_dictionary,
+                        tag_type=tag_type)
+
+# 6. initialize trainer
+from flair.trainers import ModelTrainer
 
+trainer = ModelTrainer(tagger, corpus)
+
+# 7. run training
+trainer.train('resources/taggers/ner-german',
+              train_with_dev=True,
+              max_epochs=150)
 ```
 
-yields the following output:
 
-> `My name is Julien <S-PER> , I currently live in Paris <S-LOC> , I work at Hugging <B-LOC> Face <E-LOC> .`
+
+---
+
+### Cite
+
+Please cite the following paper when using this model.
+
+```
+@inproceedings{akbik2018coling,
+  title={Contextual String Embeddings for Sequence Labeling},
+  author={Akbik, Alan and Blythe, Duncan and Vollgraf, Roland},
+  booktitle = {{COLING} 2018, 27th International Conference on Computational Linguistics},
+  pages     = {1638--1649},
+  year      = {2018}
+}
+```