add mindrecord chn doc

This commit is contained in:
liyong 2022-02-14 18:03:41 +08:00
parent 66f15f1b1f
commit a59542f7cd
11 changed files with 588 additions and 3 deletions

View File

@ -0,0 +1,44 @@
.. py:class:: mindspore.mindrecord.Cifar100ToMR(source, destination)
将CIFAR-100数据集转换为MindRecord格式数据集的类。
.. note::
示例的详细信息,请参见 `转换CIFAR-10数据集 <https://mindspore.cn/docs/programming_guide/zh-CN/master/dataset_conversion.html#转换CIFAR-10数据集>`_
**参数:**
- **source** (str) - 待转换的CIFAR-100数据集文件的目录路径。
- **destination** (str) - 转换生成的MindRecord文件路径。
**异常:**
- **ValueError** - `source``destination` 无效。
.. py:method:: run(fields=None)
执行从CIFAR-100数据集到MindRecord格式数据集的转换。
**参数:**
- **fields** (list[str],可选) - 索引字段的列表,例如['fine_label', 'coarse_label']。默认值None。
索引字段的设置请参考函数 :func: `mindspore.mindrecord.FileWriter.add_index`
**返回:**
MSRStatusCIFAR-100数据集是否成功转换为MindRecord格式数据集。
.. py:method:: transform(fields=None)
:func: `mindspore.mindrecord.Cifar100ToMR.run` 函数的包装函数来保证异常时正常退出。
**参数:**
- **fields** (list[str],可选) - 索引字段的列表,例如['fine_label', 'coarse_label']。默认值None。
索引字段的设置请参考函数 :func: `mindspore.mindrecord.FileWriter.add_index`
**返回:**
MSRStatusCIFAR-100数据集是否成功转换为MindRecord格式数据集。

View File

@ -0,0 +1,45 @@
.. py:class:: mindspore.mindrecord.Cifar10ToMR(source, destination)
将CIFAR-10数据集转换为MindRecord格式数据集的类。
.. note::
示例的详细信息,请参见 `转换CIFAR-10数据集 <https://mindspore.cn/docs/programming_guide/zh-CN/master/dataset_conversion.html#转换CIFAR-10数据集>`_
**参数:**
- **source** (str) - 待转换的CIFAR-10数据集文件的目录路径。
- **destination** (str) - 转换生成的MindRecord文件路径。
**异常:**
- **ValueError** - `source``destination` 无效。
.. py:method:: run(fields=None)
执行从CIFAR-10数据集到MindRecord格式数据集的转换。
**参数:**
- **fields** (list[str],可选) - 索引字段的列表。默认值None。
索引字段的设置请参考函数 :func: `mindspore.mindrecord.FileWriter.add_index`
**返回:**
MSRStatusCIFAR-10数据集是否成功转换为MindRecord格式数据集。
.. py:method:: transform(fields=None)
:func: `mindspore.mindrecord.Cifar10ToMR.run` 函数的包装函数来保证异常时正常退出。
**参数:**
- **fields** (list[str],可选) - 索引字段的列表。默认值None。
索引字段的设置请参考函数 :func: `mindspore.mindrecord.FileWriter.add_index`
**返回:**
MSRStatusCIFAR-10数据集是否成功转换为MindRecord格式数据集。

View File

@ -0,0 +1,33 @@
.. py:class:: mindspore.mindrecord.CsvToMR(source, destination, columns_list=None, partition_number=1)
将CSV格式数据集转换为MindRecord格式数据集的类。
.. note::
示例的详细信息,请参见 `转换CSV数据集 <https://mindspore.cn/docs/programming_guide/zh-CN/master/dataset_conversion.html#转换CSV数据集>`_
**参数:**
- **source** (str) - 待转换的CSV文件路径。
- **destination** (str) - 转换生成的MindRecord文件路径。
- **columns_list** (list[str],可选) - CSV中待读取数据列的列表。默认值None读取所有的数据列。
- **partition_number** (int可选) - 生成MindRecord的文件个数。默认值1。
**异常:**
- **ValueError** - `source``destination``partition_number` 无效。
- **RuntimeError** - `columns_list` 无效。
.. py:method:: run()
执行从CSV格式数据集到MindRecord格式数据集的转换。
**返回:**
MSRStatusCSV数据集是否成功转换为MindRecord格式数据集。
.. py:method:: transform()
:func: `mindspore.mindrecord.CsvToMR.run` 函数的包装函数来保证异常时正常退出。

View File

@ -0,0 +1,37 @@
.. py:class:: mindspore.mindrecord.FileReader(file_name, num_consumer=4, columns=None, operator=None)
读取MindRecord格式数据集的类。
.. note::
- 如果 `file_name` 是文件名的字符串则会尝试加载同一批转换生成的所有MindRecord文件如果缺少其中某个MindRecord文件则会引发异常。
- 如果 `file_name` 是文件名的列表则只加载列表中指定的MindRecord文件。
**参数:**
- **file_name** (str, list[str]) - MindRecord格式的数据集文件或文件列表。
- **num_consumer** (int可选) - 加载数据的并发数。默认值4。不应小于1或大于处理器的核数。
- **columns** ((list[str],可选) - MindRecord中待读取数据列的列表。默认值None读取所有的数据列。
- **operator** (int可选) - 保留参数。默认值None。
**异常:**
- **ParamValueError** - `file_name``num_consumer``columns` 无效。
.. py:method:: close()
停止数据集加载并且关闭文件句柄。
.. py:method:: get_next()
按列名一次返回一个batch的数据。
**返回:**
Dictkey与数据列的列名相同的一个batch的数据。
**异常:**
- **MRMUnsupportedSchemaError** - schema无效。

View File

@ -0,0 +1,181 @@
.. py:class:: mindspore.mindrecord.FileWriter(file_name, shard_num=1)
将用户自定义的数据转为MindRecord格式数据集的类。
.. note::
生成MindRecord文件后如果修改文件名可能会导致读取文件失败。
**参数:**
- **file_name** (str) - 转换生成的MindRecord文件路径。
- **shard_num** (int可选) - 生成MindRecord的文件个数。默认值1。取值范围为[1, 1000]。
**异常:**
- **ParamValueError** - `file_name``shard_num` 无效。
.. py:method:: add_index(index_fields)
指定schema中的字段作为索引来加速MindRecord文件的读取。schema可以通过 `add_schema` 通过来添加。
.. note::
- 索引字段应为Primitive类型例如`int``float``str`
- 如果不调用该函数则默认将schema中所有的Primitive类型的字段设置为索引。
请参考类的示例:`mindspore.mindrecord.FileWriter`
**参数:**
- **index_fields** (list[str]) - schema中的字段。
**返回:**
MSRStatusSUCCESS或FAILED。
**异常:**
- **ParamTypeError** - 索引字段无效。
- **MRMDefineIndexError** - 索引字段不是Primitive类型。
- **MRMAddIndexError** - 无法添加索引字段。
- **MRMGetMetaError** - 未设置schema或无法获取schema。
.. py:method:: add_schema(content, desc=None)
增加描述用户自定义数据的schema。
.. note::
请参考类的示例:`mindspore.mindrecord.FileWriter`
**参数:**
- **content** (dict) - schema内容的字典。
- **desc** (str可选)) - schema的描述字符。默认值None。
**返回:**
intschema ID。
**异常:**
- **MRMInvalidSchemaError** - schema无效。
- **MRMBuildSchemaError** - 构建schema失败。
- **MRMAddSchemaError** - 添加schema失败。
.. py:method:: commit()
将内存中的数据同步到磁盘,并生成相应的数据库文件。
.. note::
请参考类的示例:`mindspore.mindrecord.FileWriter`
**返回:**
MSRStatusSUCCESS或FAILED。
**异常:**
- **MRMOpenError** - 打开MindRecord文件失败。
- **MRMSetHeaderError** - 设置MindRecord文件的header失败。
- **MRMIndexGeneratorError** - 创建索引Generator失败。
- **MRMGenerateIndexError** - 写入数据库失败。
- **MRMCommitError** - 数据同步到磁盘失败。
.. py:method:: open_and_set_header()
打开MindRecord文件准备写入并且设置header。该函数仅用于并行写入并在 `write_raw_data` 函数之前调用。
**返回:**
MSRStatusSUCCESS或FAILED。
**异常:**
- **MRMOpenError** - 打开MindRecord文件失败。
- **MRMSetHeaderError** - 设置MindRecord文件的header失败。
.. py:method:: open_for_append(file_name)
打开MindRecord文件准备追加数据。
**参数:**
- **file_name** (str) - MindRecord格式的数据集文件的路径。
**返回:**
FileWriterMindRecord文件的写对象。
**异常:**
- **ParamValueError** - `file_name` 无效。
- **FileNameError** - MindRecord文件路径中包含无效字符。
- **MRMOpenError** - 打开MindRecord文件失败。
- **MRMOpenForAppendError** - 打开MindRecord文件追加数据失败。
.. py:method:: set_header_size(header_size)
设置MindRecord文件的header其中包含shard信息、schema信息、page的元信息等。
header越大MindRecord文件可以存储更多的元信息。如果header大于默认大小16MB需要调用本函数来设置合适的大小。
**参数:**
- **header_size** (int) - header大小可设置范围为16*1024(16KB)和128*1024*1024(128MB)。
**返回:**
MSRStatusSUCCESS或FAILED。
**异常:**
- **MRMInvalidHeaderSizeError** - 设置header大小失败。
.. py:method:: set_page_size(page_size)
设置存储数据的page大小page分为两种类型raw page和blob page。
page越大page可以存储更多的数据。如果单个样本大于默认大小32MB需要调用本函数来设置合适的大小。
**参数:**
- **page_size** (int) - page大小可设置范围为32*1024(32KB)和256*1024*1024(256MB)。
**返回:**
MSRStatusSUCCESS或FAILED。
**异常:**
- **MRMInvalidPageSizeError** - 设置page大小失败。
.. py:method:: write_raw_data(raw_data, parallel_writer=False)
根据schema校验用户自定义数据后将数据转换为一系列连续的MindRecord格式的数据集文件。
.. note::
请参考类的示例:`mindspore.mindrecord.FileWriter`
**参数:**
- **raw_data** (list[dict]) - 用户自定义数据的列表。
- **parallel_writer** (bool可选) - 如果为True则并行写入用户自定义数据。默认值False。。
**返回:**
MSRStatusSUCCESS或FAILED。
**异常:**
- **ParamTypeError** - 索引字段无效。
- **MRMOpenError** - 打开MindRecord文件失败。
- **MRMValidateDataError** - 数据校验失败。
- **MRMSetHeaderError** - 设置MindRecord文件的header失败。
- **MRMWriteDatasetError** - 写入MindRecord格式的数据集失败。

View File

@ -0,0 +1,39 @@
.. py:class:: mindspore.mindrecord.ImageNetToMR(map_file, image_dir, destination, partition_number=1)
将ImageNet数据集转换为MindRecord格式数据集的类。
.. note::
示例的详细信息,请参见 `Converting the ImageNet Dataset <https:// www.mindspore.cn/docs/programming_guide/en/master/dataset_conversion.html#converting-the-imagenet-dataset>`_
**参数:**
- **map_file** (str) - 标签映射文件的路径。映射文件内容如下:
.. code-block::
n02119789 0
n02100735 1
n02110185 2
n02096294 3
- **image_dir** (str) - ImageNet数据集的目录路径目录中包含类似n02119789、n02100735、n02110185和n02096294的子目录。
- **destination** (str) - 转换生成的MindRecord文件路径
- **partition_number** (int可选) - 生成MindRecord的文件个数。默认值1。
**异常:**
- **ValueError** - `map_file``image_dir``destination` 无效。
.. py:method:: run()
执行从ImageNet数据集到MindRecord格式数据集的转换。
**返回:**
MSRStatusImageNet数据集是否成功转换为MindRecord格式数据集。
.. py:method:: transform()
:func: `mindspore.mindrecord.ImageNetToMR.run` 函数的包装函数来保证异常时正常退出。

View File

@ -0,0 +1,106 @@
.. py:class:: mindspore.mindrecord.MindPage(file_name, num_consumer=4)
以分页方式读取MindRecord文件的类。
**参数:**
- **file_name** (str) - MindRecord格式的数据集文件或文件列表。
- **num_consumer** (int可选) - 加载数据的并发数。默认值4。不应小于1或大于处理器的核数。
**异常:**
- **ParamValueError** - `file_name``num_consumer``columns` 无效。
- **MRMInitSegmentError** - 初始化ShardSegment失败。
.. :py:attr: candidate_fields
返回用于数据分组的候选category字段。
**返回:**
list[str]候选category 字段。
.. :py:attr: category_field
返回用于数据分组的category字段。
**返回:**
list[str]category字段。
.. py:method:: get_category_fields()
返回用于数据分组的候选category字段。
**返回:**
list[str]候选category字段。
.. py:method:: read_at_page_by_id(category_id, page, num_row)
以分页方式按category ID进行查询。
**参数:**
- **category_id** (int) - category ID参考`read_category_info`函数的返回值。
- **page** (int) - 分页的索引。
- **num_row** (int) - 每个分页的行数。
**返回:**
list[dict]根据category ID查询的数据。
**异常:**
- **ParamValueError** - 参数无效。
- **MRMFetchDataError** - 无法按category ID获取数据。
- **MRMUnsupportedSchemaError** - schema无效。
.. py:method:: read_at_page_by_name(category_name, page, num_row)
以分页方式按category字段进行查询。
**参数:**
- **category_name** (str) - category字段对应的字符参考`read_category_info`函数的返回值。
- **page** (int) - 分页的索引。
- **num_row** (int) - 每个分页的行数。
**返回:**
list[dict]根据category字段查询的数据。
.. py:method:: read_category_info()
当数据按指定的category字段进行分组时返回category信息。
**返回:**
str分组信息的描述。
**异常:**
- **MRMReadCategoryInfoError** - 读取category信息失败。
.. py:method:: set_category_field(category_field)
设置category字段。
.. note::
必须是候选category字段。
**参数:**
- **category_field** (str) - category字段名称。
**返回:**
MSRStatusSUCCESS或FAILED

View File

@ -0,0 +1,28 @@
.. py:class:: mindspore.mindrecord.MnistToMR(source, destination, partition_number=1)
将MNIST数据集转换为MindRecord格式数据集的类。
**参数:**
- **source** (str) - 包含t10k-images-idx3-ubyte.gz、train-images-idx3-ubyte.gz、t10k-labels-idx1-ubyte.gz和train-labels-idx1-ubyte.gz数据集文件的目录路径。
- **destination** (str) - 转换生成的MindRecord文件路径。
- **partition_number** (int可选) - 生成MindRecord的文件个数。默认值1。
**异常:**
- **ValueError** - `source``destination``partition_number` 无效。
.. py:method:: run()
执行从MNIST数据集到MindRecord格式数据集的转换。
**返回:**
MSRStatusMNIST数据集是否成功转换为MindRecord格式数据集。
.. py:method:: transform()
:func: `mindspore.mindrecord.MnistToMR.run` 函数的包装函数来保证异常时正常退出。

View File

@ -0,0 +1,51 @@
.. py:class:: mindspore.mindrecord.TFRecordToMR(source, destination, feature_dict, bytes_fields=None
将TFRecord格式数据集转换为MindRecord格式数据集的类。
.. note::
示例的详细信息,请参见 `转换TFRecord数据集 <https://mindspore.cn/docs/programming_guide/zh-CN/master/dataset_conversion.html#转换TFRecord数据集>`_
**参数:**
- **source** (str) - 待转换的TFRecord文件路径。
- **destination** (str) - 转换生成的MindRecord文件路径。
- **feature_dict** (dict) - TFRecord的feature类别的字典不支持`VarLenFeature`类别。
- **bytes_fields** (list可选) - `feature_dict` 中的字节字段,可以为字节类型的图像字段。
**异常:**
- **ValueError** - 无效参数。
- **Exception** - 找不到TensorFlow模块或其版本不正确。
.. py:method:: run()
执行从TFRecord格式数据集到MindRecord格式数据集的转换。
**返回:**
MSRStatusTFRecord格式的数据集是否成功转换为MindRecord格式数据集。
.. py:method:: tfrecord_iterator()
生成一个字典其key是schema中的字段value是数据。
**返回:**
Dictkey与schema中字段名相同的数据字典。
.. py:method:: tfrecord_iterator_oldversion()
生成一个字典其中key是schema中的字段value是数据。该函数适用于早于2.1.0版本的TensorFlow。
**返回:**
Dictkey与schema中字段名相同的数据字典。
.. py:method:: transform()
:func: `mindspore.mindrecord.TFRecordToMR.run` 函数的包装函数来保证异常时正常退出。

View File

@ -0,0 +1,5 @@
MindRecord是MindSpore开发的一种高效数据格式此模块提供了一些方法帮助用户将不同数据集转换为MindRecord格式
也提供了一些操作MindRecord数据文件的方法如读取、写入、检索等。
用户可以使用FileWriter API生成MindRecord格式数据集并使用MindDataset API加载MindRecord格式数据集。
用户还可以通过相应的子模块将其他格式数据集转换为MindRecord格式数据集。

View File

@ -1,9 +1,25 @@
mindspore.mindrecord
====================
Introduction of MindRecord.
.. include:: mindrecord/mindspore.mindrecord.rst
MindRecord is a module to implement reading, writing, searching and converting for MindSpore format dataset. Users could use the FileWriter API to generate MindRecord data and use the MindDataset API to load MindRecord data. Users could also convert other format datasets to mindrecord data through corresponding sub-module.
.. include:: mindrecord/mindspore.mindrecord.Cifar100ToMR.rst
.. include:: mindrecord/mindspore.mindrecord.Cifar10ToMR.rst
.. include:: mindrecord/mindspore.mindrecord.CsvToMR.rst
.. include:: mindrecord/mindspore.mindrecord.FileReader.rst
.. include:: mindrecord/mindspore.mindrecord.FileWriter.rst
.. include:: mindrecord/mindspore.mindrecord.ImageNetToMR.rst
.. include:: mindrecord/mindspore.mindrecord.MindPage.rst
.. include:: mindrecord/mindspore.mindrecord.MnistToMR.rst
.. include:: mindrecord/mindspore.mindrecord.TFRecordToMR.rst
.. automodule:: mindspore.mindrecord
:members:
:members: