speechbrain.utils.metric_stats 模块

metric_stats 模块提供了一个抽象类，用于存储实验过程中生成的统计数据并进行汇总。

作者

Peter Plantinga 2020
Mirco Ravanelli 2020
Gaëlle Laperrière 2021
Sahar Ghannay 2021

摘要

类

`BinaryMetricStats`	跟踪二元指标，如精度、召回率、F1、EER 等。
`ClassificationStats`	计算与多标签分类任务相关的统计数据，以及出于评估目的可以大致解释为多标签分类任务的统计数据。
`EmbeddingErrorRateSimilarity`	实现了 EmbER 指标中的相似性函数，该函数定义于 https://www.isca-archive.org/interspeech_2022/roux22_interspeech.pdf
`ErrorRateStats`	一个用于跟踪错误率（例如，WER、PER）的类。
`MetricStats`	一个用于存储和汇总任意指标的默认类。
`MultiMetricStats`	一个同时评估多个指标的封装器
`WeightedErrorRateStats`	一个指标，它使用任何选定的方法重新衡量 `ErrorRateStats` 的 WER。

函数

`EER`	计算 EER（及其阈值）。
`minDCF`	计算通常用于评估说话人确认系统的 minDCF 指标。
`multiprocess_evaluation`	如果在多个任务上并行，则运行指标评估。
`sequence_evaluation`	按顺序在输入上运行指标评估。

参考

class speechbrain.utils.metric_stats.MetricStats(metric, n_jobs=1, batch_eval=True)[source]

基类: object

一个用于存储和汇总任意指标的默认类。

通过继承此类可以创建更复杂的指标。

参数:

metric (function) – 用于计算相关指标的函数。应至少接受两个参数（predictions 和 targets），并且可以选择接受其中一个或两个参数的相对长度。通常不在子类中使用。
n_jobs (int) – 用于计算指标的并行任务数量。如果大于 1，则单独处理每个样本，否则一次性传递整个批次。
batch_eval (bool) – 如果为 True，则将批处理输入馈送到评估指标。如果为 False 且 n_jobs=1，则按顺序逐个进行指标评估。如果为 False 且 n_jobs>1，则使用 joblib 在不同输入上并行运行评估。

示例

>>> from speechbrain.nnet.losses import l1_loss
>>> loss_stats = MetricStats(metric=l1_loss)
>>> loss_stats.append(
...      ids=["utterance1", "utterance2"],
...      predictions=torch.tensor([[0.1, 0.2], [0.2, 0.3]]),
...      targets=torch.tensor([[0.1, 0.2], [0.1, 0.2]]),
...      reduction="batch",
... )
>>> stats = loss_stats.summarize()
>>> stats['average']
0.050...
>>> stats['max_score']
0.100...
>>> stats['max_id']
'utterance2'

clear()[source]: 创建用于存储的空容器，移除现有统计信息。

append(ids, *args, **kwargs)[source]

存储一组特定的指标得分。

参数:

ids (list) – 与话语相对应的 ID 列表。
*args (tuple) – 传递给指标函数的参数。
**kwargs (dict) – 传递给指标函数的参数。

summarize(field=None)[source]

汇总指标得分，返回相关统计数据。

参数:: field (str) – 如果提供，则仅返回选定的统计数据。否则，返回所有计算的统计数据。
返回:: 如果提供了 field，则返回一个 float，否则返回一个包含所有计算统计数据的字典。
返回类型:: float 或 dict

write_stats(filestream, verbose=False)[source]

将所有相关统计数据写入文件。

参数:

filestream (file-like object) – 用于写入统计数据的流。
verbose (bool) – 是否同时将统计数据打印到标准输出。

speechbrain.utils.metric_stats.multiprocess_evaluation(metric, predict, target, lengths=None, n_jobs=8)[source]: 如果在多个任务上并行，则运行指标评估。

speechbrain.utils.metric_stats.sequence_evaluation(metric, predict, target, lengths=None)[source]: 按顺序在输入上运行指标评估。

class speechbrain.utils.metric_stats.ErrorRateStats(merge_tokens=False, split_tokens=False, space_token='_', keep_values=True, extract_concepts_values=False, tag_in='', tag_out='', equality_comparator: ~typing.Callable[[str, str], bool] = <function _str_equals>)[source]

基类: MetricStats

一个用于跟踪错误率（例如，WER、PER）的类。

参数:

merge_tokens (bool) – 是否合并连续的 token（例如，用于从字符 token 创建单词）。请参阅 speechbrain.dataio.dataio.merge_char。
split_tokens (bool) – 是否分割 token（例如，用于从词 token 创建字符）。请参阅 speechbrain.dataio.dataio.split_word。
space_token (str) – 用于边界的字符。与 merge_tokens 一起使用时，这表示合并后用于分割的字符。与 split_tokens 一起使用时，序列会用此 token 连接起来，然后整个序列被分割。
keep_values (bool) – 是否保留概念的值。
extract_concepts_values (bool) – 处理预测和目标，仅保留概念和值。
tag_in (str) – 概念的开始（例如 ‘<’）。
tag_out (str) – 概念的结束（例如 ‘>’）。
equality_comparator (Callable[[str, str], bool]) – 用于检查两个词是否相等的函数。

示例

>>> cer_stats = ErrorRateStats()
>>> i2l = {0: 'a', 1: 'b'}
>>> cer_stats.append(
...     ids=['utterance1'],
...     predict=torch.tensor([[0, 1, 1]]),
...     target=torch.tensor([[0, 1, 0]]),
...     target_len=torch.ones(1),
...     ind2lab=lambda batch: [[i2l[int(x)] for x in seq] for seq in batch],
... )
>>> stats = cer_stats.summarize()
>>> stats['WER']
33.33...
>>> stats['insertions']
0
>>> stats['deletions']
0
>>> stats['substitutions']
1

append(ids, predict, target, predict_len=None, target_len=None, ind2lab=None)[source]

将统计信息添加到相关容器。

请参阅 MetricStats.append()

参数:

ids (list) – 与话语相对应的 ID 列表。
predict (torch.tensor) – 预测输出，用于与目标输出进行比较
target (torch.tensor) – 正确的参考输出，用于与预测进行比较。
predict_len (torch.tensor) – 预测的相对长度，用于取消预测中的填充（如果存在）。
target_len (torch.tensor) – 目标输出的相对长度，用于取消目标中的填充（如果存在）。
ind2lab (callable) – 可调用对象，用于将索引映射到标签，在批次上操作，用于写入对齐。

summarize(field=None)[source]

汇总 error_rate 并返回相关统计数据。

请参阅 MetricStats.summarize()

write_stats(filestream)[source]: 将所有相关信息（例如，错误率对齐）写入文件。* 请参阅 MetricStats.write_stats()

class speechbrain.utils.metric_stats.WeightedErrorRateStats(base_stats: ErrorRateStats, cost_function: Callable[[str, str | None, str | None], float], weight_name: str = 'weighted')[source]

基类: MetricStats

一个指标，它使用任何选定的方法重新衡量 ErrorRateStats 的 WER。这不会修改找到的编辑序列（插入/删除/替换），但会将其对指标的影响乘以成本函数返回的 0 到 1 之间的值。

参数:

base_stats (ErrorRateStats) – 要使用的基础 WER 计算器。
成本函数 (Callable[[str, Optional[str], Optional[str]], float]) – 成本函数，签名格式为 fn(edit_symbol, a, b) -> float，返回值为 0 到 1 之间的浮点数，该值表示在加权 WER 计算中应分配给特定编辑的权重。对于插入和删除情况，a 或 b 中的任何一个可能为 None。对于替换情况，a 和 b 绝不会是 None。
weight_name (str) – 将作为前缀添加到每个指标名称前（例如 xxx_wer）

append(*args, **kwargs)[source]

Append 函数，不应用于加权错误率统计。请转而附加到指定的 base_stats。

WeightedErrorRateStats 重用基础 ErrorRateStats 类中的分数。

参数:

*args (tuple) – 忽略。
**kwargs (dict) – 忽略。

summarize(field=None)[source]

返回一个字典，其中包含一些详细的加权 WER 统计信息，这些信息是通过使用 cost_function 确定的权重（无错误返回 0.0，默认错误行为返回 1.0，介于两者之间则返回其他值）对每次编辑进行加权后计算得出的。

不要求已经调用过 summarize()。

完整的字段集合，**每个字段都带有 <weight_name_specified_at_init>_ 前缀：** - wer: 加权 WER（比率 *100） - insertions: 加权插入数 - substitutions: 加权替换数 - deletions: 加权删除数 - num_edits: 加权插入数/替换数/删除数之和

此外，此函数会为每对句子填充一个 scores 列表。该列表的每个条目都是一个字典，包含以下字段： - key: 话语的 ID。

WER, insertions, substitutions, deletions, num_edits 具有与上述相同的语义，但作用于句子级别而非全局级别。

参数:

field (str, optional) – 要返回的字段，如果您只对其中一个感兴趣。如果指定，将返回一个单独的 float，否则返回一个字典。

返回:

dict from str to float, if field is None – 一个包含上述文档字段的字典。
float, if field is not None – 由 field 选择的单个字段。

write_stats(filestream)[source]: 将所有相关信息写入文件；此处仅写入由 summarize 返回的加权信息。参见 write_stats()。

class speechbrain.utils.metric_stats.EmbeddingErrorRateSimilarity(embedding_function: Callable[[str], Tensor | None], low_similarity_weight: float, high_similarity_weight: float, threshold: float)[source]

基类: object

实现了 EmbER 指标中的相似性函数，该函数定义于 https://www.isca-archive.org/interspeech_2022/roux22_interspeech.pdf

此指标涉及一个将标记映射到单个词嵌入的字典。当嵌入相似度足够高时，WER 中的替换错误会被降低权重。目标是减少语义影响较小的替换错误的影响。只有替换错误会被加权。

这是通过计算两个嵌入之间的余弦相似度来完成的，然后如果 similarity >= threshold，则使用 low_similarity_weight 对替换进行加权，否则使用 high_similarity_weight 进行加权（例如，高相似度的替换可以降低权重，使其重要性仅为低相似度替换的 10%）。

Note

引用的论文建议使用 (1.0, 0.1, 0.4) 作为 fastText 法语嵌入的默认值，这是通过经验选择的。使用不同的嵌入时，您可能需要测试其他值；因此我们不提供默认值。

参数:

embedding_function (Callable[[str], Optional[torch.Tensor]]) – 一个函数，根据词返回一个嵌入（作为 torch.Tensor）。如果找不到该词对应的嵌入，应返回 None。在这种情况下，将选择 low_similarity_weight。
low_similarity_weight (float) – 如果 cosine_similarity < threshold，则应用于替换的权重。
high_similarity_weight (float) – 如果 cosine_similarity >= threshold，则应用于替换的权重。
threshold (float) – 余弦相似度阈值，用于确定该词的替换错误应加权多少。

__call__(edit_symbol: str, a: str | None, b: str | None) → float[source]

返回在 WER 计算中应与特定编辑相关联的权重。

WeightedErrorRateStats 的成本函数兼容候选项，因此可以将此类的实例作为 cost_function 传递。

参数:

edit_symbol (str) – 由 WER 函数分配的编辑符号，参见 EDIT_SYMBOLS。
a (str, optional) – 要比较的第一个词（如果存在）
b (str, optional) – 要比较的第二个词（如果存在）

返回:

分配给编辑的权重。对于实际编辑，根据嵌入距离和阈值，权重为 low_similarity_weight 或 high_similarity_weight。

返回类型:

float

class speechbrain.utils.metric_stats.BinaryMetricStats(positive_label=1)[source]

基类: MetricStats

跟踪二元指标，如精度、召回率、F1、EER 等。

clear()[source]: 清除存储的指标。

append(ids, scores, labels)[source]

将分数和标签附加到内部列表。

在汇总时才计算指标，因为自动阈值（例如 EER）需要全部分数集合。

参数:

ids (list) – 样本的字符串 ID。
scores (list) – 与 ID 对应的分数。
labels (list) – 与 ID 对应的标签。

summarize(field=None, threshold=None, max_samples=None, beta=1, eps=1e-08)[source]

使用全部分数集合计算统计数据。

完整的字段集合

TP - 真阳性
TN - 真阴性
FP - 假阳性
FN - 假阴性
FAR - 错误接受率
FRR - 错误拒绝率
DER - 检测错误率（如果未传递阈值，则为 EER）
threshold - 阈值（如果未传递阈值，则为 EER 阈值）
precision - 精确率（阳性预测值）
recall - 召回率（敏感性）
F-score - 精确率和召回率的平衡（如果 beta=1 则相等）
MCC - 麦考利相关系数

参数:

field (str) – 用于选择单个统计信息的键。如果未提供，则返回包含所有统计信息的字典。
threshold (float) – 如果未提供阈值，则使用相等错误率。
max_samples (float) – 为阳性/阴性分数保留多少样本。如果未提供 max_samples，则保留所有分数。仅当 threshold 为 None 时有效。
beta (float) – F-score 中精确率与召回率的加权程度。默认值 1 表示权重相等，较高值更侧重召回率，较低值更侧重精确率。
eps (float) – 一个用于避免除以零的小值。

返回:

如果指定了 field，则只返回该字段的分数。如果 field 为 None，则返回完整的字段集合。

返回类型:

summary

speechbrain.utils.metric_stats.EER(positive_scores, negative_scores)[source]

计算 EER（及其阈值）。

参数:

positive_scores (torch.tensor) – 来自同类条目的分数。
negative_scores (torch.tensor) – 来自不同类条目的分数。

返回:

EER (float) – EER 分数。
threshold (float) – EER 分数对应的阈值。

示例

>>> positive_scores = torch.tensor([0.6, 0.7, 0.8, 0.5])
>>> negative_scores = torch.tensor([0.4, 0.3, 0.2, 0.1])
>>> val_eer, threshold = EER(positive_scores, negative_scores)
>>> val_eer
0.0

speechbrain.utils.metric_stats.minDCF(positive_scores, negative_scores, c_miss=1.0, c_fa=1.0, p_target=0.01)[source]

计算通常用于评估说话人识别系统的 minDCF 指标。min_DCF 是在定义的阈值范围内计算的以下 C_det 函数的最小值：

C_det = c_miss * p_miss * p_target + c_fa * p_fa * (1 -p_target)

其中 p_miss 是漏识概率，p_fa 是误报概率。

参数:

positive_scores (torch.tensor) – 来自同类条目的分数。
negative_scores (torch.tensor) – 来自不同类条目的分数。
c_miss (float) – 分配给漏识错误的成本（默认值 1.0）。
c_fa (float) – 分配给误报的成本（默认值 1.0）。
p_target (float) – 存在目标的先验概率（默认值 0.01）。

返回:

minDCF (float) – minDCF 分数。
threshold (float) – minDCF 分数对应的阈值。

示例

>>> positive_scores = torch.tensor([0.6, 0.7, 0.8, 0.5])
>>> negative_scores = torch.tensor([0.4, 0.3, 0.2, 0.1])
>>> val_minDCF, threshold = minDCF(positive_scores, negative_scores)
>>> val_minDCF
0.0

class speechbrain.utils.metric_stats.ClassificationStats[source]

基类: MetricStats

计算与多标签分类任务相关的统计数据，以及出于评估目的可以大致解释为多标签分类任务的统计数据。

示例

>>> import sys
>>> from speechbrain.utils.metric_stats import ClassificationStats
>>> cs = ClassificationStats()
>>> cs.append(
...     ids=["ITEM1", "ITEM2", "ITEM3", "ITEM4"],
...     predictions=[
...         "M EY K AH",
...         "T EY K",
...         "B AE D",
...         "M EY K",
...     ],
...     targets=[
...         "M EY K",
...         "T EY K",
...         "B AE D",
...         "M EY K",
...     ],
...     categories=[
...         "make",
...         "take",
...         "bad",
...         "make"
...     ]
... )
>>> cs.write_stats(sys.stdout)
Overall Accuracy: 75%

Class-Wise Accuracy
-------------------
bad -> B AE D : 1 / 1 (100.00%)
make -> M EY K: 1 / 2 (50.00%)
take -> T EY K: 1 / 1 (100.00%)

Confusion
---------
Target: bad -> B AE D
  -> B AE D   : 1 / 1 (100.00%)
Target: make -> M EY K
  -> M EY K   : 1 / 2 (50.00%)
  -> M EY K AH: 1 / 2 (50.00%)
Target: take -> T EY K
  -> T EY K   : 1 / 1 (100.00%)
>>> summary = cs.summarize()
>>> summary['accuracy']
0.75
>>> summary['classwise_stats'][('bad', 'B AE D')]
{'total': 1.0, 'correct': 1.0, 'accuracy': 1.0}
>>> summary['classwise_stats'][('make', 'M EY K')]
{'total': 2.0, 'correct': 1.0, 'accuracy': 0.5}
>>> summary['keys']
[('bad', 'B AE D'), ('make', 'M EY K'), ('take', 'T EY K')]
>>> summary['predictions']
['B AE D', 'M EY K', 'M EY K AH', 'T EY K']
>>> summary['classwise_total']
{('bad', 'B AE D'): 1.0, ('make', 'M EY K'): 2.0, ('take', 'T EY K'): 1.0}
>>> summary['classwise_correct']
{('bad', 'B AE D'): 1.0, ('make', 'M EY K'): 1.0, ('take', 'T EY K'): 1.0}
>>> summary['classwise_accuracy']
{('bad', 'B AE D'): 1.0, ('make', 'M EY K'): 0.5, ('take', 'T EY K'): 1.0}

append(ids, predictions, targets, categories=None)[source]

将输入、预测和目标附加到内部列表

参数:

ids (list) – 样本的字符串 ID
predictions (list) – 模型的预测结果（人类可理解，最好是字符串）
targets (list) – 地面实况（人类可理解，最好是字符串）
categories (list) – 分类训练样本的额外方式。如果可用，类别将与目标结合使用

summarize(field=None)[source]

汇总分类指标分数

计算以下统计数据

accuracy: 总体准确率（# 正确 / # 总数） confusion_matrix: 表示混淆矩阵的字典，格式为

{(目标, 预测): 条目数}

classwise_stats: 计算每个类别的总样本数，: 正确分类数和准确率
keys: 所有可用的类别键，可以是目标类别: 或 (类别, 目标) 元组
predictions: 所有可用的预测结果模型: 已进行的所有预测

参数:: field (str) – 如果提供，则仅返回选定的统计数据。否则，返回所有计算的统计数据。
返回:: 如果提供了 field，则返回一个 float，否则返回一个包含所有计算统计数据的字典。
返回类型:: float 或 dict

clear()[source]: 清除收集的统计数据

write_stats(filestream)[source]

将统计数据以人类可读的格式输出到指定的 filestream

参数:: filestream (file) – 文件状对象

class speechbrain.utils.metric_stats.MultiMetricStats(metric, n_jobs=1, batch_eval=False)[source]

基类: object

一个同时评估多个指标的封装器

参数:

metric (function) – 用于计算相关指标的函数。应至少接受两个参数（预测和目标），并可选择接受其中一个或两个参数的相对长度。函数应返回一个 dict 或 namedtuple
n_jobs (int) – 用于计算指标的并行任务数量。如果大于 1，则单独处理每个样本，否则一次性传递整个批次。
batch_eval (bool) – 如果为 True，则将批处理输入馈送到评估指标。如果为 False 且 n_jobs=1，则按顺序逐个进行指标评估。如果为 False 且 n_jobs>1，则使用 joblib 在不同输入上并行运行评估。

示例

>>> def metric(a, b):
...    return {
...        "sum": a + b,
...        "diff": a - b,
...        "sum_sq": a**2 + b**2
...    }
>>> multi_metric = MultiMetricStats(metric, batch_eval=True)
>>> multi_metric.append([1, 2], a=torch.tensor([2.0, 1.0]), b=torch.tensor([1.0, 2.0]))
>>> multi_metric.append([3, 4], a=torch.tensor([4.0, 5.0]), b=torch.tensor([0.0, 1.0]))
>>> multi_metric.append([5, 6], a=torch.tensor([2.0, 4.0]), b=torch.tensor([4.0, 2.0]))
>>> multi_metric.append([7, 8], a=torch.tensor([2.0, 4.0]), b=torch.tensor([4.0, 2.0]))
>>> multi_metric.summarize()
{'sum': {'average': 5.0,
  'min_score': 3.0,
  'min_id': 1,
  'max_score': 6.0,
  'max_id': 4},
 'diff': {'average': 1.0,
  'min_score': -2.0,
  'min_id': 5,
  'max_score': 4.0,
  'max_id': 3},
 'sum_sq': {'average': 16.5,
  'min_score': 5.0,
  'min_id': 1,
  'max_score': 26.0,
  'max_id': 4}}
>>> multi_metric.summarize(flat=True)
{'sum_average': 5.0,
 'sum_min_score': 3.0,
 'sum_min_id': 1,
 'sum_max_score': 6.0,
 'sum_max_id': 4,
 'diff_average': 1.0,
 'diff_min_score': -2.0,
 'diff_min_id': 5,
 'diff_max_score': 4.0,
 'diff_max_id': 3,
 'sum_sq_average': 16.5,
 'sum_sq_min_score': 5.0,
 'sum_sq_min_id': 1,
 'sum_sq_max_score': 26.0,
 'sum_sq_max_id': 4}

append(ids, *args, **kwargs)[source]

存储一组特定的指标得分。

参数:

ids (list) – 与话语相对应的 ID 列表。
*args (tuple) – 传递给指标函数的参数。
**kwargs (dict) – 传递给指标函数的参数。

eval_simple(*args, **kwargs)[source]: 以简单、顺序的方式评估指标

summarize(field=None, flat=False)[source]

汇总指标得分，返回相关统计数据。

参数:

field (str) – 如果提供，则仅返回选定的统计数据。否则，返回所有计算的统计数据。
flat (bool) – 是否展平字典

返回:

返回所有计算出的统计数据字典

返回类型:

dict