【HuggingFace Evaluate】機械学習に役立つ48の評価指標を数行で簡単に利用できるライブラリを解説！

HuggingFace社が新しいライブラリであるEvaluateを発表していたので、利用できる評価指標を利用例とともにまとめてみました。

Evaluateとは、モデルの評価や比較・性能の報告をより単純に、より標準的に行うためのライブラリです。
また、Hugging face Hubにアップロードし、共有する機能もあります。
もしかしたら、評価指標を使うとなったらEvaluateライブラリがスタンダードになるかもしれませんね。

～どのような評価指標が使えるかについて～
分類問題、多クラス分類、自然言語処理などで役に立つ、精度(accuracy)・適合率(precision)・再現率(recall)・F値・BLEUなど代表的なものからPerplexity・RL Reliability・ROUGEなど詳しくないとなかなか聞かないものまで揃っています。
目次を開くと評価指標が出てくるので、そこから目的の指標を探してください。
アルファベット順に並べています。

インストール・インポート方法

このライブラリはインストールが必要です。

以下のコードで簡単にインストールすることができます。

# evaluateをインストール
pip install evaluate==0.1.0

ついでにインポートもしておきましょう。

# evaluateをインポート
import evaluate

モジュールのタイプ分類

Evaluateは、様々な評価モジュールへアクセスできます。

モデルやデータセットを評価するツールだけでなく、テキスト、コンピュータビジョン、オーディオなど、様々な形式に対応しています。

これらのモジュールは「Metric」「Comparison」「Measurement」の3つのカテゴリに分類されます。（異なるカテゴリに同じ評価指標が含まれる場合もあります。）

それぞれのモジュールにおけるoutputsについては、意味が明らかでない場合のみ説明しています。

基本的には、「モジュールの説明」「inputsの説明」「注意点」で構成されています。

Metric一覧

metricは、モデルの性能を評価するために使われ、通常、モデルの予測値と正解ラベルが含まれます。すべてのMetricはevaluate-metricで見ることができます。

また、metric一覧は次のコードでも見ることができます。

evaluate.list_evaluation_modules(
　# モジュールのタイプをmetricに指定
  module_type="metric",
  # コミュニティモジュールを除く
  include_community=False, 
　# 詳細を表示
  with_details=True)

では、それぞれのmetricの説明と使い方を見ていきます。

Accuracy

accuracyは、処理されたケースの中で正しく予測された割合です。

inputs

references

正解ラベルが入ったリスト

predictions

予測ラベルが入ったリスト

normalize

Falseに設定された場合、正しく分類されたサンプルの数を返す
Trueの場合は、正しく分類されたサンプルの割合を返す
デフォルトはTrue

sample_weight

サンプルの重み付けをリストで与える
デフォルトはNone

利用例

"""case1 シンプルな例"""
# accuracyモジュールの読み込み
accuracy_metric = evaluate.load("accuracy")
# referencesに正解、predictionsに予測を入れてaccuracyを求める
results = accuracy_metric.compute(references=[0, 1], predictions=[0, 1])
print(results)
# {'accuracy': 1.0}

"""case2 normalinzeをFalseにセット"""
accuracy_metric = evaluate.load("accuracy")
# 正しく分類されたサンプルの数を返す
results = accuracy_metric.compute(references=[0, 1, 2, 0, 1, 2], predictions=[0, 1, 1, 2, 1, 0], normalize=False)
print(results)
{'accuracy': 3.0}

"""case3 sample_weightをセット"""
accuracy_metric = evaluate.load("accuracy")
# 分類が間違った時のペナルティの度合いが調整されたaccuracyを返す
results = accuracy_metric.compute(references=[0, 1, 2, 0, 1, 2], predictions=[0, 1, 1, 2, 1, 0], sample_weight=[0.5, 2, 0.7, 0.5, 9, 0.4])
print(results)
{'accuracy': 0.8778625954198473}

Accuracyは、クラスごとのデータ数が偏っている場合、モデルが高頻度のクラスだけを正解だと予測していると高い性能があるように誤解を与える可能性があります。なので、他の指標と組み合わせて実際にモデルがどの程度うまく機能しているかを判断する必要があります。

BERT Score

BERT Scoreは、BERTから事前に学習された文脈埋め込みを活用し、コサイン類似度によって候補文と参照文の単語を照合します。文レベル、システムレベルの評価において、人間の判断と相関があることが示されており、さらに、BERTScoreは、precision、recall、F1を計算し、異なる言語生成タスクの評価に有用です。

# bertscoreモジュールの読み込み
bertscore = evaluate.load("bertscore")

とここで、次のようなエラーが出ました。

ImportError: To be able to use bertscore, you need to install the following dependencies['bert_score'] using 'pip install bert_score' for instance'

bert_scoreをインストールしておく必要があるみたいです。

プロンプトを開いて次のコードを実行しておきましょう。

# bert_scoreをインストール
pip install bert_score

inputs

predictions

候補文の文字列のリスト

references

文字列のリスト、または参照文の文字列のリストのリスト

model_type or lang

model_type：BERT仕様に従って、使用するモデルを指定する文字列

どんなmodel_typeを選択できるかはこちらを参照してください。rinna/japanese-roberta-baseでできないかなと思ったけどそのままでは無理です。改変すればいけそうなので、ローカルでやってみようかな。

lang：文の言語を示す2文字の文字列（日本ならja）

どちらかを設定すればいいです。

デフォルトの設定では、ターゲットの言語の推奨モデルが指定されている場合はそれを使用し、そうでない場合は示されたmodel_typeを使用します。

日本語の場合は、multilingual bertがデフォルトっぽいです。その関係でトークン化があまり丁寧な方法では行っていなさそうです。詳しくはこちらをご覧ください。

以下の引数は設定しなくてもいいです。

num_layers

使用する層の数

model_typeに依存する

verbose

:中間状態の更新をオンにする
デフォルトはFalse

idf

idfの重み付けを使用する
事前に計算されたidf_dictを使用することもできる

device

cudaが利用できるなら設定します。

nthreads

計算に使用するスレッドの数

rescale_with_baseline

BERTScoreを事前に計算されたベースラインで再スケールする
デフォルトはFalse

batch_size

BERTScoreの処理バッチサイズ

baseline_path

カスタマイズされたベースライン・ファイルへのパス

use_fast_tokenizer

hugging faceのトークナイザーに渡されるuse_fastパラメータ。デフォルトはFalse。

利用例

"""case1 シンプルな例"""
# bertscoreモジュールの読み込み
bertscore = evaluate.load("bertscore")
predictions = ["I have an apple"]
references = ["I have a pen"]
# model_typeにdistilbert-base-uncasedを設定
results = bertscore.compute(predictions=predictions, references=references, model_type="distilbert-base-uncased")
# 結果を表示
print(results)
# {'precision': [0.8849452137947083], 'recall': [0.8849452137947083], 
# 'f1': [0.8849452137947083], 'hashcode': 'distilbert-base-uncased_L5_no-idf_version=0.3.11(hug_trans=4.11.0.dev0)'}

"""case2 日本語の例"""
bertscore = evaluate.load("bertscore")
predictions = ["私は猫が好きである"]
references = ["よろしくお願いいたします。"]
# langにjaを設定
results = bertscore.compute(predictions=predictions, references=references, lang="ja")
# 結果を表示
print(results)
# {'precision': [0.6896750926971436], 'recall': [0.68590247631073], 'f1': [0.6877835988998413], 
# 'hashcode': 'bert-base-multilingual-cased_L9_no-idf_version=0.3.11(hug_trans=4.11.0.dev0)'}

モデルを評価するための完璧な評価基準というのは存在しないと思います。だからこそ、いろいろと試行錯誤がなされているので、その試行錯誤を追うのも悪くないと思います。bert scoreについて詳しく知りたい方は、こちらのオリジナルの論文を読んでみてください。
オリジナルの論文では、BERTScoreは、文レベルおよびシステムレベルの評価において人間の判断と良い相関があることを示しましたが、これは選択したモデルおよび言語ペアに依存します。

BLEU

BLEU（Bilingual Evaluation Understudy）とは、ある自然言語から別の自然言語に機械翻訳されたテキストの品質を評価するためのアルゴリズムです。機械翻訳がプロの人間の翻訳に近ければ近いほど優れていることがBLEUの中心的な考え方です。BLEUは、人間が判断する品質と高い相関性を持つことを主張した最初の測定基準の1つであり、現在でも最も人気のある自動化された安価な測定基準の1つです。

inputs

predictions

翻訳された文章を入れたリスト

references

翻訳の正解が入ったリスト

tokenizer

どのように文章を分けるかを決めた関数を渡す感じ

max_order

計算する際に使用するn-gramの最大次数。デフォルトは４

smooth

スムージングを適用するかどうか。デフォルトはFalse

outputs

bleu

bleuのスコア

precisions

n-gram precisions の幾何平均

brevity_penalty

簡易化のペナルティ

length_ratio

長さの比率

translation_length

翻訳文の長さ

reference_length

正解文の長さ

利用例

"""日本語に翻訳した時の例"""
# bleuモジュールの読み込み
bleu = evaluate.load("bleu")
predictions = ["私はこれまでのコメントを削除しました。"]
references = ["私はこれまでのコメントを削除しました。"]
# 適当にtokenizerを探したらこれが見つかったので使ってみる
# transformersはインストールが必要
from transformers import T5Tokenizer
tokenizer = T5Tokenizer.from_pretrained("rinna/japanese-roberta-base")
tokenizer.do_lower_case = True
results = bleu.compute(predictions=predictions, references=references, tokenizer=tokenizer.tokenize)
# 結果を出力
print(results)
# {'bleu': 1.0, 'precisions': [1.0, 1.0, 1.0, 1.0], 'brevity_penalty': 1.0, 
# 'length_ratio': 1.0, 'translation_length': 9, 'reference_length': 9}

BLEUは、異なるデータセット間や、異なる言語間で比較できるものではありません。
また、BLEUは意味を比較するのではなく、予測値と参照値のトークンの重なりを比較しています。このため、BLEUのスコアと人間の評価との間に不一致が生じることがあるので注意しましょう。

BLEURT

BLEURTとは、自然言語生成のための学習された評価指標のことです。詳しくはこちらをご覧ください。

inputs

predictions

生成された文章のリスト

references

比較対象となる文章

checkpoint

BLEURT のチェックポイント
指定しない場合、デフォルトはBLEURT-tiny
他に選択可能なモデルは bleurt-tiny-128、bleurt-tiny-512、bleurt-base-128、bleurt-base-512、bleurt-large-128、bleurt-large-512、BLEURT-20-D3、BLEURT-20-D6、BLEURT-20-D12、BLEURT-20

利用例

"""case1 デフォルトの場合"""
predictions = ["hello there", "general kenobi"]
references = ["hello there", "general kenobi"]
# bleurtモジュールの読み込み
bleurt = evaluate.load("bleurt", module_type="metric")
results = bleurt.compute(predictions=predictions, references=references)
print(results)
# {'scores': [1.0295498371124268, 1.0445425510406494]}

"""case2 model checkpointを指定した場合"""
predictions = ["hello there", "general kenobi"]
references = ["hello there", "general kenobi"]
bleurt = load("bleurt", module_type="metric", checkpoint="bleurt-base-128")
results = bleurt.compute(predictions=predictions, references=references)
print(results)
# {'scores': [1.0295498371124268, 1.0445425510406494]}

　オリジナルのBLEURTの論文は、BLEURTが人間の判断とよく相関することを示しましたが、これは選択されたモデルと言語ペアに依存する点に注意が必要です。
　さらに、現在のところ、BLEURTは英語のコーパスで学習したモデルを利用しているため、英語でのスコアリングしかサポートされていません。また、モデルの学習データに存在する偏りや相関をある程度反映している可能性があります。
　BLEURT指標を計算するには、スコアを計算するために使用されるBLEURTモデルをダウンロードする必要があり、選択されたモデルによってはかなりの時間がかかる可能性があります。

CER

CER（Character error rat）とは、自動音声認識（ASR）システムの性能の一般的な指標です。
CER = (S + D + I) / Nで表されます。
Nは正解文の文字数、Dは削除誤り、Sは置換誤り・Iは挿入誤りの文字数になります。
エラー率のことなので低い方が良いです。

inputs

predictions

認識した文のリスト

references

正解文のリスト

利用例

"""エラー率０"""
# cerモジュール読み込み
cer = evaluate.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

CERは、自動音声認識（ASR）や光学式文字認識（OCR）などのタスクで異なるモデルを比較する際に有用であり、特に、言語の多様性を考えるとWERが適さない多言語データセットに適しています。しかし、CERは翻訳エラーの性質に関する詳細を教えてくれるものではないので注意が必要です。

chrF

ChrFとは、文字n-gramのマッチングにFスコア統計量を使用する機械翻訳の評価指標です。

inputs

predictions

予測されたテキスト

references

参照元のテキスト

char_order

文字のn-gramの順番
デフォルトは6

word_order

単語の n-gram オーダー
2 の場合、chrF++ と呼ばれる
デフォルトは 0

beta

精度に対する想起の重要度を決定する
デフォルトは2

lowercase

True の場合、大文字小文字を区別しない
デフォルトはFalse

whitespace

True の場合、文字 N-gram を抽出する際に空白を含める
デフォルトはFalse

eps_smoothing

Trueの場合、参考のchrF++.py、NLTK、Mosesの実装と同様に、イプシロンスムージングを適用するFalseの場合、sacreBLEU < 2.0.0と同様に、有効なマッチング順序を考慮する
デフォルトはFalse

利用例

"""シンプルな例"""
prediction = ["私のコメントは見えていません。よろしくお願いします。"]
reference = ["私のコメントは見えていません。よろしくお願いいたします。"]
# chrfモジュールを読み込み
chrf = evaluate.load("chrf")
results = chrf.compute(predictions=prediction,
references=reference,
word_order=2,
lowercase=True)
print(results)
# {'score': 71.88024536070621, 'char_order': 6, 'word_order': 2, 'beta': 2}

Popović 2017によると、chrF+（word_order=1）とchrF++（word_order=2）は、chrF（word_order=0）よりも人間の判断と相関のあるスコアを生成するそうです。

Code Eval

Code Evalとは、論文 Evaluating Large Language Models Trained on Codeで紹介された HumanEval 問題解決データセットの評価ハーネスを実装したものです。

inputs

predictions

評価する候補のリスト
各候補は、問題を解決するためのいくつかのコード候補を持つ文字列のリストであるべきである

references

各予測に対するテストを含むリスト
各テストは、コード候補の正しさを評価する必要がある

k

評価で考慮するコード候補の数
デフォルト値は [1, 10, 100]

num_workers

候補プログラムの評価に使用するワーカーの数 (デフォルト値は 4)

timeout

予測が「タイムアウト」とみなされるまでにかかる最大時間
デフォルト値は3.0（3秒）

利用例

"""シンプルな例"""
import os
# 信頼されていないモデル生成コードを実行する可能性があるので、以下の設定には自己責任で十分注意してください
os.environ["HF_ALLOW_CODE_EVAL"] = "1"
code_eval = load("code_eval")
test_cases = ["assert add(2,3)==5"]
candidates = [["def add(a, b): return a+b"]]
pass_at_k, results = code_eval.compute(references=test_cases, predictions=candidates, k=[1])
print(pass_at_k)
# {'pass@1': 1.0}

上記のコードを実行するとエラーが出ました。

# NotImplementedError: This metric is currently not supported on Windows.

Windowsには対応していないみたいです。

このプログラムは、信頼されていないモデル生成コードを実行するので、破壊的な動作をする可能性があります。コードの制限に関する詳細は、Human Eval Githubリポジトリに掲載されています。

COMET

COMET（Crosslingual Optimized Metric for Evaluation of Translation）は、様々なタイプの人間の判断と高い相関を持つ機械翻訳メトリクスを学習するためのオープンソースのフレームワークです。
詳しく知りたい方はCOMET WEBSITEをご覧ください。

inputs

sources

原文のリスト

predictions

訳語候補のリスト

references

参照訳のリスト

gpus

学習に使うGPUの数、または整数のリスト（どのGPUを使用するか）
デフォルトはNone

progress_bar

Trueに設定すると、進捗状況の更新がプリントアウトされる
デフォルト値はFalse

使用例

unbabel-cometをインストールしろと出るので、先にインストールしておきます。

# terminalなどで実行
pip install unbabel-comet

また、私だけかもしれませんが、次のようなエラーが出ました。

# Exception: HOME environment variable is not defined.

探っていくと、以下のところでエラーが発生していました。

if "HOME" in os.environ:
    saving_directory = os.environ["HOME"] + "/.cache/torch/unbabel_comet/"
else:
    raise Exception("HOME environment variable is not defined.")

なので、次のようにos.environ[“HOME”]を設定して解決しています。
もともと設定されていたら大丈夫だと思います。

import os
os.environ["HOME"]="絶対パスを指定する"

では、準備したところで使用例を見ていきます。

"""シンプルな例"""
# cometモジュールを読み込み
comet_metric = evaluate.load('comet') 
source = ["Dem Feuer konnte Einhalt geboten werden", "Schulen und Kindergärten wurden eröffnet."]
predictions = ["They were able to control the fire.", "Schools and kindergartens opened"]
reference = ["They were able to control the fire.", "Schools and kindergartens opened"]
results = comet_metric.compute(predictions=predictions, references=reference, sources=source)
print([round(v, 1) for v in results["scores"]])
[1.0, 1.0]

COMETの指標を計算するには、特徴を得るためのモデルをダウンロードする必要があります。デフォルトのモデルであるwmt20-comet-daは1.79GB以上の記憶容量を必要とし、ダウンロードにはインターネット接続速度によってかなりの時間がかかることが予想されます。この問題がある場合は、より小さいモデルを選択してください。例えば、wmt21-cometinho-daは344MBです。

Competition MATH

Competition MATHは、Mathematics Aptitude Test of Heuristics (MATH)データセットにおける性能を評価するための評価指標です。

inputs

predictions

予測値のリスト
各予測は、自然言語とLaTeXを含む文字列

references

各予測の参照元のリスト
各参照は、自然言語とLaTeXを含む文字列

使用例

"""シンプルな例"""
# competition_mathモジュールの読み込み
math = evaluate.load("competition_math")
references = ["\\frac{1}{2}"]
predictions = ["1/2"]
results = math.compute(references=references, predictions=predictions)
print(results)
# {'accuracy': 1.0}

この指標はMathematics Aptitude Test of Heuristics (MATH) データセットと同じ形式のデータセットに限定されています。

Coval

CoValはCoNLLとARRAUデータセットのための共通の評価指標ツールです。

inputs

keep_singletons

キーやシステムファイルの記述をすべて抽出した後、対応する相互参照列のサイズが1であるものを要素が一つだけのものとして考慮する。デフォルトの評価モードでは、要素が一つのものがキーやシステムファイルに含まれている場合、評価に含まれる。keep_singletons=False に設定すると、キーやシステムファイルに含まれるすべての要素が一つのものが評価から除外される。

NP_only

NP_only オプションを設定することで、スコアラーはNPの解決のみを評価するようになる。

min_span

min_spanを設定することにより、スコアラーは自動的に検出された最小スパンに基づいて結果を報告する。最小スパンはMINAアルゴリズムを用いて決定される。

outputs

muc

0-1 の範囲で、回収率と精度で性能を表す

bcub

0-1の範囲で、分布内の全アイテムの精度を平均したもの

ceafe

参照エンティティとシステムエンティティを、参照エンティティが最大1つの参照エンティティと整列するという制約のもとで整列させて計算される指標である
範囲は0-1

lea

リンクベースのエンティティ考慮指標であり、各エンティティについて、そのエンティティがどれだけ重要で、どれだけ解決されたかを考慮する
範囲は0〜1

conll_score

平均化されたCoNLLスコア（muc、bcub、ceafeのF1値の平均）
0〜100の範囲

利用例

"""例"""
# covalモジュールの読み込み
coval = evaluate.load('coval')
words = ['bc/cctv/00/cctv_0005   0   0       Thank   VBP  (TOP(S(VP*    thank  01   1    Xu_li  *           (V*)        *       -',
... 'bc/cctv/00/cctv_0005   0   1         you   PRP        (NP*)      -    -   -    Xu_li  *        (ARG1*)   (ARG0*)   (116)',
... 'bc/cctv/00/cctv_0005   0   2    everyone    NN        (NP*)      -    -   -    Xu_li  *    (ARGM-DIS*)        *    (116)',
... 'bc/cctv/00/cctv_0005   0   3         for    IN        (PP*       -    -   -    Xu_li  *        (ARG2*         *       -',
... 'bc/cctv/00/cctv_0005   0   4    watching   VBG   (S(VP*))))   watch  01   1    Xu_li  *             *)      (V*)      -',
... 'bc/cctv/00/cctv_0005   0   5           .     .          *))      -    -   -    Xu_li  *             *         *       -']
references = [words]
predictions = [words]
results = coval.compute(predictions=predictions, references=references)
print(results)
# {'mentions/recall': 1.0, 'mentions/precision': 1.0, 'mentions/f1': 1.0, 
# 'muc/recall': 1.0, 'muc/precision': 1.0, 'muc/f1': 1.0, 'bcub/recall': 1.0, 
# 'bcub/precision': 1.0, 'bcub/f1': 1.0, 'ceafe/recall': 1.0, 'ceafe/precision': 1.0, 
# 'ceafe/f1': 1.0, 'lea/recall': 1.0, 'lea/precision': 1.0, 'lea/f1': 1.0, 'conll_score': 100.0}

CoValのこのラッパーは、CoNLL行形式でのみ動作します。これは、1行に1つの単語があり、その単語のすべての注釈がスペースで区切られて列になっている形式です。

CUAD

CUADは、Contract Understanding Atticus Dataset (CUAD)のバージョン1用の公式スコアリングスクリプトを包含しています。Contract Understanding Atticus Dataset (CUAD) v1は、510の商業的な法的契約における13,000以上のラベルのコーパスで、弁護士が企業取引に関連して契約をレビューする際に見る重要な条項の41カテゴリーを識別するために手動でラベル付けされたものです。

inputs

predictions

question-answerの対応を辞書にしたリスト

– id

リファレンスで与えられた質問と答えのペアのID

– prediction_text

答えの候補のリスト
各予測の信頼度に関する閾値に依存した文字列のリストとして使用される

references

question-answerの対応を辞書にしたリスト

– id

質問と回答のペアのID

– answers

CUADデータセット形式の辞書で、以下のkeyを持つ

・text

回答として考えられるテキストのリスト

・answer_start

答えの開始位置のリスト

outputs

exact_match

0.0 から 1.0 の範囲で、参照解答と完全に一致する正規化された解答（詳細）

f1

precisionとrecallの調和平均
範囲は0.0から1.0

aupr

適合率−再現率 曲線の下面積
0.0から1.0までの範囲

prec_at_80_recall

再現率80%で予測された例のうち、真の例の割合
範囲は0.0から1.0

prec_at_90_recall

再現率90%で予測された例のうち、真の例の割合
範囲は0.0から1.0

利用例

"""exact_matchがマックスな例"""
# cuadモジュールの読み込み
cuad_metric = evaluate.load("cuad")
predictions = [{'prediction_text': ['The seller:', 'The buyer/End-User: Shenzhen LOHAS Supply Chain Management Co., Ltd.'], 'id': 'LohaCompanyltd_20191209_F-1_EX-10.16_11917878_EX-10.16_Supply Agreement__Parties'}]
references = [{'answers': {'answer_start': [143, 49], 'text': ['The seller:', 'The buyer/End-User: Shenzhen LOHAS Supply Chain Management Co., Ltd.']}, 'id': 'LohaCompanyltd_20191209_F-1_EX-10.16_11917878_EX-10.16_Supply Agreement__Parties'}]
results = cuad_metric.compute(predictions=predictions, references=references)
print(results)
# {'exact_match': 100.0, 'f1': 100.0, 'aupr': 0.0, 'prec_at_80_recall': 1.0, 'prec_at_90_recall': 1.0}

この指標はCUADデータセットと同じフォーマットを持つデータセットでのみ機能します。
　また、このデータセットのバイアスの限界は議論されていませんが、このデータセットに対するアノテーターの均質性を考えると、アノテーションバイアスを示す可能性があります。

Exact Match

Exact Matchは、regexes_to_ignoreリストの一部として入力された文字列を無視して、入力された予測文字列がその参照に完全に一致する割合を返します。

inputs

predictions

予測されたテキストのリスト

references

参考テキストのリスト

regexes_to_ignore

完全一致を計算する際に無視する文字列を表す正規表現
デフォルトはNone

ignore_case

True の場合、すべてを小文字に変換し、大文字小文字の違いを無視する
デフォルトは False

ignore_punctuation

True の場合、文字列を比較する前に句読点を除去する
デフォルトは False

ignore_numbers

True の場合、文字列を比較する前にすべての数字を削除する
デフォルトはFalse。

利用例

"""case1 無視する正規表現を含めない"""
# exact_matchモジュールの読み込み
exact_match = evaluate.load("exact_match")
refs = ["the cat", "theater", "YELLING", "agent007"]
preds = ["cat?", "theater", "yelling", "agent"]
results = exact_match.compute(references=refs, predictions=preds)
print(round(results["exact_match"], 2))
# 0.25

"""case2 theとyellを無視し、大文字と小文字、句読点も無視する"""
exact_match = evaluate.load("exact_match")
refs = ["the cat", "theater", "YELLING", "agent007"]
preds = ["cat?", "theater", "yelling", "agent"]
results = exact_match.compute(references=refs, predictions=preds, regexes_to_ignore=["the ", "yell"], ignore_case=True, ignore_punctuation=True)
print(round(results["exact_match"], 2))
0.5

この指標は、完全に間違っているものと、一文字だけ正しいものとが同じ点数で出力されるという欠点があります。

F1

F1は、適合率と再現率の調和平均です。
F1 = 2 * (precision * recall) / (precision + recall)で求められます。

inputs

predictions

予測ラベルのリスト

references

正解ラベルのリスト

labels

averageがbinaryでない場合に含めるべきラベルのセット
average が None の場合のラベルの順序．データ中に存在するラベルを除外することができる
デフォルトはNone

pos_label

averageがbinaryに設定されている場合に、正のクラスとみなされるクラス
デフォルトは1

average

Noneに設定された場合、各クラスのスコアを返す
そうでない場合、データに対して実行される平均化のタイプを決定する
デフォルトはbinary

– binary

pos_labelで指定されたクラスについてのみ結果を出力する
これは、予測や参照で見つかったクラスがバイナリである場合にのみ適用される

– micro

真陽性、偽陰性、偽陽性の合計をカウントして、大まかにメトリクスを計算する

– macro

各ラベルについてメトリクスを計算し、それらの非加重平均を求める

– weighted

各ラベルのメトリクスを計算し、各ラベルの真の数で重み付けした平均を求める

– samples

各インスタンスに対してメトリクスを計算し、その平均を求める
マルチラベル分類にのみ意味がある

sample_weight

サンプルの重み付け
デフォルトはNone

利用例

"""case1 シンプルな例"""
# f1モジュールの読み込み
f1_metric = evaluate.load("f1")
results = f1_metric.compute(references=[0, 1, 0, 1, 0], predictions=[0, 0, 1, 1, 0])
print(results)
# {'f1': 0.5}

"""case2 pos_labelを０にセットした例"""
f1_metric = evaluate.load("f1")
results = f1_metric.compute(references=[0, 1, 0, 1, 0], predictions=[0, 0, 1, 1, 0], pos_label=0)
print(round(results['f1'], 2))
# 0.67

F1は、評価指標の中でもかなり有名な部類に入ると思います。
なぜ、調和平均を取るのかを調べてみるとより理解が深まると思うので、ぜひ理由を調べてみてください。

Frugalscore

FrugalScoreは、自然言語生成（NLG）モデル評価のための参照ベースのメトリックです。FrugalScoreは蒸留法に基づいており、高価なNLGメトリックの固定された低コストバージョンを、その本来の性能の大部分を保持しながら学習することができたモデルを用いて評価します。

inputs

predictions

予測をスコアリングするための文字列のリスト

references

各予測の正解を表す文字列のリスト

batch_size

予測のバッチサイズ

max_length

最大配列長

device

gpu or cpuを設定
デフォルトはNone

使用例

"""referencesとpredictionsが一致する場合"""
# frugalscoreモジュールの読み込み
frugalscore = evaluate.load("frugalscore")
results = frugalscore.compute(predictions=['hello world'], references=['hello world'])
print(results)
{'scores': [0.9891097]}

FrugalScoreはBertScoreとMoverScoreをベースにしており、使用されているモデルはこれらのスコアに使用されているオリジナルのモデルをベースにしている点に注意が必要です。

GLUE

GLUE（General Language Understanding Evaluation benchmark）は、自然言語理解システムの学習・評価・解析のためのリソースの集まりです。この指標は、各GLUEデータセットに関連付けられたGLUE評価指標を計算するために使用されます。

モジュールの読み込み時の引数

GLUEはモジュールの読み込み時の引数を設定する必要があります。

もし、設定しないと以下のエラーが出ます。

glue_metric = evaluate.load('glue') # 第二引数を設定していない
# KeyError: 'You should supply a configuration name selected in 
# ["sst2", "mnli", "mnli_mismatched", "mnli_matched", 
# "cola", "stsb", "mrpc", "qqp", "qnli", "rte", "wnli", "hans"]'

ここから選べと言っているので、この中から選んで設定する必要があります。

それぞれの説明はこちらをご覧ください。

inputs

references

各翻訳の参考テキストのリスト

predictions

モデルの予測値のリスト

outputs

f1

適合率と再現率の調和平均

pearson

2つのデータセット間の線形関係を表す尺度
範囲は-1から+1までで、0は相関がないことを意味し、-1/+1は正確な線形関係を意味する

spearmanr

2つのデータセット間の関係の単調性のノンパラメトリック尺度
範囲は-1から+1

matthews_correlation

バイナリおよびマルチクラス分類の品質を評価する尺度

モジュールの読み込み時の引数によって出力が変わります。
cola → matthews_correlation
stsb → pearsonとspearmanr
mrpcとqqp → accuracyとf1
その他の GLUE のサブセット → accuracy

利用例

"""MRPCを選んだ場合"""
# glueモジュールの読み込み
glue_metric = evaluate.load('glue', 'mrpc')
references = [0, 1]
predictions = [0, 1]
results = glue_metric.compute(predictions=predictions, references=references)
print(results)
# {'accuracy': 1.0, 'f1': 1.0}

"""STSBを選んだ場合"""
glue_metric = evaluate.load('glue', 'stsb')
references = [0., 1., 2., 3., 4., 5.]
predictions = [-10., -11., -12., -13., -14., -15.]
results = glue_metric.compute(predictions=predictions, references=references)
print(results)
# {'pearson': -1.0, 'spearmanr': -1.0}

この指標はGLUEデータセットと同じ形式のデータセットでのみ動作します。
GLUEデータセットは「一般的な言語理解」を表すものですが、表現されているタスクは必ずしも言語理解を代表するものではない点に注意が必要です。

Google BLEU

BLEUはコーパスの尺度として設計されているため、単文に用いると好ましくない性質があります。Google BLEUは、このような望ましくない性質を抑制するように設計されています。

inputs

predictions

翻訳された文のリスト

references

各翻訳の正解文のリスト

tokenizer

predictionsとreferencesのトークン化に使用される手法
デフォルトはtokenizer_13a

min_len

n-gramの最小次数
デフォルトは1

max_len

n-gram の最大次数
デフォルトは4

利用例

""" シンプルな例 """
predictions = ['It is a guide to action which ensures that the rubber duck always disobeys the commands of the cat', 'he read the book because he was interested in world history']
references = [['It is the guiding principle which guarantees the rubber duck forces never being under the command of the cat'], ['he was interested in world history because he read the book']]
# google bleuモジュールの読み込み
google_bleu = evaluate.load("google_bleu")
results = google_bleu.compute(predictions=predictions, references=references)
print(results)
# {'google_bleu': 0.4351851851851852}

""" 日本語を突っ込んだ例 (デフォルトのままなので、tokenizer的におかしいかも）"""
predictions = ['コメントありがとうございます。']
references = ["コメントありがとうございます。"]
google_bleu = evaluate.load("google_bleu")
results = google_bleu.compute(predictions=predictions, references=references)
print(results)
# {'google_bleu': 1.0}

GoogleBLEUにはあらかじめ定義されたトークン化関数がありません。以前のバージョンでは、単に split() を使って入力文字列をトークンに分割していました。デフォルトのtokenizer_13aのようなtokenizerを使用することで、結果の標準化と再現性が高まります。

IndicGLUE

IndicGLUEはインド言語の自然言語理解ベンチマークです。アッサム語 (as), ベンガル語 (bn), グジャラート語 (gu), ヒンディー語 (hi), カンナダ語 (kn), マラヤーラム語 (ml), マラーティー語 (mr), オリヤー (or), パンジャービー語 (pa), タミル (ta) およびテルグ語 (te) というインドの主要11言語について様々なタスクが含まれています。この評価指標はIndicGLUEデータセットの評価指標を計算するために使用されます。

日本語でこの指標について調べる人はいないと思うので、利用例だけ載せておきます。

利用例

""" case1 """
indic_glue_metric = evaluate.load('indic_glue', 'wnli') 
references = [0, 1]
predictions = [0, 1]
results = indic_glue_metric.compute(predictions=predictions, references=references)
print(results)
{'accuracy': 1.0}

MAE

平均絶対誤差（MAE）は、予測された数値と実際の数値の差の絶対値の平均値です。

inputs

predictions

(n_samples,) または (n_samples, n_outputs) 形式の数値配列で、推定された目標値

references

(n_samples,) または (n_samples, n_outputs) 形式の数値配列の正しい値

sample_weight

サンプルの重み
(n_samples, )形状の数値配列
デフォルトはNone

multioutput

raw_values、uniform_average、または(n_outputs, )形状の数値配列で、複数の出力値の集計方法を定義する
デフォルトはuniform_average

– raw_values

複数出力の入力の場合，誤差の完全なセットを返す

– uniform_average

すべての出力の誤差を一様な重みで平均化する

利用例

""" シンプルな例 """
# MAEモジュールの読み込み
mae_metric = evaluate.load("mae")
predictions = [2.5, 0.0, 2, 8]
references = [3, -0.5, 2, 7]
results = mae_metric.compute(predictions=predictions, references=references)
print(results)
# {'mae': 0.5}

MAEの限界の1つとして、誤差の相対的な大きさが必ずしも明らかではないことが挙げられます。つまり、大きな誤差と小さな誤差を見分けるのが難しい場合があります。そのため、MAEをパーセントで計算するMean Absolute Percentage Error（MAPE）などが提案されています。
また、MAEは平均値を計算するため、頻度は高くありませんが、大きな誤差の影響を過小評価する可能性があります。RMSE（Root Mean Square Error）などのメトリクスは、誤差の値の根を取ることでこれを補正しています。

Mahalanobis Distance

マハロノビス距離（Mahalanobis Distance）とは、ある点とある分布との距離（2点間の距離とは異なる）であり、ユークリッド距離の多変量版に相当するものです。多変量異常検出、高度にアンバランスなデータセットでの分類、1クラス分類によく用いられます。

inputs

X

reference_distributionと比較したい対象のデータの地点

reference distribution

比較したいreference distributionのデータの地点

利用例

""" シンプルな例 """
# mahalanobisモジュールの読み込み
mahalanobis_metric = evaluate.load("mahalanobis")
results = mahalanobis_metric.compute(reference_distribution=[[0, 1], [1, 0]], X=[[0, 1]])
print(results)
# {'mahalanobis': array([0.5])}

マハラノビス距離は、変数間の線形関係しか捉えることができないため、あらゆる種類の外れ値を捉えることができません。また、マハラノビス距離は、大きく歪んだデータやマルチモーダルなデータを忠実に表現することもできません。

Matthews Correlation Coefficient

マシューズ相関係数（Matthews Correlation Coefficient）は、機械学習において、2クラスおよび多クラス分類の品質を測る尺度として用いられます。これは真陽性と偽陽性を考慮し、クラスが非常に異なるサイズであっても使用できるバランスの取れた指標と一般にみなされています。

inputs

predictions

予測されたクラスラベル

references

正解ラベル

sample_weight

サンプルの重み
デフォルトはNone

利用例

""" シンプルな例 """
# matthews_correlationモジュールの読み込み
matthews_metric = evaluate.load("matthews_correlation")
results = matthews_metric.compute(references=[1, 3, 2, 0, 3, 2], predictions=[1, 2, 2, 0, 3, 3])
print(results)
# {'matthews_correlation': 0.5384615384615384}

マシューズ相関係数は-1から+1までの相関係数の値です。1の係数は完全な予測を表し、0は平均的なランダム予測、-1は逆予測を表します。この統計量は、ファイ係数としても知られています。

MAUVE

MAUVEはPyTorchとHuggingFace Transformersをベースに作られたライブラリで、ニューラルネットワークのテキストと人間のテキストの間のギャップを測定します。詳細は、MAUVE論文をご覧ください。

inputs

predictions

モデルによって生成されたテキスト

references

各予測の参照テキスト

num_buckets

PとQを量子化するヒストグラムのサイズ
デフォルトはauto

pca_max_data

クラスタリングに先立ってPCA次元削減に使用するデータ数
1の場合、すべてのデータを使用する
デフォルトは-1

kmeans_explained_var

PCAによる次元削減のために保持するデータの分散量
デフォルトは0.9

kmeans_num_redo

k-meansクラスタリングをやり直す回数（最適な目的値を保持する）
デフォルトは5

kmeans_max_iter

k-meansの最大イテレーション数
デフォルトは500

featurize_model_name

特徴を取得するモデルの名前
gpt2, gpt2-medium, gpt2-large, gpt2-xl のいずれかから選ぶ
デフォルトは gpt2-large

device_id

GPU を使用する場合は GPU id (例: 0 または 3) を指定する
このIDを持つGPUが見つからない場合、メトリックはCPUを使用する

max_text_length

考慮するトークンの最大数
デフォルトは1024

divergence_curve_discretization_size

発散曲線上で考慮する点の数
デフォルトは25

mauve_scaling_factor

スケーリングのためのハイパーパラメータ
デフォルトは5

verbose

Trueの場合、メトリックを実行すると、実行時間の更新が表示される
デフォルトはTrue

seed

クラスタ割り当てを初期化するためのランダムな値
デフォルトではランダムに割り当てられる

outputs

mauve

0 から 1 の間で、値が大きいほどPとQが近いことを示す

fromtier_integral

0 から 1 の間の値。値が小さいほど、P と Q は近いことを示す

divergence_curve

(m, 2)のnumpy.ndarray; matplotlib でプロットするとダイバージェンスカーブが表示される

p_hist

離散分布で、テキスト分布 p_text を量子化したもの

q_hist

離散分布で、テキスト分布 q_text を量子化したもの

利用例

""" シンプルな例 """
# mauveモジュールの読み込み
mauve = evaluate.load('mauve')
predictions = ["hello world", "goodnight moon"]
references = ["hello world",  "goodnight moon"]
mauve_results = mauve.compute(predictions=predictions, references=references) 
print(mauve_results.mauve)
# 1.0

「To be able to use mauve, you need to install the following dependencies[‘faiss’, ‘mauve’] using ‘pip install # Here to have a nice missing dependency error message early on mauve-text’ for instance’」
上記のエラーが出てpip install mauve-textとしましたが、エラーは解決しませんでした。（私の環境が悪いのかも）そこまで詳しく調べてないので、分かった方はコメントまでお願いします。

Mean IoU

IoU (Intersection over Union) は、予測されたセグメンテーションと正解データの間の重複面積を、予測されたセグメンテーションと正解データの間の結合面積で割ったものです。物体検出で利用されます。バイナリ（2クラス）またはマルチクラスセグメンテーションの場合、各クラスのIoUを取り、それらを平均化することによって計算されます。

inputs

predictions

予測されたセグメンテーションマップのリスト
各マップは (height, width) の形状を持つ

references

正解データのセグメンテーションマップのリスト

num_labels

クラス (カテゴリ) の数

ignore_index

評価時に無視されるインデックス

nan_to_num

指定された場合、NaN 値はユーザが定義した数値に置き換えられる

label_map

指定された場合，古いラベルのインデックスを新しいラベルのインデックスにマッピングする辞書

reduce_labels

通常、背景に0が使われ、背景そのものがデータセットの全クラスに含まれないデータセットに使用される
背景のラベルは255で置き換えられる
デフォルトはFalse

outputs

mean_iou

全カテゴリーで平均化されたIoU

mean_accuracy

平均精度

overall_accuracy

全画像の総合精度

per_category_accuracy

カテゴリごとの精度

per_category_iou

カテゴリごとのIoU

利用例

""" シンプルな例 """
# numpyをインポート
import numpy as np
# mean_iouモジュールの読み込み
mean_iou = evaluate.load("mean_iou")
# suppose one has 3 different segmentation maps predicted
predicted_1 = np.array([[1, 2], [3, 4], [5, 255]])
actual_1 = np.array([[0, 3], [5, 4], [6, 255]])
predicted_2 = np.array([[2, 7], [9, 2], [3, 6]])
actual_2 = np.array([[1, 7], [9, 2], [3, 6]])
predicted_3 = np.array([[2, 2, 3], [8, 2, 4], [3, 255, 2]])
actual_3 = np.array([[1, 2, 2], [8, 2, 1], [3, 255, 1]])
predictions = [predicted_1, predicted_2, predicted_3]
references = [actual_1, actual_2, actual_3]
results = mean_iou.compute(predictions=predictions, references=references, num_labels=10, ignore_index=255, reduce_labels=False)
print(results)
# {'mean_iou': 0.47750000000000004, 'mean_accuracy': 0.5916666666666666, 
# 'overall_accuracy': 0.5263157894736842, 
# 'per_category_iou': array([0.   , 0.   , 0.375, 0.4  , 0.5  , 0.   , 0.5  , 1.   , 1.   , 1.   ]), 
# 'per_category_accuracy': array([0.        , 0.        , 0.75      , 0.66666667, 1.        ,
#        0.        , 0.5       , 1.        , 1.        , 1.        ])}

Mean IoUは平均的な指標であるため、モデルの予測が正解データと異なる部分（すなわち、モデルが苦手とする特定の地域やクラスがある場合）を示すことはできません。

METEOR

METEOR（Metric for Evaluation of Translation with Explicit ORdering）は、機械翻訳の評価指標で、適合率と再現率の調和平均に基づいて計算され、再現率は適合率よりも重視されます。詳しくは、METEOR paperをご覧ください。

inputs

predictions

モデルに翻訳されたテキスト

references

各predictionsの参考文のリスト

alpha

適合率と再現率の相対的な重みを制御するためのパラメータ
デフォルトは0.9

beta

フラグメントの関数としてのペナルティの形状を制御するためのパラメータ
デフォルト値は3

gamma

フラグメントペナルティに割り当てる相対的な重みを指定
デフォルトは 0.5

利用例

""" シンプルな例 """
# meteorモジュールの読み込み
meteor = evaluate.load('meteor')
predictions = ["It is a guide to action which ensures that the military always obeys the commands of the party"]
references = ["It is a guide to action which ensures that the military always obeys the commands of the party"]
results = meteor.compute(predictions=predictions, references=references)
print(round(results['meteor'], 2))
1.0

METEORと人間の判断の相関は中国語とアラビア語で測定され、有意であることがわかったが、他の言語での相関を確認するためにはさらなる実験が必要です。（最新の情報を確認してください）

MSE

平均二乗誤差（MSE）は、誤差の二乗の平均、つまり推定値と実測値の差の平均二乗を表します。

inputs

predictions

(n_samples, ) または (n_samples, n_outputs) 形式の数値配列の推定値

references

(n_samples, )または(n_samples, n_outputs) 形式の数値配列の真の値

sample_weight

サンプルの重みを表す
(n_samples, )形状の数値配列
デフォルトはNone

multioutput

raw_values、uniform_average、または(n_outputs, ) の数値配列
複数の出力値の集計を定義するものである
デフォルトは uniform_average

– raw_values

複数出力の入力の場合，誤差の完全な集合を返す

– uniform_average

すべての出力の誤差が均一な重みで平均化される

squared

True の場合 MSE 値を、False の場合 RMSE (Root Mean Squared Error) を返す
デフォルトはTrue

利用例

""" シンプルな例 """
# mseモジュールの読み込み
mse_metric = evaluate.load("mse")
predictions = [2.5, 0.0, 2, 8]
references = [3, -0.5, 2, 7]
results = mse_metric.compute(predictions=predictions, references=references)
print(results)
# {'mse': 0.375}

MSEは外れ値に大きな重み付けをする欠点があります。二乗するので、大きな誤差は小さな誤差よりも大きな重み付けをすることになります。

Pearson Correlation Coefficient

ピアソン相関係数（Pearson Correlation Coefficient）は、2つのデータセット間の線形関係を測定します。他の相関係数と同様、この係数は-1から+1の間で変化し、0は相関がないことを意味します。また、相関が-1または+1であれば、正確な線形関係を意味します。

inputs

predictions

モデルによって返される予測されたクラスラベル

references

正解ラベル

return_pvalue

True の場合、相関係数とともに p-Value を返す
False の場合、相関係数のみを返す
デフォルトは False

outputs

pearsonr

ピアソンの相関係数

p-value

p-valueは、相関のない系統のデータセットが、これらのデータセットから計算されたピアソン相関と少なくとも同じ極端な相関を持つデータセットを生成する確率をおおまかに示すもの
最小値は0、最大値は1で、値が大きいほど確率が高いことを示す

利用例

""" シンプルな例 """
# pearsonrモジュールの読み込み
pearsonr_metric = evaluate.load("pearsonr")
results = pearsonr_metric.compute(predictions=[10, 9, 2.5, 6, 4], references=[1, 2, 3, 4, 5], return_pvalue=True)
print(sorted(list(results.keys())))
['p-value', 'pearsonr']
print(round(results['pearsonr'], 2))
-0.74
print(round(results['p-value'], 2))
0.15

p値の計算は、各データセットが正規分布しているという仮定に依存しています。これは常にそうであるとは限らないので、データセットの真の分布を検証することが推奨されます。

Perplexity

Perplexityは、モデルが与えられた入力テキスト列を生成する可能性がどの程度あるかを測定します。指標としては、モデルが学習したテキストの分布をどの程度学習したかを評価するために用いることができます。この場合、モデルの入力は評価対象の学習済みモデルであり、入力テキストはモデルが学習したテキストであるべきです。

inputs

model_id

Perplexityを計算するために使用するモデル
Perplexityは因果関係のある言語モデルに対してのみ計算できる
計算できるモデルのリストはこちらのドキュメントを参照

input_texts

入力テキスト

batch_size

モデルを通してテキストを実行するバッチサイズ
デフォルトは16

add_start_token

テキストに開始トークンを追加し、最初の単語の確率を含む複雑さを計算するかどうか
デフォルトはTrue

device

実行するデバイス
デフォルトはcuda

利用例

""" シンプルな例 """
# perplexityモジュールの読み込み
perplexity = evaluate.load("perplexity", module_type="metric")
input_texts = ["lorem ipsum", "Happy Birthday!", "Bienvenue"]
results = perplexity.compute(model_id='gpt2',
                             add_start_token=False,
                             input_texts=input_texts)
print(list(results.keys()))
['perplexities', 'mean_perplexity']
print(round(results["mean_perplexity"], 2))
78.22
print(round(results["perplexities"][0], 2))
11.11

出力値はモデルがどのようなテキストで学習したかに大きく依存することに注意してください。つまり、モデルやデータセット間でperplexityスコアは比較できません。

Precision

適合率（Precision）とは、正とラベル付けされたすべての例のうち、正しく正とラベル付けされた例の割合です。

inputs

predictions

予測されたクラスラベル

references

実際のクラスラベル

labels

averageがbinaryに設定されていない場合に含めるべきラベルセット
average：Noneの場合、ラベルの順番となる
データ中に存在するラベルを除外することができる
例えば、多数派のネガティブクラスを無視してマルチクラス平均を計算することができる
データ中に存在しないラベルは、マクロ平均では0成分になる
マルチラベル・ターゲットでは、ラベルは列インデックスである
デフォルトでは、予測および参照におけるすべてのラベルは、ソートされた順序で使用される
デフォルトはNone

pos_label

averageがbinary に設定されている場合に、正のクラスとみなされるクラス
デフォルトは1

average

このパラメータは、マルチクラス/マルチラベルのターゲットに必要である
Noneに設定された場合、各クラスのスコアが返される
そうでない場合、データに対して実行される平均化のタイプを決定する
デフォルトはbinary

– binary

pos_labelで指定されたクラスの結果のみを返す

– micro

真陽性、偽陰性、偽陽性の合計をカウントして、全体的にメトリクスを計算する

– macro

各ラベルのメトリクスを計算し、それらの非加重平均を求める
これは、ラベルの不均衡を考慮に入れていない

– weighted

各ラベルのメトリクスを計算し、各ラベルの真のインスタンスの数で重み付けした平均値を求める

– samples

各インスタンスのメトリクスを計算し、その平均を求める
マルチラベル分類にのみ意味がある

sample_weight

サンプルの重み付け
デフォルトはNone

zero_division()

ゼロ除算があったときに返す値を設定する
デフォルトは
0: ゼロ除算があった場合、0を返す
1: ゼロ除算があった場合、1を返す
warn: 警告を発生させ、ゼロ除算の場合は0を返す

利用例

""" シンプルな例 """
# precisionモジュールの読み込み
precision_metric = evaluate.load("precision")
results = precision_metric.compute(references=[0, 1, 0, 1, 0], predictions=[0, 0, 1, 1, 0], pos_label=0)
print(round(results['precision'], 2))
# 0.67

適合度と再現率は補完的であり、モデルの性能の異なる側面を測定するために使用することができます。

Recall

再現率（Recall）は、モデルによって正とラベル付けされた中の正例の割合です。

inputs

predictions

予測されたクラスラベル

references

実際のクラスラベル

labels

averageがbinaryに設定されていない場合に含めるべきラベルセット
average：Noneの場合、ラベルの順番となる
データ中に存在するラベルを除外することができる
例えば、多数派のネガティブクラスを無視してマルチクラス平均を計算することができる
データ中に存在しないラベルは、マクロ平均では0成分になる
マルチラベル・ターゲットでは、ラベルは列インデックスである
デフォルトでは、予測および参照におけるすべてのラベルは、ソートされた順序で使用される
デフォルトはNone

pos_label

再現率を計算する際に「正のクラス」として使用するクラスラベル
デフォルトは1

average

このパラメータは、マルチクラス/マルチラベルのターゲットに必要である
Noneに設定された場合、各クラスのスコアが返される
そうでない場合、データに対して実行される平均化のタイプを決定する
デフォルトはbinary

– binary

pos_labelで指定されたクラスの結果のみを返す

– micro

真陽性、偽陰性、偽陽性の合計をカウントして、全体的にメトリクスを計算する

– macro

各ラベルのメトリクスを計算し、それらの非加重平均を求める
これは、ラベルの不均衡を考慮に入れていない

– weighted

各ラベルのメトリクスを計算し、各ラベルの真のインスタンスの数で重み付けした平均値を求める

– samples

各インスタンスのメトリクスを計算し、その平均を求める
マルチラベル分類にのみ意味がある

sample_weight

サンプルの重み付け
デフォルトはNone

zero_division()

ゼロ除算があったときに返す値を設定する
デフォルトは
warn:ゼロ除算があった場合、返り値は0であるが、警告も発生する
0: ゼロ除算があった場合、0を返す
1: ゼロ除算があった場合、1を返す

利用例

""" シンプルな例 """
# recallモジュールの読み込み
recall_metric = evaluate.load('recall')
results = recall_metric.compute(references=[0, 0, 1, 1, 1], predictions=[0, 1, 0, 1, 1])
print(results)
{'recall': 0.6666666666666666}

適合度と再現率は補完的であり、モデルの性能の異なる側面を測定するために使用することができます。

RL Reliability

RL Reliability Metricsは、強化学習（RL）アルゴリズムの信頼性を測定するためのメトリクスを提供するライブラリです。評価には「オンライン」と「オフライン」の構成があります。

inputs

timesteps

実行ごとのタイムステップのリスト/配列

rewards

実行ごとの報酬のリスト/配列

baseline

default “が渡された場合、曲線は、オンライン設定ではその範囲によって、オフラインでは実行全体の性能の中央値によって正規化される
浮動小数点が渡された場合、曲線はその値で割られる

eval_points

[50000, 150000, …, 2000000]のポイントで統計が計算される

freq_tresh

ローパスフィルタリングのための周波数閾値
デフォルトは0.01

window_size

各評価点を中心としたウィンドウを定義する
デフォルトは100000

window_size_trimmed

差分処理により短くなったカーブを処理する
デフォルトは99000

alpha

“value at risk” (VaR)のカットオフポイント
デフォルトは0.05

利用例

あまり容量を圧迫したくないので、ダウンロードして試していません。

# ファイルをダウンロード
wget https://storage.googleapis.com/rl-reliability-metrics/data/tf_agents_example_csv_dataset.tgz
tar -xvzf tf_agents_example_csv_dataset.tgz

# サンプルデータをロード
dfs = [pd.read_csv(f"./csv_data/sac_humanoid_{i}_train.csv") for i in range(1, 4)]
# rl_reliabilityモジュールの読み込み
rl_reliability = evaluate.load("rl_reliability", "online")
rl_reliability.compute(timesteps=[df["Metrics/EnvironmentSteps"] for df in dfs],
                       rewards=[df["Metrics/AverageReturn"] for df in dfs])

このRL reliabilityの実装では、アルゴリズムがメトリクスの値で統計的に異なるかどうかを判断するため検定を計算せず、またアルゴリズムの順位に関するブートストラップ信頼区間も計算していません。
また、出力の概要については、こちらのOutput Valuesをご覧ください。

ROC AUC

roc aucは、ROC（Receiver Operating Characteristic Curve）の曲線下面積（AUC）を計算します。戻り値は、使用したモデルが入力データに基づいて、正しいクラスをどれだけ良く予測しているかを表しています。

inputs

references

(n_samples, ) または (n_samples, n_classes) の配列で正解のラベル
ユースケースに応じて異なる入力が期待される

– binary

(n_samples,) の配列の場合に設定することが望ましい

– multiclass

(n_samples,) の配列の場合に設定することが望ましい

– multilabel

(n_samples, n_classes) の配列の場合に設定することが望ましい

prediction_scores

(n_samples, ) または (n_samples, n_classes)の配列でモデルの予測値
ユースケースに応じて異なる入力が期待される

– binary

(n_samples, ) の配列の場合に設定することが望ましい

– multiclass

(n_samples, n_classes)の配列の場合に設定することが望ましい
確率の推定値は、クラス全体で合計が1でなければならない

– multilabel

(n_samples, n_classes) の配列の場合に設定することが望ましい

average

ユースケースでbinaryが選択されている場合は無視される
デフォルトはmacro

– micro

ラベル指標行列の各要素をラベルとして考慮し、全体的にメトリクスを計算する
multilabelのユースケースでのみ機能する

– macro

各ラベルのメトリクスを計算し、それらの非加重平均を求める
これはラベルのアンバランスを考慮しない

– weighted

各ラベルのメトリクスを計算し、各ラベルの真のインスタンスの数で重み付けした平均を求める

– samples

各インスタンスのメトリクスを計算し、その平均を求める
multilabelのユースケースでのみ機能する

– None

平均は計算されず、各クラスのスコアが返される
マmultilabelのユースケースでのみ機能する

sample_weight

サンプルの重み付け
デフォルトはNone

max_fpr

None でない場合、範囲 [0, max_fpr] にわたって標準化された部分 AUC が返される
デフォルトは None

multi_class

multiclassのtargetsにのみ使用され、その場合は必須である
使用する構成の種類を決定する

– ovr

One-vs-restの略
各クラスの残りのクラスに対するAUCを計算する

– ovo

One-vs-oneの略
クラスのすべての可能な組み合わせの平均AUCを計算する

labels

multiclassのtargetsにのみ使用される
predict_scoresのクラスをインデックスするラベルのリスト
Noneの場合、prediction_scoreのラベルの数値順または辞書順が使用される
デフォルトはNone

利用例

""" シンプルな例 """
# roc_aucモジュールの読み込み
roc_auc_score = evaluate.load("roc_auc")
refs = [1, 0, 1, 1, 0, 0]
pred_scores = [0.5, 0.2, 0.99, 0.3, 0.1, 0.7]
results = roc_auc_score.compute(references=refs, prediction_scores=pred_scores)
print(round(results['roc_auc'], 2))
# 0.78

multi_classにovrを設定してAUCを計算する場合、ユースケースがmulticlassの時もmultilabelの時と同じように扱います。これは、averageがmacroの場合でもクラスの不均衡に敏感で、restグループの構成に影響を与えるからです。

ROUGE

ROUGE（Recall-Oriented Understudy for Gisting Evaluation）は、自然言語処理における自動要約や機械翻訳ソフトの評価に用いられる評価指標とソフトウェアパッケージのセットです。この評価基準は、機械的に作成された要約や翻訳を人間が作成した要約や翻訳と比較するものです。

inputs

predictions

機械的に作成された要約や翻訳文
トークンをスペースで区切った文字列でなければならない

references

人間が作成した要約や翻訳
スペースで区切られたトークンの文字列でなければならない

rouge_types

詳しくはこちらを見るか、「rouge_typeとは」と調べて見てください
デフォルトはすべて計算する

– rouge1

1-gramベースのスコアリング

– rouge2

bigram (2-gram)に基づくスコアリング

– rougeL

Longest common subsequenceに基づくスコアリング

– rougeLSum

“\n” を使ってテキストを分割する

use_aggregator

Trueの場合、集計値を返す
デフォルトはTrue

use_stemmer

True の場合、Porter Stemmer を使って単語の接尾辞を除去する
デフォルトは False

利用例

rouge_scoreをインストールする必要があります。

# rouge_scoreをインストール
pip install rouge_score

""" シンプルな例 """
# rougeモジュールの読み込み
rouge = evaluate.load('rouge')
predictions = ["hello goodbye", "ankh morpork"]
references = ["goodbye", "general kenobi"]
results = rouge.compute(predictions=predictions,references=references,use_aggregator=False)
print(list(results.keys()))
# ['rouge1', 'rouge2', 'rougeL', 'rougeLsum']
print(results["rouge1"])
# [0.6666666666666666, 0.0]

ROUGE の多くの制限に関する詳細な議論については、Schluter (2017) を参照してください。

SacreBLEU

SacreBLEUは、オリジナルの実装(Papineni et al., 2002)を他の有用な機能とともにラッピングすることで、これらの問題を解決することを目指しています。
詳しくはGithubをご覧ください。

inputs

predictions

翻訳文のリスト

references

参考文のリスト

smooth_method

使用する平滑化方法
デフォルトはexp
使用可能な値は以下の通り

– none

平滑化しない

– floor

ゼロカウントを増加させる

– add_k

num/denom を k ずつ増加させる

– exp

指数的減衰を行う

smooth_value

平滑化の値
smooth_methodがfloorの場合 smooth_value のデフォルトは 0.1
smooth_methodがadd-kの場合 smooth_value のデフォルトは 1

tokenize

BLEUに使用するトークン化手法

– none

トークン化なし

– zh

中国語のトークン化

– 13a

Mosesのmteval-v13a

– intl

Mosesのmteval-v14

– char

言語にとらわれない文字レベルのトークン化

– ja-mecab

日本語のトークン化

lowercase

True の場合、入力を小文字にし、大文字小文字を区別しないようにする
デフォルトはFalse

force

True の場合、トークン化された入力が実際にトークン化解除されるかどうかを保証する
デフォルトはFalse

use_effective_order

文レベルのBLEUを計算する場合は、Trueにする必要がある
デフォルトはFalse

outputs

score

BLEUスコア

counts

カウント数

totals

合計

precisions

適合率

bp

簡略化ペナルティ

sys_len

予測文の長さ

ref_len

参照文の長さ

利用例

""" 日本語での例 """
predictions = ["今日は、仕事をしてそのまま寝ました。"]
references = ["今日は、タスクをしてそのまま寝ました。"]
# sacrebleuモジュールの読み込み
sacrebleu = evaluate.load("sacrebleu")
results = sacrebleu.compute(predictions=predictions, 
                            references=references, tokenize="ja-mecab")
print(list(results.keys()))
# ['score', 'counts', 'totals', 'precisions', 'bp', 'sys_len', 'ref_len']
print(results)
# {'score': 73.48889200874659, 'counts': [11, 9, 7, 5], 
# 'totals': [12, 11, 10, 9], 'precisions': [91.66666666666667, 81.81818181818181, 70.0, 55.55555555555556], 
# 'bp': 1.0, 'sys_len': 12, 'ref_len': 12}

この指標で計算されるのはBLEUスコアなので、sacreBLEUの方が再現性が高いことを除けば、BLUE指標と同じ制約がある点には注意が必要です。

SARI

SARI (system output against references and against the input sentence) は、自動テキスト簡略化システムを評価するために用いられる指標です。この指標は、予測し簡略化された文章を参照文と原文で比較します。また、システムによって追加、削除、保持された単語の良し悪しを明示的に測定します。

inputs

souces

ソース文の文字列のリスト

predictions

予測文の文字列のリスト

references

参照文の文字列のリスト

利用例

""" シンプルな例 """
# sariモジュールの読み込み
sari = evaluate.load("sari")
sources=["About 95 species are currently accepted."]
predictions=["About 95 you now get in."]
references=[["About 95 species are currently known.","About 95 species are now accepted.","95 species are now accepted."]]
sari_score = sari.compute(sources=sources, predictions=predictions, references=references)
print(sari_score)
# {'sari': 26.953601953601954}

SARIは、異なるテキスト簡略化システムを比較するための貴重な尺度であると同時に、システムの反復的な開発を支援するものでもある。しかし、SARIを発表した元の論文では、「文法性と意味の保存の概念」を捉えているとされていますが、これは実証的に検証することが難しい主張です。

seqeval

seqevalは、系列ラベリング(固有表現抽出)の評価用Pythonフレームワークです。名前付き実体の認識、品詞タグ付け、意味役割ラベル付けなどのチャンキングタスクの性能を評価することができます。

inputs

predictions

予測されたラベルのリスト

references

参照ラベルのリスト

suffix

IOBタグを後につける場合であればTrue、前につける場合はFalse
デフォルトはFalse

scheme

対象のタグ付けスキーム
[IOB1, IOB2, IOE1, IOE2, IOBES, BILOU] のいずれかを指定する
デフォルトはNone

mode

間違ったI/Bタグを持つ正しい実体ラベルを真陽性としてカウントするかどうかを指定する
完全一致のみをカウントしたい場合は、mode=”strict “と特定のscheme値を渡す
デフォルトはNone

sample_weight

各サンプルの重み
デフォルトはNone

zero_division

ゼロ除算の場合に、どの値をメトリック値として代用するか
[ 0, 1, “warn”]のいずれかでなければならない
warnは0として動作するが、警告を出す

outputs

overall_accuracy

0.0から1.0の間のスケールの平均精度

overall_precision

0.0から1.0の間のスケールの平均適合率

overall_recall

0.0から1.0の間のスケールの平均再現性

overall_f1

0.0から1.0の間のスケールのF1スコアの平均値

precision

タグごとの0.0から1.0の間のスケールの平均適合率

recall

タグごとの0.0から1.0の間のスケールの平均再現性

f1

タグごとの0.0から1.0の間のスケールのF1スコアの平均値

利用例

""" シンプルな例 """
# seqevalモジュールの読み込み
seqeval = evaluate.load('seqeval')
predictions = [['O', 'O', 'B-MISC', 'I-MISC', 'I-MISC', 'I-MISC', 'O'], ['B-PER', 'I-PER', 'O']]
references = [['O', 'O', 'B-MISC', 'I-MISC', 'I-MISC', 'I-MISC', 'O'], ['B-PER', 'I-PER', 'O']]
results = seqeval.compute(predictions=predictions, references=references)
print(results)
# {'MISC': {'precision': 1.0, 'recall': 1.0, 'f1': 1.0, 'number': 1}, 
# 'PER': {'precision': 1.0, 'recall': 1.0, 'f1': 1.0, 'number': 1}, 
# 'overall_precision': 1.0, 'overall_recall': 1.0, 'overall_f1': 1.0, 'overall_accuracy': 1.0}

IOBフォーマットについての詳細は、Wikipedia pageとCoNLL-2000 shared taskを参照してください。

Spearman Correlation Coefficient Metric

スピアマンの順位相関係数（Spearman Correlation Coefficient Metric）は、2つのデータセット間の関係を表す尺度です。他の相関係数と同様、-1 から +1 の間で変化し、0 は相関がないことを意味します。正の相関は、データセットxのデータが増加すると、データセットyのデータも増加することを意味し、負の相関は、xが増加するとyが減少することを意味します。相関が-1または+1であれば、厳密な単調関係を意味します。

inputs

predictions

モデルによって返されるラベルの予測値

references

真のラベル

return_pvalue

True の場合、p-value を返す
False の場合、spearmanr スコアのみが返される
デフォルトはFalse

利用例

""" シンプルな例 """
# spearmanrモジュールの読み込み
spearmanr_metric = evaluate.load("spearmanr")
results = spearmanr_metric.compute(references=[1, 2, 3, 4, 5], predictions=[10, 9, 2.5, 6, 4], return_pvalue=True)
print(results)
# {'spearmanr': -0.7, 'spearmanr_pvalue': 0.1881204043741873}

SQuAD

SQuADは読解問題のデータセットで、Wikipediaの記事に対してクラウドワーカーが出した質問から構成されています。すべての質問に対する答えは、対応する読解箇所のテキストのセグメント、またはスパンであり、質問は答えられない場合があります。このメトリクスは、そのStanford Question Answering Dataset (SQuAD) のバージョン1用の公式採点スクリプトを内包しています。

inputs

predictions

モデルの予測文

references

比較する文

outputs

extra_match

範囲は0-100
0.0は答えが一致しなかったことを意味し、100.0はすべての答えが一致したことを意味する

f1

範囲は0-1
最小値は0、つまり適合率と再現率のどちらかが0であることを意味する
最大値は1.0、つまり適合率と再現率が完璧であることを意味する

利用例

""" シンプルな例 """
# squadモジュールの読み込み
squad_metric = evaluate.load("squad")
predictions = [{'prediction_text': '1976', 'id': '56e10a3be3433e1400422b22'}]
references = [{'answers': {'answer_start': [97], 'text': ['1976']}, 'id': '56e10a3be3433e1400422b22'}]
results = squad_metric.compute(predictions=predictions, references=references)
print(results)
# {'exact_match': 100.0, 'f1': 100.0}

この指標は、SQuAD v.1データセットと同じ形式のデータセットでのみ機能します。

SQuAD v2

このメトリクス（SQuAD v2）は、Stanford Question Answering Dataset (SQuAD) のバージョン2の公式採点スクリプトをラップしています。

inputs

predictions

以下のKey-Valueペアでスコア付けするquestion-answerの三項リスト

– id

question-answerのペアを識別するid

– prediction_text

予測されたテキスト

– no_answer_probability

質問に対して答えがない確率

references

以下のKey-Valueペアを持つquestion-answers辞書のリスト

– id

question-answerのペアのID

– answers

文字列としての答えのテキスト

no_amswer_threshold

質問に対して答えがないと判断するための確率の閾値

outputs

exact

正規化された回答が完全に一致する

f1

予測されたトークンと正解の平均 F1 スコア

total

考慮したスコアの数

HasAns_exact

正規化された回答が完全に一致する

HasAns_f1

予測されたトークンと正解の平均 F1 スコア

HasAns_total

質問のうちいくつの答えがあるのか

NoAns_exact

正規化された回答が完全に一致する

NoAns_f1

予測されたトークンと正解の平均 F1 スコア

NoAns_total

質問のうち答えがないものの数

best_exact

閾値を変化させた完全一致のベストスコア

best_exact_thresh

完全一致に伴う無回答の確率の閾値

best_f1

閾値を変化させた場合の最適なF1スコア

best_f1_thresh

最適なF1スコアに関係する無回答確率の閾値

利用例

""" シンプルな例 """
# squad_v2モジュールの読み込み
squad_v2_metric = evaluate.load("squad_v2")
predictions = [{'prediction_text': '1976', 'id': '56e10a3be3433e1400422b22', 'no_answer_probability': 0.}]
references = [{'answers': {'answer_start': [97], 'text': ['1976']}, 'id': '56e10a3be3433e1400422b22'}]
results = squad_v2_metric.compute(predictions=predictions, references=references)
print(results)
# {'exact': 100.0, 'f1': 100.0, 'total': 1, 'HasAns_exact': 100.0, 
# 'HasAns_f1': 100.0, 'HasAns_total': 1, 'best_exact': 100.0, 'best_exact_thresh': 0.0, 
'best_f1': 100.0, 'best_f1_thresh': 0.0}

このメトリックは、SQuAD v.2データセットと同じ形式のデータセットでのみ機能します。

SuperGLUE

SuperGLUEは、GLUEの後継として、より難しい言語理解タスクのセットを追加・リソースを改善し、新しいパブリックリーダーボードを備えた新しいベンチマークです。

モジュールの読み込み時の引数

super_glue_metric = evaluate.load('super_glue')
# KeyError: 'You should supply a configuration name selected in
# ["boolq", "cb", "copa", "multirc", "record", "rte", "wic", "wsc", "wsc.fixed", "axb", "axg",]'

第二引数を設定しないとエラーが出ます。

[“boolq”, “cb”, “copa”, “multirc”, “record”, “rte”, “wic”, “wsc”, “wsc.fixed”, “axb”, “axg”,]←ここから選ぶ必要があります。

 詳しくは、SuperGLUE dataset pageまたはofficial dataset websiteを参照して下さい。

inputs

predictions

予測

モジュールの読み込み時の第二引数がrecodeの場合

以下のキーを持つQuestion-Answerの辞書のリスト

– idx

データセットで指定された質問のインデックス

– prediction_text

答えの予測文

モジュールの読み込み時の第二引数がmultircの場合

question-answerの辞書のリストで、キーは以下の通り

– idx

データセットで指定されたquestion-answerのペアのインデックス

– prediction

予測された答えのラベル

モジュールの読み込み時の第二引数が上記以外の場合

予測されたラベルのリスト

references

質問-回答辞書のリストで、キーは以下の通り

モジュールの読み込み時の第二引数がrecodeの場合

– idx

データセットで指定された質問のインデックス

– answers

可能性のある答えのリスト

モジュールの読み込み時の第二引数がrecode以外の場合

参照ラベルのリスト

outputs

exact_match

予測文字列の完全一致スコア
詳細はこちら

f1

適合率と再現率の調和平均

matthews_correlation

バイナリおよびマルチクラス分類の品質を示す指標
詳細はこちら

利用例

""" ["copa", "rte", "wic", "wsc", "wsc.fixed", "boolq", "axg"]から選んだ場合 """
# super_glueモジュールの読み込み
super_glue_metric = evaluate.load('super_glue', 'copa')
predictions = [0, 1]
references = [0, 1]
results = super_glue_metric.compute(predictions=predictions, references=references)
print(results)
# {'accuracy': 1.0}

""" 'multirc'の場合 """
super_glue_metric = evaluate.load('super_glue', 'multirc')
predictions = [{'idx': {'answer': 0, 'paragraph': 0, 'question': 0}, 'prediction': 0}, 
{'idx': {'answer': 1, 'paragraph': 2, 'question': 3}, 'prediction': 1}]
references = [1,0]
results = super_glue_metric.compute(predictions=predictions, references=references)
print(results)
# {'exact_match': 0.0, 'f1_m': 0.0, 'f1_a': 0.0}

""" 'axb'の場合 """
super_glue_metric = evaluate.load('super_glue', 'axb')
references = [0, 1]
predictions = [1, 1]
results = super_glue_metric.compute(predictions=predictions, references=references)
print(results)
# {'matthews_correlation': 0.0}

この指標は、SuperGLUEデータセットと同じフォーマットのデータセットでのみ機能します。

TER

Translation Error Rateは、機械翻訳のエラー指標であり、システムの出力を基準に変更するために必要な編集回数を測定します。

inputs

predictions

予測された訳語

references

一つ以上の基準語訳

normalized

True の場合、基本的なトークン化および正規化を文に適用する
デフォルトは False

ignore_punct

こちらのinputsの説明文では、normalizedと同じ説明になっていますが、引数名的には次の意味だと思います。変わっていたらコメントで教えてください。

True の場合、句読点を無視する
デフォルトは False

support_zh_ja_chars

True の場合、トークン化/正規化は、漢字、ひらがな、カタカナ、およびカタカナの音韻拡張と同様に、中国語の文字の処理をサポートする
normalized = True の場合のみ適用される
デフォルトはFalse

case_sensitive

Falseの場合、大文字と小文字の違いを無視するために、すべての予測および参照を小文字にする
デフォルトはFalse

outputs

score

TER スコア (num_edits / sum_ref_lengths * 100)

num_edits

編集回数の累計

ref_length

累積平均基準語訳の長

利用例

""" シンプルな例 """
# terモジュールの読み込み
ter = evaluate.load("ter")
predictions = ["does this sentence match??","what about this sentence?"]
references = [["does this sentence match", "does this sentence match!?!"],["wHaT aBoUt ThIs SeNtEnCe?", "wHaT aBoUt ThIs SeNtEnCe?"]]
results = ter.compute(predictions=predictions, references=references,case_sensitive=True)
print(results)
# {'score': 62.5, 'num_edits': 5, 'ref_length': 8.0}

TREC Eval

TREC Evalは、情報検索の指標である適合率やnormalized Discounted Cumulative Gain（nDCG）などを組み合わせた指標です。これは、検索された文書のランキングを基準値でスコアリングするために使用されます。

このモジュールは、trectoolsをインストールしておく必要があります。
以下のコマンドを入力してください。

pip install trectools

inputs

predictions

一回の検索run

– query

クエリ ID

– q0

リテラル”q0″

– docid

ドキュメント ID

– rank

ドキュメント rank

– score

ドキュメント score

– system

現在のrunのタグ

references

一回のqrel

query

クエリ ID

q0

リテラル “q0”

docid

ドキュメント ID

rel

文書の関連性

outputs

runid

run ID

num_ret

検索された文書数

num_rel

該当文書の数

num_rel_ret

検索された該当文書の数

num_q

クエリの数

map

平均適合率の平均値

gm_map

平均適合率の幾何学的平均

bpref

バイナリ優先度スコア

Rprec

適合率@R
Rは該当文書数

recip_rank

相互ランク

P@k

precision@k (k in [5, 10, 15, 20, 30, 100, 200, 500, 1000]

NDCG@k

nDCG@k (k in [5, 10, 15, 20, 30, 100, 200, 500, 1000]

利用例

""" シンプルな例 """
qrel = {
    "query": [0],
    "q0": ["q0"],
    "docid": ["doc_1"],
    "rel": [2]
}
run = {
    "query": [0, 0],
    "q0": ["q0", "q0"],
    "docid": ["doc_2", "doc_1"],
    "rank": [0, 1],
    "score": [1.5, 1.2],
    "system": ["test", "test"]
}
# trec_evalモジュールの読み込み
trec_eval = evaluate.load("trec_eval")
results = trec_eval.compute(references=[qrel], predictions=[run])
print(results)
# {'runid': 'test', 'num_ret': 2, 'num_rel': 1, 'num_rel_ret': 1, 
# 'num_q': 1, 'map': 0.5, 'gm_map': 0.5, 'bpref': 0.0, 'Rprec': 0.0, 
# 'recip_rank': 0.5, 'P@5': 0.2, 'P@10': 0.1, 'P@15': 0.06666666666666667, 
# 'P@20': 0.05, 'P@30': 0.03333333333333333, 'P@100': 0.01, 'P@200': 0.005, 
# 'P@500': 0.002, 'P@1000': 0.001, 'NDCG@5': 0.6309297535714575,
# 'NDCG@10': 0.6309297535714575, 'NDCG@15': 0.6309297535714575, 
# 'NDCG@20': 0.6309297535714575, 'NDCG@30': 0.6309297535714575, 'NDCG@100': 0.6309297535714575, 
# 'NDCG@200': 0.6309297535714575, 'NDCG@500': 0.6309297535714575, 'NDCG@1000': 0.6309297535714575}

より実際のケースに沿った例はtrectoolsをご覧ください。

WER

Word error rate（WER）は、自動音声認識（ASR）システムの性能の一般的な指標です。

このモジュールは、jiwerをインストールしておく必要があります。

pip install jiwer

inputs

predictions

認識音声の文字列のリスト

references

各音声入力の基準のリスト

利用例

""" シンプルな例 """
# werモジュールの読み込み
wer = evaluate.load("wer")
predictions = ["hello world", "good night moon"]
references = ["hello world", "good night moon"]
wer_score = wer.compute(predictions=predictions, references=references)
print(wer_score)

WERは、異なるシステムの比較や、システム内の改善点を評価するための貴重なツールです。しかし、この種の測定では、翻訳エラーの性質に関する詳細な情報は得られない点については注意が必要です。

Wikisplit

WIKI_SPLITは、SARI、EXACT、SACREBLEUの3つの指標を組み合わせたもので、機械で生成されたテキストの品質を評価するために用いることができます。

inputs

sources

原文のリスト

predictions

予測された文のリスト

references

参照文のリスト

outputs

sari

SARIスコア
0.0から100.0までの値をとり、値が高いほど評価対象モデルの性能が高いことを示す

sacrebleu

SacreBLEUスコア
0.0から100.0の間の任意の値を取りうる

exact

exact match スコア
範囲は0.0から100

利用例

""" シンプルな例 """
# wiki_splitモジュールの読み込み
wiki_split = evaluate.load("wiki_split")
sources = ["About 95 species are currently accepted ."]
predictions = ["About 95 species are currently accepted ."]
references= [["About 95 species are currently accepted ."]]
results = wiki_split.compute(sources=sources, predictions=predictions, references=references)
print(results)
# {'sari': 100.0, 'sacrebleu': 100.00000000000004, 'exact': 100.0}

この指標はWikiSplitデータセットでモデルを評価するための公式な指標ではありません。当初はRotheら(2020)が提案したものですが、WikiSplitデータセットを紹介したオリジナルの論文(2018)では、コーパスレベルのBLEUや文レベルのBLEUなど、異なる指標で性能評価をしています。

XNLI

XNLIはMNLIデータセットの数千例のサブセットで、スワヒリ語やウルドゥー語など比較的リソースの少ない14言語に翻訳されたデータセットで、モデルのスコアを評価することができます。

inputs

predictions

予測ラベルのリスト

references

真のラベルのリスト

利用例

""" シンプルな例 """
# xnliモジュールの読み込み
xnli_metric = evaluate.load("xnli")
predictions = [0, 1]
references = [0, 1]
results = xnli_metric.compute(predictions=predictions, references=references)
print(results)
# {'accuracy': 1.0}

精度だけでも性能の一定の目安にはなりますが、エラー分析や、データセットで表現される各カテゴリーでのモデルのミス、特にアンバランスな場合の理解を深めることで補完することができます。

XTREME-S

XTREME-Sは、Cross-lingual TRansfer Evaluation of Multilingual Encoders for Speech (XTREME-S) ベンチマークでのモデル性能を評価することを目的として作られたものです。このベンチマークは、言語、タスク、ドメイン、データ領域を横断して音声表現を評価するために設計されています。10以上の言語族からなる102の言語、3つの異なるドメイン、音声認識、翻訳、分類、検索の4つのタスク群を対象にしています。

モジュールの読み込み時の引数

xtreme_s_metric = evaluate.load('xtreme_s', 'この部分に入れる')

mlsvoxpopulicovost2fleurs-asrfleurs-lang_idminds14babel

上記の中から選ぶことができます。（詳細）

inputs

predictions

予測のリスト

references

基準のリスト

bleu_kwargs

covost2サブセットのbleuメトリックを計算する際に渡されるキーワードのディクショナリ
キーワードは、smooth_method, smooth_value, force, lowercase, tokenize, use_effective_orderのうちの1つ

wer_kwargs

mls, fleurs-asr, voxpopuli, babel サブセットで計算される wer と cer の計算時に渡されるキーワードのオプションディクショナリ
キーワードは concatenate_texts

outputs

accuracy

処理された総ケース数に対する正しい予測の割合
fleurs-lang_idとminds14のサブセットに対して返される

f1

適合率と再現率の調和平均
minds14 サブセットに対して返される

wer

単語誤り率
mls、fleurs-asr、voxpopuliおよびbabelサブセットに対して返される

cer

文字誤り率
mls、fleurs-asr、voxpopuli、babelサブセットで返される

bleu

BLEUスコア
covost2 サブセットに対して返される

利用例

""" シンプルな例 """
# xtreme_sモジュールの読み込み
xtreme_s_metric = evaluate.load('xtreme_s', 'mls')  
references = ["it is sunny here", "paper and pen are essentials"]
predictions = ["it's sunny", "paper pen are essential"]
results = xtreme_s_metric.compute(predictions=predictions, references=references)
print({k: round(v, 2) for k, v in results.items()})
# {'wer': 0.56, 'cer': 0.27}

このメトリクスはXTREME-Sデータセットと同じフォーマットのデータセットでのみ機能します。

Comparison一覧

Comparisonは、2つのモデルを比較するために使われます。例えば、予測値と正解ラベルを比較し、その一致度を計算します。すべてのComparisonはevaluate-comparisonで見ることができます。

また、comparison一覧は次のコードでも見ることができます。

evaluate.list_evaluation_modules(
　# モジュールのタイプをcomparisonに指定
  module_type="comparison",
  # コミュニティモジュールを除く
  include_community=False, 
　# 詳細を表示
  with_details=True)

では、それぞれのcomparisonの説明と使い方を見ていきます。

Exact Match

Exact Matchは、あるモデルの予測値が、別のモデルの予測値と正確に一致する割合を返します。

inputs

predictions1

モデル１の予測値

predictions2

モデル２の予測値

利用例

""" シンプルな例 """
# exact_matchモジュールの読み込み
exact_match = evaluate.load("exact_match", module_type="comparison")
results = exact_match.compute(predictions1=[0, 1, 1], predictions2=[1, 1, 1])
print(results)
# {'exact_match': 0.6666666666666666}

McNemar

McNemarの検定は，2つの分類器の予測から得られる分割表に対するノンパラメトリックな検定です。この検定は，同じグループの参照ラベルでの検出テストの感度と特異度を比較します。

inputs

predictions1

1番目のモデルからの予測値のリスト

predcitions2

2番目のモデルからの予測値のリスト

references

基準のラベルのリスト

outputs

stat

McNemar統計量

p

p 値

利用例

""" シンプルな例 """
# mcnemarモジュールの読み込み
mcnemar = evaluate.load("mcnemar")
results = mcnemar.compute(references=[1, 0, 1], predictions1=[1, 1, 1], predictions2=[1, 0, 1])
print(results)
# {'stat': 1.0, 'p': 0.31731050786291115}

McNemar 検定はノンパラメトリック検定なので、そのことによる制限には注意が必要です。

Measurement一覧

Measurementは、データセットをより深く理解し、その特性や特徴に基づいたモデル予測を行うための評価指標です。Measurementはevaluate-measurementで見ることができます。

また、comparison一覧は次のコードでも見ることができます。

evaluate.list_evaluation_modules(
　# モジュールのタイプをmeasurementに指定
  module_type="measurement",
  # コミュニティモジュールを除く
  include_community=False, 
　# 詳細を表示
  with_details=True)

では、それぞれのmeasurementの説明と使い方を見ていきます。

Perplexity

Perplexityは、モデルと入力テキスト列が与えられたとき、モデルが入力テキスト列を生成する可能性がどの程度あるかを測定します。指標としては、モデルが学習したテキストの分布をどの程度学習したかを評価するために用いることができます。

inputs

model_id

Perplexityを計算するために使用するモデル

predictions

入力テキスト、各スニペットが1つのリストエントリになる

batch_size

モデルを通してテキストを実行するバッチサイズ
デフォルトは16

add_start_token

テキストに開始トークンを追加し、最初の単語の確率を含む複雑さを計算するかどうか
デフォルトはTrue

device

実行するデバイス
デフォルトは ‘cuda’

利用例

""" シンプルな例 """
# perplexityモジュールの読み込み
perplexity = evaluate.load("perplexity", module_type="measurement")
input_texts = ["lorem ipsum", "Happy Birthday!", "Bienvenue"]
results = perplexity.compute(model_id='gpt2',
                             add_start_token=False,
                             predictions=input_texts)
print(results)
# {'perplexities': [11.108955383300781, 159.01539611816406, 64.5319595336914], 
# 'mean_perplexity': 78.21877034505208}

出力値はモデルがどのようなテキストで学習したかに大きく依存することに注意してください。つまり、モデルやデータセット間でperplexityスコアは比較できません。

Text Duplicates

text_duplicatesは、入力データの中で重複している文字列の割合を返します。

inputs

data

重複を計算する対象となる文字列

list_duplicates

duplicates_listを出力するか
デフォルトはFalse

outputs

duplicate_fraction

入力文字列中の重複する文字列の割合

duplicates_list

重複している文字列とその回数を示すタプルのリスト

利用例

""" シンプルな例 """
# text_duplicatesモジュールの読み込み
duplicates = evaluate.load("text_duplicates")
data = ["hello sun", "goodbye moon", "hello sun", "foo bar", "foo bar"]
results = duplicates.compute(data=data, list_duplicates=True)
print(results)
# {'duplicate_fraction': 0.4, 'duplicates_list': {'hello sun': 2, 'foo bar': 2}}

list_duplicates=Trueにすると、大きなデータセットではメモリを大量に消費する可能性があります。

Word Count

Word Countは、sklearnのCountVectorizerを使って、入力文字列の単語数の合計を返します。

inputs

data

単語長を計算するための文字列の入力リスト

max_vocab

考慮すべき単語の最大数

outputs

total_word_count

入力文字列中の総単語数

unique_words

入力文字列に含まれるユニークワードの数

利用例

""" シンプルな例 """
# word_countモジュールの読み込み
wordcount= evaluate.load("word_count")
data = ["hello world and hello moon"]
results = wordcount.compute(data=data)
print(results)
# {'total_word_count': 5, 'unique_words': 4}

Word Length

Word Lengthは、入力文字列の単語数を返します。

inputs

data

単語長を計算するための文字列の入力リスト

tokenizer

dataをトークン化するための手法
デフォルトはNLTK’s `word_tokenize`

利用例

""" シンプルな例 """
# word_lengthモジュールの読み込み
wordcount= evaluate.load("word_length", module_type="measurement")
data = ["hello world and hello moon"]
results = wordcount.compute(data=data)
print(results)
# {'average_word_length': 5}

最後に

今回は、機械学習で使える評価指標の利用方法を紹介してきました。

モジュールの読み込み時などでエラーが出た場合の対処方法も載せましたが、すべてを検証出来ているわけではないので、エラーが出る可能性もまだまだあります。

もし、エラーが出た場合はコメントなどで教えてください。