Update Space (evaluate main: 828c6327)

README.md

@@ -1,12 +1,138 @@
 ---
-title: Cer
-emoji: 💻
-colorFrom: purple
-colorTo: blue
+title: CER
+emoji: 🤗 
+colorFrom: blue
+colorTo: red
 sdk: gradio
 sdk_version: 3.0.2
 app_file: app.py
 pinned: false
+tags:
+- evaluate
+- metric
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces#reference
+# Metric Card for CER
+
+## Metric description
+
+Character error rate (CER) is a common metric of the performance of an automatic speech recognition (ASR) system. CER is similar to Word Error Rate (WER), but operates on character instead of word. 
+
+Character error rate can be computed as: 
+
+`CER = (S + D + I) / N = (S + D + I) / (S + D + C)`
+
+where
+
+`S` is the number of substitutions, 
+
+`D` is the number of deletions, 
+
+`I` is the number of insertions, 
+
+`C` is the number of correct characters, 
+
+`N` is the number of characters in the reference (`N=S+D+C`). 
+
+
+## How to use 
+
+The metric takes two inputs: references (a list of references for each speech input) and predictions (a list of transcriptions to score).
+
+```python
+from evaluate import load
+cer = load("cer")
+cer_score = cer.compute(predictions=predictions, references=references)
+```
+## Output values
+
+This metric outputs a float representing the character error rate.
+
+```
+print(cer_score)
+0.34146341463414637
+```
+
+The **lower** the CER value, the **better** the performance of the ASR system, with a CER of 0 being a perfect score. 
+
+However, CER's output is not always a number between 0 and 1, in particular when there is a high number of insertions (see [Examples](#Examples) below).
+
+### Values from popular papers
+
+This metric is highly dependent on the content and quality of the dataset, and therefore users can expect very different values for the same model but on different datasets.
+
+Multilingual datasets such as [Common Voice](https://huggingface.co/datasets/common_voice) report different CERs depending on the language, ranging from 0.02-0.03 for languages such as French and Italian, to 0.05-0.07 for English (see [here](https://github.com/speechbrain/speechbrain/tree/develop/recipes/CommonVoice/ASR/CTC) for more values).
+
+## Examples 
+
+Perfect match between prediction and reference:
+
+```python
+from evaluate import load
+cer = load("cer")
+predictions = ["hello world", "good night moon"]
+references = ["hello world", "good night moon"]
+cer_score = cer.compute(predictions=predictions, references=references)
+print(cer_score)
+0.0
+```
+
+Partial match between prediction and reference:
+
+```python
+from evaluate import load
+cer = load("cer")
+predictions = ["this is the prediction", "there is an other sample"]
+references = ["this is the reference", "there is another one"]
+cer_score = cer.compute(predictions=predictions, references=references)
+print(cer_score)
+0.34146341463414637
+```
+
+No match between prediction and reference:
+
+```python
+from evaluate import load
+cer = load("cer")
+predictions = ["hello"]
+references = ["gracias"]
+cer_score = cer.compute(predictions=predictions, references=references)
+print(cer_score)
+1.0
+```
+
+CER above 1 due to insertion errors:
+
+```python
+from evaluate import load
+cer = load("cer")
+predictions = ["hello world"]
+references = ["hello"]
+cer_score = cer.compute(predictions=predictions, references=references)
+print(cer_score)
+1.2
+```
+
+## Limitations and bias
+
+CER is useful for comparing different models for tasks such as automatic speech recognition (ASR) and optic character recognition (OCR), especially for multilingual datasets where WER is not suitable given the diversity of languages. However, CER provides no details on the nature of translation errors and further work is therefore required to identify the main source(s) of error and to focus any research effort.
+
+Also, in some cases, instead of reporting the raw CER, a normalized CER is reported where the number of mistakes is divided by the sum of the number of edit operations (`I` + `S` + `D`) and `C` (the number of correct characters), which results in CER values that fall within the range of 0–100%.
+
+
+## Citation
+
+
+```bibtex
+@inproceedings{morris2004,
+author = {Morris, Andrew and Maier, Viktoria and Green, Phil},
+year = {2004},
+month = {01},
+pages = {},
+title = {From WER and RIL to MER and WIL: improved evaluation measures for connected speech recognition.}
+}
+```
+
+## Further References 
+
+- [Hugging Face Tasks -- Automatic Speech Recognition](https://huggingface.co/tasks/automatic-speech-recognition)

app.py

@@ -0,0 +1,6 @@
+import evaluate
+from evaluate.utils import launch_gradio_widget
+
+
+module = evaluate.load("cer")
+launch_gradio_widget(module)

cer.py

@@ -0,0 +1,159 @@
+# Copyright 2021 The HuggingFace Evaluate Authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+""" Character Error Ratio (CER) metric. """
+
+from typing import List
+
+import datasets
+import jiwer
+import jiwer.transforms as tr
+from datasets.config import PY_VERSION
+from packaging import version
+
+import evaluate
+
+
+if PY_VERSION < version.parse("3.8"):
+    import importlib_metadata
+else:
+    import importlib.metadata as importlib_metadata
+
+
+SENTENCE_DELIMITER = ""
+
+
+if version.parse(importlib_metadata.version("jiwer")) < version.parse("2.3.0"):
+
+    class SentencesToListOfCharacters(tr.AbstractTransform):
+        def __init__(self, sentence_delimiter: str = " "):
+            self.sentence_delimiter = sentence_delimiter
+
+        def process_string(self, s: str):
+            return list(s)
+
+        def process_list(self, inp: List[str]):
+            chars = []
+            for sent_idx, sentence in enumerate(inp):
+                chars.extend(self.process_string(sentence))
+                if self.sentence_delimiter is not None and self.sentence_delimiter != "" and sent_idx < len(inp) - 1:
+                    chars.append(self.sentence_delimiter)
+            return chars
+
+    cer_transform = tr.Compose(
+        [tr.RemoveMultipleSpaces(), tr.Strip(), SentencesToListOfCharacters(SENTENCE_DELIMITER)]
+    )
+else:
+    cer_transform = tr.Compose(
+        [
+            tr.RemoveMultipleSpaces(),
+            tr.Strip(),
+            tr.ReduceToSingleSentence(SENTENCE_DELIMITER),
+            tr.ReduceToListOfListOfChars(),
+        ]
+    )
+
+
+_CITATION = """\
+@inproceedings{inproceedings,
+    author = {Morris, Andrew and Maier, Viktoria and Green, Phil},
+    year = {2004},
+    month = {01},
+    pages = {},
+    title = {From WER and RIL to MER and WIL: improved evaluation measures for connected speech recognition.}
+}
+"""
+
+_DESCRIPTION = """\
+Character error rate (CER) is a common metric of the performance of an automatic speech recognition system.
+
+CER is similar to Word Error Rate (WER), but operates on character instead of word. Please refer to docs of WER for further information.
+
+Character error rate can be computed as:
+
+CER = (S + D + I) / N = (S + D + I) / (S + D + C)
+
+where
+
+S is the number of substitutions,
+D is the number of deletions,
+I is the number of insertions,
+C is the number of correct characters,
+N is the number of characters in the reference (N=S+D+C).
+
+CER's output is not always a number between 0 and 1, in particular when there is a high number of insertions. This value is often associated to the percentage of characters that were incorrectly predicted. The lower the value, the better the
+performance of the ASR system with a CER of 0 being a perfect score.
+"""
+
+_KWARGS_DESCRIPTION = """
+Computes CER score of transcribed segments against references.
+Args:
+    references: list of references for each speech input.
+    predictions: list of transcribtions to score.
+    concatenate_texts: Whether or not to concatenate sentences before evaluation, set to True for more accurate result.
+Returns:
+    (float): the character error rate
+
+Examples:
+
+    >>> predictions = ["this is the prediction", "there is an other sample"]
+    >>> references = ["this is the reference", "there is another one"]
+    >>> cer = evaluate.load("cer")
+    >>> cer_score = cer.compute(predictions=predictions, references=references)
+    >>> print(cer_score)
+    0.34146341463414637
+"""
+
+
+@evaluate.utils.file_utils.add_start_docstrings(_DESCRIPTION, _KWARGS_DESCRIPTION)
+class CER(evaluate.EvaluationModule):
+    def _info(self):
+        return evaluate.EvaluationModuleInfo(
+            description=_DESCRIPTION,
+            citation=_CITATION,
+            inputs_description=_KWARGS_DESCRIPTION,
+            features=datasets.Features(
+                {
+                    "predictions": datasets.Value("string", id="sequence"),
+                    "references": datasets.Value("string", id="sequence"),
+                }
+            ),
+            codebase_urls=["https://github.com/jitsi/jiwer/"],
+            reference_urls=[
+                "https://en.wikipedia.org/wiki/Word_error_rate",
+                "https://sites.google.com/site/textdigitisation/qualitymeasures/computingerrorrates",
+            ],
+        )
+
+    def _compute(self, predictions, references, concatenate_texts=False):
+        if concatenate_texts:
+            return jiwer.compute_measures(
+                references,
+                predictions,
+                truth_transform=cer_transform,
+                hypothesis_transform=cer_transform,
+            )["wer"]
+
+        incorrect = 0
+        total = 0
+        for prediction, reference in zip(predictions, references):
+            measures = jiwer.compute_measures(
+                reference,
+                prediction,
+                truth_transform=cer_transform,
+                hypothesis_transform=cer_transform,
+            )
+            incorrect += measures["substitutions"] + measures["deletions"] + measures["insertions"]
+            total += measures["substitutions"] + measures["deletions"] + measures["hits"]
+
+        return incorrect / total

requirements.txt

@@ -0,0 +1,4 @@
+# TODO: fix github to release
+git+https://github.com/huggingface/evaluate.git@b6e6ed7f3e6844b297bff1b43a1b4be0709b9671
+datasets~=2.0
+jiwer

test_cer.py

@@ -0,0 +1,128 @@
+# Copyright 2021 The HuggingFace Evaluate Authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+import unittest
+
+from cer import CER
+
+
+cer = CER()
+
+
+class TestCER(unittest.TestCase):
+    def test_cer_case_senstive(self):
+        refs = ["White House"]
+        preds = ["white house"]
+        # S = 2, D = 0, I = 0, N = 11, CER = 2 / 11
+        char_error_rate = cer.compute(predictions=preds, references=refs)
+        self.assertTrue(abs(char_error_rate - 0.1818181818) < 1e-6)
+
+    def test_cer_whitespace(self):
+        refs = ["were wolf"]
+        preds = ["werewolf"]
+        # S = 0, D = 0, I = 1, N = 9, CER = 1 / 9
+        char_error_rate = cer.compute(predictions=preds, references=refs)
+        self.assertTrue(abs(char_error_rate - 0.1111111) < 1e-6)
+
+        refs = ["werewolf"]
+        preds = ["weae     wolf"]
+        # S = 1, D = 1, I = 0, N = 8, CER = 0.25
+        char_error_rate = cer.compute(predictions=preds, references=refs)
+        self.assertTrue(abs(char_error_rate - 0.25) < 1e-6)
+
+        # consecutive whitespaces case 1
+        refs = ["were wolf"]
+        preds = ["were               wolf"]
+        # S = 0, D = 0, I = 0, N = 9, CER = 0
+        char_error_rate = cer.compute(predictions=preds, references=refs)
+        self.assertTrue(abs(char_error_rate - 0.0) < 1e-6)
+
+        # consecutive whitespaces case 2
+        refs = ["were   wolf"]
+        preds = ["were               wolf"]
+        # S = 0, D = 0, I = 0, N = 9, CER = 0
+        char_error_rate = cer.compute(predictions=preds, references=refs)
+        self.assertTrue(abs(char_error_rate - 0.0) < 1e-6)
+
+    def test_cer_sub(self):
+        refs = ["werewolf"]
+        preds = ["weaewolf"]
+        # S = 1, D = 0, I = 0, N = 8, CER = 0.125
+        char_error_rate = cer.compute(predictions=preds, references=refs)
+        self.assertTrue(abs(char_error_rate - 0.125) < 1e-6)
+
+    def test_cer_del(self):
+        refs = ["werewolf"]
+        preds = ["wereawolf"]
+        # S = 0, D = 1, I = 0, N = 8, CER = 0.125
+        char_error_rate = cer.compute(predictions=preds, references=refs)
+        self.assertTrue(abs(char_error_rate - 0.125) < 1e-6)
+
+    def test_cer_insert(self):
+        refs = ["werewolf"]
+        preds = ["wereolf"]
+        # S = 0, D = 0, I = 1, N = 8, CER = 0.125
+        char_error_rate = cer.compute(predictions=preds, references=refs)
+        self.assertTrue(abs(char_error_rate - 0.125) < 1e-6)
+
+    def test_cer_equal(self):
+        refs = ["werewolf"]
+        char_error_rate = cer.compute(predictions=refs, references=refs)
+        self.assertEqual(char_error_rate, 0.0)
+
+    def test_cer_list_of_seqs(self):
+        refs = ["werewolf", "I am your father"]
+        char_error_rate = cer.compute(predictions=refs, references=refs)
+        self.assertEqual(char_error_rate, 0.0)
+
+        refs = ["werewolf", "I am your father", "doge"]
+        preds = ["werxwolf", "I       am your father", "doge"]
+        # S = 1, D = 0, I = 0, N = 28, CER = 1 / 28
+        char_error_rate = cer.compute(predictions=preds, references=refs)
+        self.assertTrue(abs(char_error_rate - 0.03571428) < 1e-6)
+
+    def test_correlated_sentences(self):
+        refs = ["My hovercraft", "is full of eels"]
+        preds = ["My hovercraft is full", " of eels"]
+        # S = 0, D = 0, I = 2, N = 28, CER = 2 / 28
+        # whitespace at the front of " of eels" will be strip during preporcessing
+        # so need to insert 2 whitespaces
+        char_error_rate = cer.compute(predictions=preds, references=refs, concatenate_texts=True)
+        self.assertTrue(abs(char_error_rate - 0.071428) < 1e-6)
+
+    def test_cer_unicode(self):
+        refs = ["我能吞下玻璃而不伤身体"]
+        preds = [" 能吞虾玻璃而 不霜身体啦"]
+        # S = 3, D = 2, I = 0, N = 11, CER = 5 / 11
+        char_error_rate = cer.compute(predictions=preds, references=refs)
+        self.assertTrue(abs(char_error_rate - 0.4545454545) < 1e-6)
+
+        refs = ["我能吞下玻璃", "而不伤身体"]
+        preds = ["我    能 吞 下 玻 璃", "而不伤身体"]
+        # S = 0, D = 5, I = 0, N = 11, CER = 5 / 11
+        char_error_rate = cer.compute(predictions=preds, references=refs)
+        self.assertTrue(abs(char_error_rate - 0.454545454545) < 1e-6)
+
+        refs = ["我能吞下玻璃而不伤身体"]
+        char_error_rate = cer.compute(predictions=refs, references=refs)
+        self.assertFalse(char_error_rate, 0.0)
+
+    def test_cer_empty(self):
+        refs = [""]
+        preds = ["Hypothesis"]
+        with self.assertRaises(ValueError):
+            cer.compute(predictions=preds, references=refs)
+
+
+if __name__ == "__main__":
+    unittest.main()