complete Readme

README.md

@@ -0,0 +1,206 @@
+---
+language: "ca"
+tags:
+- masked-lm
+- BERTa
+- catalan
+---
+
+# BERTa: RoBERTa-based Catalan language model
+
+## 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
+
+The training corpus consists of several corpora gathered from web crawling and public corpora.
+
+The publicly available corpora are:
+
+ 1. the Catalan part of the [DOGC](http://opus.nlpl.eu/DOGC-v2.php) corpus, a set of documents from the Official Gazette of the Catalan Government
+    
+ 2. the [Catalan Open Subtitles](http://opus.nlpl.eu/download.php?f=OpenSubtitles/v2018/mono/OpenSubtitles.raw.ca.gz), a collection of translated movie subtitles
+    
+ 3. the non-shuffled version of the Catalan part of the [OSCAR](https://traces1.inria.fr/oscar/) corpus \cite{suarez2019asynchronous}, 
+    a collection of monolingual corpora, filtered from [Common Crawl](https://commoncrawl.org/about/)
+    
+ 4. The [CaWac](http://nlp.ffzg.hr/resources/corpora/cawac/) corpus, a web corpus of Catalan built from the .cat top-level-domain in late 2013
+    the non-deduplicated version
+
+ 5. the [Catalan Wikipedia articles](https://ftp.acc.umu.se/mirror/wikimedia.org/dumps/cawiki/20200801/) downloaded on 18-08-2020.
+
+The crawled corpora are:
+
+ 6. The Catalan General Crawling, obtained by crawling the 500 most popular .cat and .ad domains
+ 7. the Catalan Government Crawling, obtained by crawling the .gencat domain and subdomains, belonging to the Catalan Government
+    
+ 8. the ACN corpus with 220k news items from March 2015 until October 2020, crawled from the [Catalan News Agency](https://www.acn.cat/)
+
+To obtain a high-quality training corpus, each corpus have preprocessed with a pipeline of operations, including among the others,
+sentence splitting, language detection, filtering of bad-formed sentences and deduplication of repetitive contents.
+During the process, we keep document boundaries are kept. 
+Finally, the corpora are concatenated and further global deduplication among the corpora is applied.
+The final training corpus consists of about 1,8B tokens.
+
+
+## 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
+
+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.
+
+It contains the following tasks and their related datasets:
+
+ 1. Part-of-Speech Tagging (POS)
+    
+    **Catalan-Ancora**: from the [Universal Dependencies treebank](https://github.com/UniversalDependencies/UD_Catalan-AnCora) of the well-known Ancora corpus
+
+ 2. Named Entity Recognition (NER)
+    
+    **[AnCora Catalan 2.0.0](https://zenodo.org/record/4762031#.YKaFjqGxWUk)**: extracted named entities from the original [Ancora](https://doi.org/10.5281/zenodo.4762030) version,
+    filtering out some unconventional ones, like book titles, and transcribed them into a standard CONLL-IOB format
+
+ 3. Text Classification (TC)
+     
+    **[TeCla](https://doi.org/10.5281/zenodo.4627197)**: consisting of 137k news pieces from the Catalan News Agency ([ACN](https://www.acn.cat/)) corpus
+
+ 4. Semantic Texual Similarity (STS)
+    
+    **[Catalan semantic texual similarity](https://doi.org/10.5281/zenodo.4529183)**: consting of more than 3000 sentence pairs, annotated with the semantic similarity between them, 
+    scraped from the [Catalan Textual Corpus](https://doi.org/10.5281/zenodo.4519349)
+
+ 5. Question Answering (QA):
+    
+    **[ViquiQuAD](https://doi.org/10.5281/zenodo.4562344)**: consisting of more than 15,000 questions outsourced from Catalan Wikipedia randomly chosen from a set of 596 articles which were
+                   originally written in Catalan.
+    
+    **[XQuAD](https://doi.org/10.5281/zenodo.4526223)**: the Catalan translation of XQuAD, a multilingual collection of manual translations of 1,190 
+               question-answer pairs from English Wikipedia used only as test set
+
+## Results
+
+Below the evaluation results on the CLUB tasks compared with the multilingual mBERT, XLM-RoBERTa models and 
+the Catalan WikiBERT-ca model
+
+
+| Task        | NER (F1)      | POS (F1)   | STS (Pearson)   | TC (accuracy) | QA (ViquiQuAD) (F1/EM)  | QA (XQuAD) (F1/EM) | 
+| ------------|:-------------:| -----:|:------|:-------|:------|:----|
+| BERTa       | **88.13** | **98.97** | **79.73** | **74.16** | **86.97/72.29** | **68.89/48.87** |
+| mBERT       | 86.38 | 98.82 | 76.34 | 70.56 | 86.97/72.22 | 67.15/46.51 |
+| XLM-RoBERTa | 87.66 | 98.89 | 75.40 | 71.68 | 85.50/70.47 | 67.10/46.42 |
+| 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("bsc/roberta-base-ca-cased")
+
+model = AutoModelForMaskedLM.from_pretrained("bsc/roberta-base-ca-cased")
+```
+
+## Fill Mask task
+
+Below, an example of how to use the masked language modeling task with a pipeline.
+
+```python
+>>> from transformers import pipeline
+>>> unmasker = pipeline('fill-mask', model='bsc/roberta-base')
+>>> 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à"
+  }
+]
+```
+
+
+
+### BibTeX  citation
+
+```bibtex
+Armengol-Estapé J., Carrino CP., Rodriguez-Penagos C., 
+de Gibert Bonet O., Armentano-Oller C., Gonzalez-Agirre A., Melero M. 
+and Villegas M., "Are Multilingual Models the Best Choice for Moderately 
+Under-resourced Languages? A Comprehensive Assessment for Catalan". 
+Findings of ACL 2021 (ACL-IJCNLP 2021)
+```