speechbrain.utils.data_utils 模块

这个库收集了数据输入/输出操作的实用工具。

作者

Mirco Ravanelli 2020
Aku Rouhe 2020
Samuele Cornell 2020
Adel Moumen 2024
Pierre Champion 2023

摘要

函数

`batch_pad_right`	给定一个 torch tensor 列表，通过在每个维度右侧填充将它们批量处理在一起，以使所有 tensor 具有相同的长度。
`batch_shuffle`	在序列内打乱固定大小的批次
`concat_padded_features`	以向量化方式将多个填充特征张量连接到一个单个填充张量中，最终张量不包含内部填充，只在末尾添加填充。
`dict_value_combinations`	返回给定字典中所有可能的键值组合
`dict_value_combinations_gen`	返回指定值字典的排列生成器
`dist_stats`	返回标准分布统计信息（均值、标准差、最小值、最大值）
`download_file`	从给定源下载文件并将其保存在给定目标路径。
`get_all_files`	返回在文件夹中找到的文件列表。
`get_list_from_csv`	从输入 csv 文件的选定字段获取列表。
`length_range`	创建一个 tensor，其单个维度的范围与另一个 tensor 的形状匹配
`masked_max`	一个计算每个样本最小值的度量函数
`masked_mean`	计算每个样本均值（不包含填充）的度量函数
`masked_min`	一个计算每个样本最小值的度量函数
`masked_std`	计算每个样本标准差（不包含填充）的度量函数
`match_shape`	一个瑞士军刀式的辅助函数，用于使一个 tensor 的形状与另一个 tensor 的形状匹配 - 对于掩码等很有用。
`mod_default_collate`	从批量值列表中创建一个 tensor。
`non_batch_dims`	返回指定 tensor 的所有维度，批处理维度除外
`pad_divisible`	在 tensor 的指定维度添加额外填充，使其可被指定因子整除。
`pad_right_to`	此函数接收一个任意形状的 torch tensor，通过在右侧附加值将其填充到目标形状。
`recursive_items`	生成嵌套字典的每个 (key, value)。
`recursive_to`	将数据移动到设备或转换为其他类型，并处理容器。
`recursive_update`	类似于 `dict.update` 的函数，但用于嵌套的 `dict`。
`scalarize`	将包含 tensor 的 namedtuple 或字典转换为其标量值
`set_writing_permissions`	此函数为给定文件夹中的所有文件设置用户写入权限。
`split_by_whitespace`	str.split 的一个非常基本的功能版本
`split_list`	返回序列中的分块列表。
`split_path`	将路径分割为源和文件名
`trim_as`	裁剪指定 tensor 以匹配另一个 tensor 的形状（至多）
`trim_to_shape`	裁剪指定 tensor 以匹配指定形状
`undo_padding`	给定一批句子及其对应的相对长度，生成 Python 列表。
`unsqueeze_1d`	将一维 tensor 扩展到指定维度数，保留一个维度并在其他位置创建“哑”维度
`unsqueeze_as`	重塑 tensor 以使其形状与目标 tensor 兼容，仅在 x.dim() <= y.dim() 时有效

参考

speechbrain.utils.data_utils.undo_padding(batch, lengths)[source]

给定一批句子及其对应的相对长度，生成 Python 列表。

参数:

batch (torch.Tensor) – 批量句子集合在一个批次中。
lengths (torch.Tensor) – 批次中每个句子的相对长度。

返回:

as_list – 对应输入 tensor 的 python 列表。

返回类型:

list

示例

>>> batch=torch.rand([4,100])
>>> lengths=torch.tensor([0.5,0.6,0.7,1.0])
>>> snt_list=undo_padding(batch, lengths)
>>> len(snt_list)
4

speechbrain.utils.data_utils.get_all_files(dirName, match_and=None, match_or=None, exclude_and=None, exclude_or=None)[source]

返回在文件夹中找到的文件列表。

可以使用不同的选项将搜索限制到某些特定模式。

参数:

dirName (str) – 要搜索的目录。
match_and (list) – 包含要匹配模式的列表。如果文件匹配 match_and 中的所有条目，则返回该文件。
match_or (list) – 包含要匹配模式的列表。如果文件匹配 match_or 中的一个或多个条目，则返回该文件。
exclude_and (list) – 包含要匹配模式的列表。如果文件不匹配 exclude_and 中的任何条目，则返回该文件。
exclude_or (list) – 包含要匹配模式的列表。如果文件未能匹配 exclude_or 中的任何条目，则返回该文件。

返回:

allFiles – 匹配模式的文件列表。

返回类型:

list

示例

>>> get_all_files('tests/samples/RIRs', match_and=['3.wav'])
['tests/samples/RIRs/rir3.wav']

speechbrain.utils.data_utils.get_list_from_csv(csvfile, field, delimiter=',', skipinitialspace=True)[source]

从输入 csv 文件的选定字段获取列表。

参数:

csvfile (路径) – csv 文件路径。
field (str) – 用于创建列表的 csv 文件字段。
delimiter (str) – csv 文件的分隔符。
skipinitialspace (bool) – 设置为 true 可跳过条目中的初始空格。

返回类型:

给定 csv 文件字段中的文件列表

speechbrain.utils.data_utils.split_list(seq, num)[source]

返回序列中的分块列表。

参数:

seq (可迭代对象) – 要分割的输入列表。
num (int) – 要生成的块数。

返回类型:

一个列表的列表，长度为 num，包含 seq 的所有元素。

示例

>>> split_list([1, 2, 3, 4, 5, 6, 7, 8, 9], 4)
[[1, 2], [3, 4], [5, 6], [7, 8, 9]]

speechbrain.utils.data_utils.recursive_items(dictionary)[source]

生成嵌套字典的每个 (key, value)。

参数:: dictionary (dict) – 要列出的嵌套字典。
生成:: 字典中的 (key, value) 元组。

示例

>>> rec_dict={'lev1': {'lev2': {'lev3': 'current_val'}}}
>>> [item for item in recursive_items(rec_dict)]
[('lev3', 'current_val')]

speechbrain.utils.data_utils.recursive_update(d, u, must_match=False)[source]

类似于 dict.update 的函数，但用于嵌套的 dict。

来源: https://stackoverflow.com/a/3233356

如果你有一个嵌套映射结构，例如

{“a”: 1, “b”: {“c”: 2}}

假设你想用以下内容更新上述结构

{“b”: {“d”: 3}}

此函数将产生

{“a”: 1, “b”: {“c”: 2, “d”: 3}}

而不是

{“a”: 1, “b”: {“d”: 3}}

参数:

d (dict) – 要更新的映射。
u (dict) – 用于更新的映射。
must_match (bool) – 如果 u 中的键在 d 中不存在是否抛出错误。

示例

>>> d = {'a': 1, 'b': {'c': 2}}
>>> recursive_update(d, {'b': {'d': 3}})
>>> d
{'a': 1, 'b': {'c': 2, 'd': 3}}

speechbrain.utils.data_utils.download_file(source, dest, unpack=False, dest_unpack=None, replace_existing=False, write_permissions=False)[source]

从给定源下载文件并将其保存在给定目标路径。

参数

网页。

dest路径

目标路径。

unpack布尔值

如果为 True，它会将数据解压到 dest 文件夹。压缩包将被保留。

支持解压的文件格式有

shutil.get_archive_formats() 枚举的任何格式，通常包括 .tar、.tar.gz、.zip。
普通 .gz 文件（当不是 .tar 压缩包时）

请注意，出于安全原因，你应该 ALWAYS 信任你正在解压的压缩包。

dest_unpack: 路径

存储解压数据集的路径

replace_existing布尔值

如果为 True，则替换现有文件。

write_permissions: 布尔值

当设置为 True 时，dest_unpack 目录中的所有文件都将被授予写入权限。此选项仅在 unpack=True 时有效。

speechbrain.utils.data_utils.set_writing_permissions(folder_path)[source]

此函数为给定文件夹中的所有文件设置用户写入权限。

参数:: folder_path (文件夹) – 将被授予写入权限的文件夹。

speechbrain.utils.data_utils.pad_right_to(tensor, target_shape, mode='constant', value=0)[source]

此函数接收一个任意形状的 torch tensor，通过在右侧附加值将其填充到目标形状。

参数:

tensor (torch.Tensor) – 需要填充维度的输入 tensor。
target_shape ((列表, 元组)) – 目标 tensor 的目标形状，其长度必须等于 tensor.ndim
mode (str) – 填充模式，请参阅 torch.nn.functional.pad 文档。
value (float) – 填充值，请参阅 torch.nn.functional.pad 文档。

返回:

tensor (torch.Tensor) – 填充后的 tensor。
valid_vals (list) – 包含原始非填充值在每个维度的比例的列表。

speechbrain.utils.data_utils.batch_pad_right(tensors: list, mode='constant', value=0)[source]

给定一个 torch tensor 列表，通过在每个维度右侧填充将它们批量处理在一起，以使所有 tensor 具有相同的长度。

参数:

tensors (list) – 我们希望一起填充的 tensor 列表。
mode (str) – 填充模式，请参阅 torch.nn.functional.pad 文档。
value (float) – 填充值，请参阅 torch.nn.functional.pad 文档。

返回:

tensor (torch.Tensor) – 填充后的 tensor。
valid_vals (list) – 包含原始非填充值在每个维度的比例的列表。

speechbrain.utils.data_utils.split_by_whitespace(text)[source]: str.split 的一个非常基本的功能版本

speechbrain.utils.data_utils.recursive_to(data, *args, **kwargs)[source]

将数据移动到设备或转换为其他类型，并处理容器。

与 torch.utils.data._utils.pin_memory.pin_memory 非常相似，但应用的是 .to()。

speechbrain.utils.data_utils.mod_default_collate(batch)[source]

从批量值列表中创建一个 tensor。

注意，这不需要将 zip(*) 值连接起来，因为 PaddedBatch 已经（通过键）连接了它们。

这里的想法是不出错。

这是从以下链接修改而来: https://github.com/pytorch/pytorch/blob/c0deb231db76dbea8a9d326401417f7d1ce96ed5/torch/utils/data/_utils/collate.py#L42

speechbrain.utils.data_utils.split_path(path)[source]

将路径分割为源和文件名

除了常规路径外，这也处理 URL 和 Huggingface hub 路径。

参数:

path (str 或 FetchSource)

返回:

str – 源
str – 文件名

speechbrain.utils.data_utils.scalarize(value)[source]

将包含 tensor 的 namedtuple 或字典转换为其标量值

参数:: value (dict 或 namedtuple) – 包含 tensor 的字典或命名元组
返回:: result – 结果字典
返回类型:: dict

speechbrain.utils.data_utils.unsqueeze_as(x, target)[source]

重塑 tensor 以使其形状与目标 tensor 兼容，仅在 x.dim() <= y.dim() 时有效

参数:

x (torch.Tensor) – 原始 tensor
target (torch.Tensor) – 其形状的 tensor

返回:

result – tensor x 重塑后与 y 形状兼容的视图

返回类型:

torch.Tensor

speechbrain.utils.data_utils.pad_divisible(tensor, length=None, factor=2, len_dim=1, pad_value=0)[source]

在 tensor 的指定维度添加额外填充，使其可被指定因子整除。这在使用可变长序列输入到下采样 UNet 或其他类似架构时很有用，这些架构要求输入可被下采样因子整除。

参数:

tensor (torch.Tensor) – 要填充的 tensor，任意维度
length (torch.Tensor) – 一维相对长度 tensor
factor (int) – 整除因子
len_dim (int) – 用作长度的维度的索引
pad_value (int) – 输出将使用的填充值

返回:

tensor_padded (torch.Tensor) – 填充后的 tensor，如果需要会额外填充
length (torch.Tensor) – 调整后的长度 tensor，如果提供

示例

>>> x = torch.tensor([[1, 2, 3, 4],
...                   [5, 6, 0, 0]])
>>> lens = torch.tensor([1., .5])
>>> x_pad, lens_pad = pad_divisible(x, length=lens, factor=5)
>>> x_pad
tensor([[1, 2, 3, 4, 0],
        [5, 6, 0, 0, 0]])
>>> lens_pad
tensor([0.8000, 0.4000])

speechbrain.utils.data_utils.trim_to_shape(tensor, shape)[source]

裁剪指定 tensor 以匹配指定形状

参数:

tensor (torch.Tensor) – 一个 tensor
shape (可枚举对象) – 期望的形状

返回:

tensor – 裁剪后的 tensor

返回类型:

torch.Tensor

speechbrain.utils.data_utils.trim_as(tensor, other)[source]

裁剪指定 tensor 以匹配另一个 tensor 的形状（至多）

参数:

tensor (torch.Tensor:) – 一个 tensor
other (torch.Tensor) – 要匹配其形状的 tensor

返回:

tensor – 裁剪后的 tensor

返回类型:

torch.Tensor

speechbrain.utils.data_utils.match_shape(tensor, other)[source]

一个瑞士军刀式的辅助函数，用于使一个 tensor 的形状与另一个 tensor 的形状匹配 - 对于掩码等很有用。

参数:

tensor (torch.Tensor:) – 一个 tensor
other (torch.Tensor) – 要匹配其形状的 tensor

返回:

tensor – 形状匹配的 tensor

返回类型:

torch.Tensor

speechbrain.utils.data_utils.batch_shuffle(items, batch_size)[source]

在序列内打乱固定大小的批次

参数:

items (序列) – 一个 tensor 或可索引序列，例如列表
batch_size (int) – 批量大小

返回:

items – 原始项。如果传入的是 tensor，则返回 tensor。否则，将返回列表

返回类型:

序列

speechbrain.utils.data_utils.concat_padded_features(feats, lens, dim=1, feats_slice_start=None, feats_slice_end=None)[source]

以向量化方式将多个填充特征张量连接到一个单个填充张量中，最终张量不包含内部填充，只在末尾添加填充。该函数支持对张量进行可选的相对切片。

一个可能的用例是连接频谱图或音频的批次。

参数:

feats (list) – 填充 tensor 的列表
lens (list) – 长度 tensor 的列表
dim (int) – 执行连接的维度
feats_slice_start (list) – 相对于序列开头的偏移量，用于每个要连接的 tensor。如果只包含某些切片的子序列，这会很有用。
feats_slice_end (list) – 相对于序列末尾的偏移量，用于每个要连接的 tensor。如果只包含某些切片的子序列，这会很有用。

返回:

out – 连接后的 tensor

返回类型:

torch.Tensor

speechbrain.utils.data_utils.unsqueeze_1d(value, dim, value_dim)[source]

将一维 tensor 扩展到指定维度数，保留一个维度并在其他位置创建“哑”维度

参数:

value (torch.Tensor) – 一维 tensor
dim (int) – 维度数量
value_dim (int) – value tensor 代表的维度

返回:

result – 一个 dim 维 tensor

返回类型:

torch.Tensor

speechbrain.utils.data_utils.length_range(feats, len_dim)[source]

创建一个 tensor，其单个维度的范围与另一个 tensor 的形状匹配

参数:

feats (torch.Tensor) – 任意形状的特征 tensor
len_dim (torch.Tensor) – 用作长度的维度

返回:

result – 一个与 feats 形状匹配的 tensor，沿着长度维度具有 0 到最大长度的范围，并在其他维度重复

返回类型:

torch.Tensor

speechbrain.utils.data_utils.non_batch_dims(sample)[source]

返回指定 tensor 的所有维度，批处理维度除外

参数:: sample (torch.Tensor) – 一个任意 tensor
返回:: dims – 维度列表
返回类型:: list

speechbrain.utils.data_utils.masked_mean(sample, mask=None)[source]

计算每个样本均值（不包含填充）的度量函数

参数:

sample (torch.Tensor) – 一个声谱图张量
mask (torch.Tensor) – 一个长度掩码

返回:

result – 一个均值张量

返回类型:

torch.Tensor

speechbrain.utils.data_utils.masked_std(sample, mask=None)[source]

计算每个样本标准差（不包含填充）的度量函数

参数:

sample (torch.Tensor) – 一个声谱图张量
mask (torch.Tensor) – 一个长度掩码

返回:

result – 一个均值张量

返回类型:

torch.Tensor

speechbrain.utils.data_utils.masked_min(sample, mask=None)[source]

一个计算每个样本最小值的度量函数

参数:

sample (torch.Tensor) – 一个声谱图张量
mask (torch.Tensor) – 一个长度掩码

返回:

result – 一个均值张量

返回类型:

torch.Tensor

speechbrain.utils.data_utils.masked_max(sample, mask=None)[source]

一个计算每个样本最小值的度量函数

参数:

sample (torch.Tensor) – 一个声谱图张量
mask (torch.Tensor) – 一个长度掩码

返回:

result – 一个均值张量

返回类型:

torch.Tensor

speechbrain.utils.data_utils.dist_stats(sample, mask=None)[source]

返回标准分布统计信息（均值、标准差、最小值、最大值）

参数:

sample (torch.Tensor) – 一个声谱图张量
mask (torch.Tensor) – 一个长度掩码

返回:

result – 一个均值张量

返回类型:

torch.Tensor

speechbrain.utils.data_utils.dict_value_combinations(values)[source]

返回给定字典中所有可能的键值组合

参数:

values (dict) –

一个以列表作为值的字典示例: {

”digit”: [1,2,3], “speaker”: [10, 20]

}

返回:

result – 一个字典列表，其中每个字典是可能的排列组合之一

返回类型:

list

speechbrain.utils.data_utils.dict_value_combinations_gen(values, keys)[source]

返回指定值字典的排列生成器

参数:

values (dict) –
一个以列表作为值的字典示例: {

”digit”: [1,2,3], “speaker”: [10, 20]

}
keys (list) – 要考虑的键

返回:

result – 一个字典生成器，其中每个字典是可能的排列组合之一

返回类型:

生成器