Update README.md

README.md

@@ -18,40 +18,128 @@ license: apache-2.0
 
 # BERTa: RoBERTa-based Catalan language model
 
-## BibTeX  citation
-
-If you use any of these resources (datasets or models) in your work, please cite our latest paper:
-
-```bibtex
-@inproceedings{armengol-estape-etal-2021-multilingual,
-    title = "Are Multilingual Models the Best Choice for Moderately Under-resourced Languages? {A} Comprehensive Assessment for {C}atalan",
-    author = "Armengol-Estap{\'e}, Jordi  and
-      Carrino, Casimiro Pio  and
-      Rodriguez-Penagos, Carlos  and
-      de Gibert Bonet, Ona  and
-      Armentano-Oller, Carme  and
-      Gonzalez-Agirre, Aitor  and
-      Melero, Maite  and
-      Villegas, Marta",
-    booktitle = "Findings of the Association for Computational Linguistics: ACL-IJCNLP 2021",
-    month = aug,
-    year = "2021",
-    address = "Online",
-    publisher = "Association for Computational Linguistics",
-    url = "https://aclanthology.org/2021.findings-acl.437",
-    doi = "10.18653/v1/2021.findings-acl.437",
-    pages = "4933--4946",
-}
-```
+## Table of contents
+<details>
+<summary>Click to expand</summary>
+
+- [Model description](#model-description)
+- [Intended uses and limitations](#intended-use)
+- [How to use](#how-to-use)
+- [Limitations and bias](#limitations-and-bias)
+- [Training](#training)
+- [Evaluation](#evaluation)
+- [Additional information](#additional-information)
+  - [Author](#author)
+  - [Contact information](#contact-information)
+  - [Copyright](#copyright)
+  - [Licensing information](#licensing-information)
+  - [Funding](#funding)
+  - [Citing information](#citing-information)
+  - [Disclaimer](#disclaimer)
+  
+</details>
 
 
 ## Model description
-
 BERTa is a transformer-based masked language model for the Catalan language. 
 It is based on the [RoBERTA](https://github.com/pytorch/fairseq/tree/master/examples/roberta) base model 
 and has been trained on a medium-size corpus collected from publicly available corpora and crawlers.
 
-## Training corpora and preprocessing
+This model was originally published as [bsc/roberta-base-ca-cased](https://huggingface.co/bsc/roberta-base-ca-cased).
+
+## Intended uses and limitations
+The model is ready-to-use only for masked language modelling to perform the Fill Mask task (try the inference API or read the next section). 
+However, it is intended to be fine-tuned on non-generative downstream tasks such as Question Answering, Text Classification or Named Entity Recognition.
+
+
+## How to use
+
+### Load model and tokenizer
+
+``` python
+from transformers import AutoTokenizer, AutoModelForMaskedLM
+tokenizer = AutoTokenizer.from_pretrained("PlanTL-GOB-ES/roberta-base-ca-cased")
+model = AutoModelForMaskedLM.from_pretrained("PlanTL-GOB-ES/roberta-base-ca-cased")
+```
+
+### Fill Mask task
+
+Below, an example of how to use the masked language modelling task with a pipeline.
+
+```python
+>>> from transformers import pipeline
+>>> unmasker = pipeline('fill-mask', model='PlanTL-GOB-ES/roberta-base-ca-cased')
+>>> unmasker("Situada a la costa de la mar Mediterrània, <mask> s'assenta en una plana formada "
+             "entre els deltes de les desembocadures dels rius Llobregat, al sud-oest, "
+             "i Besòs, al nord-est, i limitada pel sud-est per la línia de costa,"
+             "i pel nord-oest per la serralada de Collserola "
+             "(amb el cim del Tibidabo, 516,2 m, com a punt més alt) que segueix paral·lela "
+             "la línia de costa encaixant la ciutat en un perímetre molt definit.")
+
+[
+  {
+    "sequence": " Situada a la costa de la mar Mediterrània, <mask> s'assenta en una plana formada "
+                "entre els deltes de les desembocadures dels rius Llobregat, al sud-oest, "
+                "i Besòs, al nord-est, i limitada pel sud-est per la línia de costa,"
+                "i pel nord-oest per la serralada de Collserola "
+                "(amb el cim del Tibidabo, 516,2 m, com a punt més alt) que segueix paral·lela "
+                "la línia de costa encaixant la ciutat en un perímetre molt definit.",
+    "score": 0.4177263379096985,
+    "token": 734,
+    "token_str": " Barcelona"
+  },
+  {
+    "sequence": " Situada a la costa de la mar Mediterrània, <mask> s'assenta en una plana formada "
+                "entre els deltes de les desembocadures dels rius Llobregat, al sud-oest, "
+                "i Besòs, al nord-est, i limitada pel sud-est per la línia de costa,"
+                "i pel nord-oest per la serralada de Collserola "
+                "(amb el cim del Tibidabo, 516,2 m, com a punt més alt) que segueix paral·lela "
+                "la línia de costa encaixant la ciutat en un perímetre molt definit.",
+    "score": 0.10696165263652802,
+    "token": 3849,
+    "token_str": " Badalona"
+  },
+  {
+    "sequence": " Situada a la costa de la mar Mediterrània, <mask> s'assenta en una plana formada "
+                "entre els deltes de les desembocadures dels rius Llobregat, al sud-oest, "
+                "i Besòs, al nord-est, i limitada pel sud-est per la línia de costa,"
+                "i pel nord-oest per la serralada de Collserola "
+                "(amb el cim del Tibidabo, 516,2 m, com a punt més alt) que segueix paral·lela "
+                "la línia de costa encaixant la ciutat en un perímetre molt definit.",
+    "score": 0.08135009557008743,
+    "token": 19349,
+    "token_str": " Collserola"
+  },
+  {
+   "sequence": " Situada a la costa de la mar Mediterrània, <mask> s'assenta en una plana formada "
+                "entre els deltes de les desembocadures dels rius Llobregat, al sud-oest, "
+                "i Besòs, al nord-est, i limitada pel sud-est per la línia de costa,"
+                "i pel nord-oest per la serralada de Collserola "
+                "(amb el cim del Tibidabo, 516,2 m, com a punt més alt) que segueix paral·lela "
+                "la línia de costa encaixant la ciutat en un perímetre molt definit.",
+    "score": 0.07330769300460815,
+    "token": 4974,
+    "token_str": " Terrassa"
+  },
+  {
+    "sequence": " Situada a la costa de la mar Mediterrània, <mask> s'assenta en una plana formada "
+                "entre els deltes de les desembocadures dels rius Llobregat, al sud-oest, "
+                "i Besòs, al nord-est, i limitada pel sud-est per la línia de costa,"
+                "i pel nord-oest per la serralada de Collserola "
+                "(amb el cim del Tibidabo, 516,2 m, com a punt més alt) que segueix paral·lela "
+                "la línia de costa encaixant la ciutat en un perímetre molt definit.",
+    "score": 0.03317456692457199,
+    "token": 14333,
+    "token_str": " Gavà"
+  }
+]
+```
+
+
+## Limitations and bias
+
+## Training
+### Training corpora and preprocessing
 
 The training corpus consists of several corpora gathered from web crawling and public corpora.
 
@@ -83,17 +171,19 @@ Finally, the corpora are concatenated and further global deduplication among the
 The final training corpus consists of about 1,8B tokens.
 
 
-## Tokenization and pretraining 
+### Tokenization and pretraining 
 
 The training corpus has been tokenized using a byte version of [Byte-Pair Encoding (BPE)](https://github.com/openai/gpt-2)
 used in the original [RoBERTA](https://github.com/pytorch/fairseq/tree/master/examples/roberta) model with a vocabulary size of 52,000 tokens. 
+
 The BERTa pretraining consists of a masked language model training that follows the approach employed for the RoBERTa base model
 with the same hyperparameters as in the original work.
+
 The training lasted a total of 48 hours with 16 NVIDIA V100 GPUs of 16GB DDRAM.
 
 ## Evaluation
 
-## CLUB benchmark
+### CLUB benchmark
 
 The BERTa model has been fine-tuned on the downstream tasks of the Catalan Language Understanding Evaluation benchmark (CLUB),
 that has been created along with the model.
@@ -137,7 +227,7 @@ Here are the train/dev/test splits of the datasets:
 
 _The fine-tuning on downstream tasks have been performed with the HuggingFace [**Transformers**](https://github.com/huggingface/transformers) library_
 
-## Results
+### Results
 
 Below the evaluation results on the CLUB tasks compared with the multilingual mBERT, XLM-RoBERTa models and 
 the Catalan WikiBERT-ca model
@@ -151,112 +241,50 @@ the Catalan WikiBERT-ca model
 | WikiBERT-ca | 77.66 | 97.60 | 77.18 | 73.22 | 85.45/70.75 | 65.21/36.60 |
 
 
-## Intended uses & limitations
-The model is ready-to-use only for masked language modelling to perform the Fill Mask task (try the inference API or read the next section)
-However, the is intended to be fine-tuned on non-generative downstream tasks such as Question Answering, Text Classification or Named Entity Recognition.
-
----
-
-## Using BERTa 
-## Load model and tokenizer
-
-``` python
-from transformers import AutoTokenizer, AutoModelForMaskedLM
-    
-tokenizer = AutoTokenizer.from_pretrained("PlanTL-GOB-ES/roberta-base-ca-cased")
-
-model = AutoModelForMaskedLM.from_pretrained("PlanTL-GOB-ES/roberta-base-ca-cased")
-```
-
-## Fill Mask task
-
-Below, an example of how to use the masked language modelling task with a pipeline.
-
-```python
->>> from transformers import pipeline
->>> unmasker = pipeline('fill-mask', model='PlanTL-GOB-ES/roberta-base-ca-cased')
->>> unmasker("Situada a la costa de la mar Mediterrània, <mask> s'assenta en una plana formada "
-             "entre els deltes de les desembocadures dels rius Llobregat, al sud-oest, "
-             "i Besòs, al nord-est, i limitada pel sud-est per la línia de costa,"
-             "i pel nord-oest per la serralada de Collserola "
-             "(amb el cim del Tibidabo, 516,2 m, com a punt més alt) que segueix paral·lela "
-             "la línia de costa encaixant la ciutat en un perímetre molt definit.")
-
-[
-  {
-    "sequence": " Situada a la costa de la mar Mediterrània, <mask> s'assenta en una plana formada "
-                "entre els deltes de les desembocadures dels rius Llobregat, al sud-oest, "
-                "i Besòs, al nord-est, i limitada pel sud-est per la línia de costa,"
-                "i pel nord-oest per la serralada de Collserola "
-                "(amb el cim del Tibidabo, 516,2 m, com a punt més alt) que segueix paral·lela "
-                "la línia de costa encaixant la ciutat en un perímetre molt definit.",
-    "score": 0.4177263379096985,
-    "token": 734,
-    "token_str": " Barcelona"
-  },
-  {
-    "sequence": " Situada a la costa de la mar Mediterrània, <mask> s'assenta en una plana formada "
-                "entre els deltes de les desembocadures dels rius Llobregat, al sud-oest, "
-                "i Besòs, al nord-est, i limitada pel sud-est per la línia de costa,"
-                "i pel nord-oest per la serralada de Collserola "
-                "(amb el cim del Tibidabo, 516,2 m, com a punt més alt) que segueix paral·lela "
-                "la línia de costa encaixant la ciutat en un perímetre molt definit.",
-    "score": 0.10696165263652802,
-    "token": 3849,
-    "token_str": " Badalona"
-  },
-  {
-    "sequence": " Situada a la costa de la mar Mediterrània, <mask> s'assenta en una plana formada "
-                "entre els deltes de les desembocadures dels rius Llobregat, al sud-oest, "
-                "i Besòs, al nord-est, i limitada pel sud-est per la línia de costa,"
-                "i pel nord-oest per la serralada de Collserola "
-                "(amb el cim del Tibidabo, 516,2 m, com a punt més alt) que segueix paral·lela "
-                "la línia de costa encaixant la ciutat en un perímetre molt definit.",
-    "score": 0.08135009557008743,
-    "token": 19349,
-    "token_str": " Collserola"
-  },
-  {
-   "sequence": " Situada a la costa de la mar Mediterrània, <mask> s'assenta en una plana formada "
-                "entre els deltes de les desembocadures dels rius Llobregat, al sud-oest, "
-                "i Besòs, al nord-est, i limitada pel sud-est per la línia de costa,"
-                "i pel nord-oest per la serralada de Collserola "
-                "(amb el cim del Tibidabo, 516,2 m, com a punt més alt) que segueix paral·lela "
-                "la línia de costa encaixant la ciutat en un perímetre molt definit.",
-    "score": 0.07330769300460815,
-    "token": 4974,
-    "token_str": " Terrassa"
-  },
-  {
-    "sequence": " Situada a la costa de la mar Mediterrània, <mask> s'assenta en una plana formada "
-                "entre els deltes de les desembocadures dels rius Llobregat, al sud-oest, "
-                "i Besòs, al nord-est, i limitada pel sud-est per la línia de costa,"
-                "i pel nord-oest per la serralada de Collserola "
-                "(amb el cim del Tibidabo, 516,2 m, com a punt més alt) que segueix paral·lela "
-                "la línia de costa encaixant la ciutat en un perímetre molt definit.",
-    "score": 0.03317456692457199,
-    "token": 14333,
-    "token_str": " Gavà"
-  }
-]
-```
+## Additional information
 
-This model was originally published as [bsc/roberta-base-ca-cased](https://huggingface.co/bsc/roberta-base-ca-cased).
+### Author
+Text Mining Unit (TeMU) at the Barcelona Supercomputing Center (bsc-temu@bsc.es)
 
-## Copyright
+### Contact information
+For further information, send an email to <plantl-gob-es@bsc.es>
 
+### Copyright
 Copyright by the Spanish State Secretariat for Digitalization and Artificial Intelligence (SEDIA) (2022)
 
-## Licensing information
-
+### Licensing information
 [Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0)
 
-## Funding
-
+### Funding
 This work was funded by the Spanish State Secretariat for Digitalization and Artificial Intelligence (SEDIA) within the framework of the Plan-TL.
 
-## Disclaimer
+### Citing information
+
+If you use this model, please cite our latest paper:
+
+```bibtex
+@inproceedings{armengol-estape-etal-2021-multilingual,
+    title = "Are Multilingual Models the Best Choice for Moderately Under-resourced Languages? {A} Comprehensive Assessment for {C}atalan",
+    author = "Armengol-Estap{\'e}, Jordi  and
+      Carrino, Casimiro Pio  and
+      Rodriguez-Penagos, Carlos  and
+      de Gibert Bonet, Ona  and
+      Armentano-Oller, Carme  and
+      Gonzalez-Agirre, Aitor  and
+      Melero, Maite  and
+      Villegas, Marta",
+    booktitle = "Findings of the Association for Computational Linguistics: ACL-IJCNLP 2021",
+    month = aug,
+    year = "2021",
+    address = "Online",
+    publisher = "Association for Computational Linguistics",
+    url = "https://aclanthology.org/2021.findings-acl.437",
+    doi = "10.18653/v1/2021.findings-acl.437",
+    pages = "4933--4946",
+}
+```
 
+### Disclaimer
 The models published in this repository are intended for a generalist purpose and are available to third parties. These models may have bias and/or any other undesirable distortions.
 
 When third  parties, deploy or provide systems and/or services to other parties using any of these models (or using systems based on these models) or become users of the models, they should note that it is their responsibility to mitigate the risks arising from their use and, in any event, to comply with applicable regulations, including regulations regarding the use of artificial intelligence.