Update README.md

README.md

@@ -2,36 +2,152 @@
 license: apache-2.0
 tags:
 - automatic-speech-recognition
-- experiments/data/atcosim_uwb_atcc/train
 - generated_from_trainer
 metrics:
 - wer
 model-index:
-- name: 0.0ld_0.0ad_0.0attd_0.05fpd_0.075mtp_12mtl_0.0mfp_12mfl_1acc
-  results: []
+- name: wav2vec2-xls-r-300m-en-atc-uwb-atcc-atcosim
+  results:
+  - task:
+        type: automatic-speech-recognition
+        name: Speech Recognition
+    datasets:
+        type: Jzuluaga/uwb_atcc
+        name: UWB-ATCC dataset (Air Traffic Control Communications)
+        config: test
+        split: test
+    metrics:
+    - type: wer
+      value: 0.36
+      name: TEST WER
 ---
 
-<!-- This model card has been generated automatically according to the information the Trainer had access to. You
-should probably proofread and complete it, then remove this comment. -->
+# wav2vec2-xls-r-300m-en-atc-uwb-atcc-and-atcosim
 
-# 0.0ld_0.0ad_0.0attd_0.05fpd_0.075mtp_12mtl_0.0mfp_12mfl_1acc
+This model is a fine-tuned version of [facebook/wav2vec2-xls-r-300m](https://huggingface.co/facebook/wav2vec2-xls-r-300m) on two corpus:
+- [UWB-ATCC corpus](https://huggingface.co/datasets/Jzuluaga/uwb_atcc), and
+- [ATCOSIM corpus](https://huggingface.co/datasets/Jzuluaga/atcosim_corpus). 
 
-This model is a fine-tuned version of [facebook/wav2vec2-xls-r-300m](https://huggingface.co/facebook/wav2vec2-xls-r-300m) on the EXPERIMENTS/DATA/ATCOSIM_UWB_ATCC/TRAIN - NA dataset.
-It achieves the following results on the evaluation set:
+<a href="https://colab.research.google.com/github/idiap/w2v2-air-traffic/blob/main/src/eval_xlsr_atc_model.ipynb">
+    <img alt="GitHub" src="https://colab.research.google.com/assets/colab-badge.svg\">
+</a>
+<a href="https://github.com/idiap/w2v2-air-traffic">
+    <img alt="GitHub" src="https://img.shields.io/badge/GitHub-Open%20source-green\">
+</a>
+
+
+It achieves the following results on the evaluation set (two tests sets joined together: UWB-ATCC and ATCOSIM):
 - Loss: 0.5595
 - Wer: 0.1687
 
-## Model description
+Paper: [How Does Pre-trained Wav2Vec 2.0 Perform on Domain Shifted ASR? An Extensive Benchmark on Air Traffic Control Communications](https://arxiv.org/abs/2203.16822).
+
+Authors: Juan Zuluaga-Gomez, Amrutha Prasad, Iuliia Nigmatulina, Saeed Sarfjoo, Petr Motlicek, Matthias Kleinert, Hartmut Helmke, Oliver Ohneiser, Qingran Zhan
+
+Abstract: Recent work on self-supervised pre-training focus</b> on leveraging large-scale unlabeled speech data to build robust end-to-end (E2E)acoustic models (AM) that can be later fine-tuned on downstream tasks e.g., automatic speech recognition (ASR). Yet, few works investigated the impact on performance when the data properties substantially differ between the pre-training and fine-tuning phases, termed domain shift. We target this scenario by analyzing the robustness of Wav2Vec 2.0 and XLS-R models on downstream ASR for a completely unseen domain, air traffic control (ATC) communications. We benchmark these two models on several open-source and challenging ATC databases with signal-to-noise ratio between 5 and 20 dB. Relative word error rate (WER) reductions between 20% to 40% are obtained in comparison to hybrid-based ASR baselines by only fine-tuning E2E acoustic models with a smaller fraction of labeled data. We analyze WERs on the low-resource scenario and gender bias carried by one ATC dataset.
 
-More information needed
+Code — GitHub repository: https://github.com/idiap/w2v2-air-traffic
+
+## Usage
+
+You can use our Google Colab notebook to run and evaluate our model: https://github.com/idiap/w2v2-air-traffic/blob/master/src/eval_xlsr_atc_model.ipynb
 
 ## Intended uses & limitations
 
-More information needed
+This model was fine-tuned on air traffic control data. We don't expect that it keeps the same performance on some others datasets, e.g., LibriSpeech or CommonVoice.
+
 
 ## Training and evaluation data
 
-More information needed
+See Table 1 (page 3) in our paper: [How Does Pre-trained Wav2Vec 2.0 Perform on Domain Shifted ASR? An Extensive Benchmark on Air Traffic Control Communications](https://arxiv.org/abs/2203.16822). We described there the partitions of how to use our model. 
+
+- We use the UWB-ATCC + ATCOSIM corpus to fine-tune this model. You can download the raw data here:
+  - https://lindat.mff.cuni.cz/repository/xmlui/handle/11858/00-097C-0000-0001-CCA1-0 and,
+  - https://www.spsc.tugraz.at/databases-and-tools/atcosim-air-traffic-control-simulation-speech-corpus.html
+- However, do not worry, we have prepared the database in `Datasets format`:
+  -  Here, [UWB-ATCC corpus on HuggingFace](https://huggingface.co/datasets/Jzuluaga/uwb_atcc).
+  -  Here: [ATCOSIM CORPUS on HuggingFace](https://huggingface.co/datasets/Jzuluaga/atcosim_corpus). 
+- If you want to prepare a database in HuggingFace format, you can follow the data loader script in: [data_loader_atc.py](https://huggingface.co/datasets/Jzuluaga/uwb_atcc/blob/main/atc_data_loader.py).
+
+## Writing your own inference script
+
+If you use language model, you need to install the KenLM bindings with:
+
+```bash
+conda activate your_environment
+pip install https://github.com/kpu/kenlm/archive/master.zip
+```
+
+The snippet of code:
+
+```python
+from datasets import load_dataset, load_metric, Audio
+import torch
+from transformers import AutoModelForCTC, Wav2Vec2Processor, Wav2Vec2ProcessorWithLM
+import torchaudio.functional as F
+
+USE_LM = False
+DATASET_ID = "Jzuluaga/uwb_atcc"
+MODEL_ID = "Jzuluaga/wav2vec2-xls-r-300m-en-atc-uwb-atcc-and-atcosim"
+
+# 1. Load the dataset
+# we only load the 'test' partition, however, if you want to load the 'train' partition, you can change it accordingly
+uwb_atcc_corpus_test = load_dataset(DATASET_ID, "test", split="test")
+
+# 2. Load the model
+model = AutoModelForCTC.from_pretrained(MODEL_ID)
+
+# 3. Load the processors, we offer support with LM, which should yield better resutls
+if USE_LM:
+    processor = Wav2Vec2ProcessorWithLM.from_pretrained(MODEL_ID)
+else:
+    processor = Wav2Vec2Processor.from_pretrained(MODEL_ID)
+# 4. Format the test sample
+sample = next(iter(uwb_atcc_corpus_test))
+file_sampling_rate = sample['audio']['sampling_rate']
+# resample if neccessary
+if file_sampling_rate != 16000:
+    resampled_audio = F.resample(torch.tensor(sample["audio"]["array"]), file_sampling_rate, 16000).numpy()
+else:
+    resampled_audio = torch.tensor(sample["audio"]["array"]).numpy()
+input_values = processor(resampled_audio, return_tensors="pt").input_values
+
+# 5. Run the forward pass in the model
+with torch.no_grad():
+    logits = model(input_values).logits
+    
+# get the transcription with processor
+if USE_LM:
+    transcription = processor.batch_decode(logits.numpy()).text
+else:
+    pred_ids = torch.argmax(logits, dim=-1)
+    transcription = processor.batch_decode(pred_ids)
+# print the output
+print(transcription)
+```
+
+# Cite us
+
+If you use this code for your research, please cite our paper with:
+
+```
+@article{zuluaga2022how,
+    title={How Does Pre-trained Wav2Vec2. 0 Perform on Domain Shifted ASR? An Extensive Benchmark on Air Traffic Control Communications},
+    author={Zuluaga-Gomez, Juan and Prasad, Amrutha and Nigmatulina, Iuliia and Sarfjoo, Saeed and Motlicek, Petr and Kleinert, Matthias and Helmke, Hartmut and Ohneiser, Oliver and Zhan, Qingran},
+    journal={IEEE Spoken Language Technology Workshop (SLT), Doha, Qatar},
+    year={2022}
+  }
+```
+and, 
+
+```
+@article{zuluaga2022bertraffic,
+  title={BERTraffic: BERT-based Joint Speaker Role and Speaker Change Detection for Air Traffic Control Communications},
+  author={Zuluaga-Gomez, Juan and Sarfjoo, Seyyed Saeed and Prasad, Amrutha and Nigmatulina, Iuliia and Motlicek, Petr and Ondre, Karel and Ohneiser, Oliver and Helmke, Hartmut},
+  journal={IEEE Spoken Language Technology Workshop (SLT), Doha, Qatar},
+  year={2022}
+  }
+```
 
 ## Training procedure