torchtext.data组件介绍(参考pytorch文档)

链接: https://torchtext.readthedocs.io/en/latest/data.html#

torchtext.data包含以下功能：

1. 能够定义预处理管道。
2. Batching, padding, and numericalizing(包括构建词汇表对象)。
3. 封装数据集分割(train, validation, test)。
4. 加载一个自定义的NLP数据集。

torchtext的组件

1. Dataset继承pytorch的Dataset，用于加载数据；Batch定义examples与其Fields的一个batch；Example定义一个单独的训练或测试example，将example中的每一列存储为一个属性。

① Dataset 类
class torchtext.data.Dataset (examples, fields, filter_pred=None)
定义由Examples及其Fields组成的数据集。

变量：
sort_key (callable) - 用于对数据集example进行排序的键，以便将长度相似的examples，batching在一起，以最小化padding。
example (list(Example)) - 数据集中的examples。
fields (dict[str, Field]) - 包含每列或field的名称，以及相应的Field object。具有相同Field object的两个fields将具有共享的词汇表。

函数
_ init _(examples, fields, filter_pred=None)
-从Examples和Fields的列表创建数据集。
参数：
examples - Examples列表
fields (List(tuple(str, Field)) - 这个元组中要使用的Fields。字符串是field名，Field是关联field。
filter_pred (callable or None) - 只使用filter_pred(example)为True的examples，如果为None，则使用所有examples。默认是没有的.。

过滤 函数
filter_examples (field_names)
从数据集examples中移除给定field的未知单词。
参数：
filter_pred (list(str)) - 在这个example中，只有field_names中的fields名，未知的单词会被删除。

分割函数
split (split_ratio=0.7, stratified=False, strata_field=‘label’, random_state=None)
从实例的examples中创建train-test(-valid?)splits。
参数：
split_ratio (float or List of python:floats) - 一个数字[0,1]，表示用于训练split的数据量(剩下的用于验证)，或者一个数字列表，分别表示训练、测试和有效splits的相对大小。如果缺少valid的相对大小，则只返回train-test split。默认值是0.7(对于训练集)。
stratified (bool) -采样是否分层。默认是False。
strata_field (str) - Examples Field的名称分层。默认为常规标签field的’label’。
random_state (tuple) - 用于shuffling的随机种子。random.getstate()的返回值。

TabularDataset 类
class torchtext.data.TabularDataset *(path, format, fields, skip_header=False, csv_reader_params={}, **kwargs)
可以指定路径，格式，Field信息就可以方便的完成数据加载。定义数据集的列存储在CSV、TSV或JSON格式中。

主函数
_ init _ *(path, format, fields, skip_header=False, csv_reader_params={}, **kwargs)

参数：
path (str) -数据文件路径。
format (str) -文件格式不区分大小写。
fields (list(tuple(str, Field)) - tuple(str, Field)]: 如果使用列表，格式必须是CSV或TSV，列表的值必须是(name, Field)的元组。fields应该与CSV或TSV文件中的列的顺序相同，而(name, None)的元组表示将被忽略的列；如果使用字典，keys应该是JSON键或CSV/TSV列的子集，值应该是(name，field)的元组。在输入字典中不存在的keys将被忽略。这允许用户给JSON/CSV/TSV键名重命名列，还允许选择要加载的列子集。
skip_header (str) - 是否跳过输入文件的第一行。。
csv_reader_params (tuple) - 传递给csv读取器的参数。仅当格式为csv或tsv时相关。

② Batch 类
class torchtext.data.Batch (data=None, dataset=None, device=None)
定义一个batch的examples及其Fields。

变量：
batch_size - batch中的examples数。
dataset - 对examples来自的dataset object的引用(包含 dataset 的Field objects)。
train - 弃用:为了向后兼容，这个属性被保留了下来，但是在与pytorch 0.4合并时它就不再使用了。
input_fields - 模型输入的fields名称。
target_fields - 在模型训练中用作目标的fields名称。

将batch中每个列的变量作为属性存储。

主函数
_ init _ (data=None, dataset=None, device=None)
从样例列表中创建一个batch

③ Example 类
class torchtext.data.Example
定义一个单独的训练或测试example，将样本中的每一列存储为一个属性。
classmethod fromCSV (data, fields, field_to_index=None) （这里只举一个CSV格式的例子）

2. Fields 定义数据类型以及转换为Tensor的命令。

Field类可以将(张量表示的公共文本处理数据类型)建模，它包含有一个Vocab对象，定义field元素及其相应的数值表示的可能值的集合。Field object还包含与数据类型应该如何数字化相关的参数，例如tokenization 方法和生成的Tensor类型。
如果一个Field在数据集的两列之间共享(例如，QA数据集中的question和answer)，那么它们将有一个共享的词汇表。

① Field 类
class torchtext.data.Field (sequential=True, use_vocab=True, init_token=None, eos_token=None, fix_length=None, dtype=torch.int64, preprocessing=None, postprocessing=None, lower=False, tokenize=None, tokenizer_language=‘en’, include_lengths=False, batch_first=False, pad_token=’’, unk_token=’’, pad_first=False, truncate_first=False, stop_words=None, is_target=False)

变量：
sequential - 是否把数据表示成序列，如果是False, 不能使用分词 默认值: True。
use_vocab - 是否使用Vocab object. 如果是False， field中的数据必须已经是数值类型. 默认值: True。
init_token - 每一条数据的起始字符 如果没有初始令牌则None，默认值: None。
eos_token - 每条数据的结尾字符 默认值: None。(同上)
fix_length - 每条数据的长度为该值，不够的用pad_token补全. 默认值: None。
dtype - torch.dtype 类 表示这类数据的一批样例，默认：torch.long。
preprocessing - 在分词之后和数值化之前使用的pipeline默认值: None。
postprocessing - 数值化之后和转化成tensor之前使用的pipline默认值: None。
lower - 是否把数据转化为小写 默认值: False。
tokenize - 分词函数，如果是spacy，则使用SpaCy tokenizer。如果一个非序列化函数作为参数传递，则该field将无法序列化 默认值: str.split。
tokenizer_language - 目前仅在SpaCy中支持各种语言。
**include_lengths ** - 是否返回一个已经补全的最小batch的元组和一个包含每条数据长度的列表 . 默认值: False。
batch_first - 是否先 生成batch尺寸的Tensor。默认值:False。。
pad_token - 用于补全的字符. 默认值: “”。
unk_token -不存在词典里的字符. 默认值: “”。
pad_first - 是否补全第一个字符. 默认值: False。
truncate_first - 在开始时填充序列。默认值:False。
stop_words - 要在预处理步骤中丢弃的tokens。默认值:False。
is_target - 此filed是否为目标变量。影响batch迭代，默认值:False。

主函数
_ init _ (sequential=True, use_vocab=True, init_token=None, eos_token=None, fix_length=None, dtype=torch.int64, preprocessing=None, postprocessing=None, lower=False, tokenize=None, tokenizer_language=‘en’, include_lengths=False, batch_first=False, pad_token=’’, unk_token=’’, pad_first=False, truncate_first=False, stop_words=None, is_target=False)

字典函数
build_vocab *(*args, **kwargs)
从一个或多个数据集为该field构造Vocab object。(构建字典)

参数：
arguments (Positional) -数据集对象或其他可迭代数据源，从中构造表示此field可能值集的Vocab object。如果提供了Dataset对象，则使用与该field对应的所有列;单个列也可以直接提供。
keyword arguments (Remaining)

数值化函数
numericalize (arr, device=None)
把文本数据数值化，返回tensor 。将一批使用该field的example转换为一个变量。如果field中include_length =True，则返回值中将包含一个长度tensor。

参数：
arr (List[List[str]], or tuple of (List[List[str]], List[int])) - 如果self.include_lengths is True。tokenized和padded的examples列表，或tokenized和padded的 examples列表元组，以及每个example的长度列表
device (str or torch.device) - torch.device的字符串或实例，指定变量将在哪个设备上创建。如果保留默认值，tensors将在cpu上创建。默认值:False。

pad 函数
pad (minibatch) 在一个batch对齐每条数据。
如果提供，则pad self.fix_length，否则为batch中最长example的长度pad。如果这些属性不是None，则追加self.init_token和self.eos_token。如果self.include_length和self.sequential为True，则返回填充列表的元组和包含每个example长度的列表，否则只返回填充列表。如果self.sequential为False，则不用填充。

3. Iterator 定义从数据集加载多个batchs数据的迭代器。

class torchtext.data.Iterator (dataset, batch_size, sort_key=None, device=None, batch_size_fn=None, train=True, repeat=False, shuffle=None, sort=None, sort_within_batch=None)

Iterator是torchtext到模型的输出，它提供了我们对数据的一般处理方式，比如打乱，排序，等等，可以动态修改batch大小，这里也有splits方法 可以同时输出训练集，验证集，测试集。

变量：
dataset - 数据集。
batch_size - batch大小。
batch_size_fn -产生动态的batch大小 的函数，有三个参数的函数(要添加的新example、batch中的当前examples数和当前有效batch大小)，返回将该example添加到batch中的新有效batch大小。
sort_key -排序的key( 用于对examples进行排序的key，以便将长度相似的examples batch在一起，并尽量减少padding。提供给迭代器构造函数的sort_key将覆盖数据集的sort_key属性，如果没有sort_key属性，则遵从它。)
train -是否是一个训练集。
repeat - 是否在不同epoch中重复迭代，默认值：False。
shuffle - 是否打乱数据。
**sort ** - 是否对数据进行排序。
sort_within_batch - 内部是否排序。
device (str or torch.device) - 建立batch的设备 ，-1表示CPU 。0,1 ,2,3…表示对应的GPU。