diff --git a/docs/api/api_python/dataset/mindspore.dataset.CSVDataset.rst b/docs/api/api_python/dataset/mindspore.dataset.CSVDataset.rst new file mode 100644 index 00000000000..9fc511c67ff --- /dev/null +++ b/docs/api/api_python/dataset/mindspore.dataset.CSVDataset.rst @@ -0,0 +1,32 @@ +mindspore.dataset.CSVDataset +============================= + +Class mindspore.dataset.CSVDataset(dataset_files, field_delim=',', column_defaults=None, column_names=None, num_samples=None, num_parallel_workers=None, shuffle=, num_shards=None, shard_id=None, cache=None) + + 读取和解析逗号分隔值(CSV)数据文件作为源数据集。 + 生成的数据集的列取决于源CSV文件。 + + **参数:** + - **dataset_files** (Union[str, list[str]]):数据集文件路径,支持单文件路径字符串、多文件路径字符串列表或可被glob库模式匹配的字符串,文件列表将在内部进行字典排序。 + - **field_delim** (str,可选):指定用于分隔字段的分隔符(默认为',')。 + - **column_defaults** (list,可选):以列表形式指定每个CSV字段的数据类型(默认为None),有效的类型包括float、int或string。如果未指定该列表,则所有列的数据类型将被视为string。 + - **column_names** (list[str],可选):指定数据集生成的列名(默认值为None)。如果未指定该列表,则将CSV文件第一行的字段作为列名生成。 + - **num_samples** (int,可选):指定从数据集中读取的样本数(默认为None,即读取所有样本)。 + - **num_parallel_workers** (int,可选):指定读取数据的工作线程数(默认值None,即使用mindspore.dataset.config中配置的线程数)。 + - **shuffle** (Union[bool, Shuffle level], 可选):每个epoch中数据混洗的模式(默认为为mindspore.dataset.Shuffle.GLOBAL)。 + 如果为False,则不混洗;如果为True,等同于将`shuffle`设置为mindspore.dataset.Shuffle.GLOBAL。另外也可以传入枚举变量设置shuffle级别: + - Shuffle.GLOBAL:混洗文件和样本。 + - Shuffle.FILES:仅混洗文件。 + - **num_shards** (int, 可选):指定分布式训练时将数据集进行划分的分片数(默认值None)。指定此参数后, `num_samples` 表示每个分片的最大样本数。 + - **shard_id** (int, 可选):指定分布式训练时使用的分片ID号(默认值None)。只有当指定了 `num_shards` 时才能指定此参数。 + - **cache** (DatasetCache, 可选):数据缓存客户端实例,用于加快数据集处理速度(默认为None,不使用缓存)。 + + **异常:** + - **RuntimeError**:参数`dataset_files` 所指的文件无效或不存在。 + - **RuntimeError**:参数`num_parallel_workers` 超过系统最大线程数。 + - **RuntimeError**:指定了`num_shards`参数,但是未指定`shard_id`参数。 + - **RuntimeError**:指定了`shard_id`参数,但是未指定`num_shards`参数。 + + **样例:** + >>> csv_dataset_dir = ["/path/to/csv_dataset_file"] # 此列表可以包含1个或多个CSV文件 + >>> dataset = ds.CSVDataset(dataset_files=csv_dataset_dir, column_names=['col1', 'col2', 'col3', 'col4']) diff --git a/docs/api/api_python/dataset/mindspore.dataset.CelebADataset.rst b/docs/api/api_python/dataset/mindspore.dataset.CelebADataset.rst new file mode 100644 index 00000000000..538a41e9332 --- /dev/null +++ b/docs/api/api_python/dataset/mindspore.dataset.CelebADataset.rst @@ -0,0 +1,130 @@ +mindspore.dataset.CelebADataset +=============================== + +Class mindspore.dataset.CelebADataset(dataset_dir, num_parallel_workers=None, shuffle=None, usage='all', sampler=None, decode=False, extensions=None, num_samples=None, num_shards=None, shard_id=None, cache=None) + + 用于读取和解析CelebA数据集的源数据文件。 + 目前仅支持读取解析标注文件`list_attr_celeba.txt`作为数据集的标注。 + + 生成的数据集有两列::py:obj:`[image, attr]`。 + 列:py:obj:`image` 的数据类型为uint8。 + 列:py:obj:`attr` 的数据类型为uint32,并以one-hot编码的形式生成。 + + **参数:** + - **dataset_dir** (str):包含数据集文件的根目录路径。 + - **num_parallel_workers** (int,可选):指定读取数据的工作线程数(默认值None,即使用mindspore.dataset.config中配置的线程数)。 + - **shuffle** (bool,可选):是否混洗数据集(默认为None,下表中会展示不同配置的预期行为)。 + - **usage** (str,可选):指定数据集的子集,可取值为'train','valid','test'或'all'。(默认值为'all',即全部样本图片)。 + - **sampler** (Sampler,可选):指定从数据集中选取样本的采样器(默认为None,下表中会展示不同配置的预期行为)。 + - **decode** (bool,可选):是否对读取的图像进行解码操作(默认为False)。 + - **extensions** (list[str],可选):指定文件扩展后缀,仅读取这些后缀的文件到数据集中(默认为None)。 + - **num_samples** (int,可选):指定从数据集中读取的样本数(可以小于数据集总数,默认值为None,即全部样本图片)。 + - **num_shards** (int, 可选):指定分布式训练时将数据集进行划分的分片数(默认值None)。指定此参数后, `num_samples` 表示每个分片的最大样本数。 + - **shard_id** (int, 可选):指定分布式训练时使用的分片ID号(默认值None)。只有当指定了 `num_shards` 时才能指定此参数。 + - **cache** (DatasetCache, 可选):数据缓存客户端实例,用于加快数据集处理速度(默认为None,不使用缓存)。 + + **异常:** + - **RuntimeError**:参数`dataset_dir`不包含任何数据文件。 + - **RuntimeError**:参数`num_parallel_workers`超过系统最大线程数。 + - **RuntimeError**: 同时指定了`sampler`和`shuffle`。 + - **RuntimeError**: 同时指定了`sampler`和`num_shards`。 + - **RuntimeError**: 指定了`num_shards`参数,但是未指定`shard_id`参数。 + - **RuntimeError**: 指定了`shard_id`参数,但是未指定`num_shards`参数。 + - **ValueError**: `shard_id`参数错误(小于0或者大于等于 `num_shards`)。 + + **注:** + - 此数据集可以指定`sampler`参数,但`sampler` 和 `shuffle` 是互斥的。下表展示了几种合法的输入参数及预期的行为。 + + .. list-table:: 配置`sampler`和`shuffle`的不同组合得到的预期排序结果 + :widths: 25 25 50 + :header-rows: 1 + + * - 参数`sampler` + - 参数`shuffle` + - 预期数据顺序 + * - None + - None + - 随机排列 + * - None + - True + - 随机排列 + * - None + - False + - 顺序排列 + * - 参数`sampler` + - None + - 由`sampler`行为定义的顺序 + * - 参数`sampler` + - True + - 不允许 + * - 参数`sampler` + - False + - 不允许 + + **示例:** + >>> celeba_dataset_dir = "/path/to/celeba_dataset_directory" + >>> + >>> # 从CelebA数据集中随机读取5个样本图片 + >>> dataset = ds.CelebADataset(dataset_dir=celeba_dataset_dir, usage='train', num_samples=5) + >>> + >>> # 注:在生成的数据集对象中,每一次迭代得到的数据行都有"image"和"attr" 两个键 + + **关于CelebA数据集:** + + CelebFaces Attributes Dataset(CelebA)数据集是一个大规模的人脸属性数据集,拥有超过20万名人图像,每个图像都有40个属性标注。 + 此数据集包含了大量不同姿态、各种背景的人脸图像,种类丰富、数量庞大、标注充分。数据集总体包含: + * 10177个不同的身份 + * 202599张人脸图像 + * 每张图像拥有5个五官位置标注,40个属性标签。 + 此数据集可用于各种计算机视觉任务的训练和测试,包括人脸识别、人脸检测、五官定位、人脸编辑和合成等。 + + 原始CelebA数据集结构: + + .. code-block:: + + . + └── CelebA + ├── README.md + ├── Img + │ ├── img_celeba.7z + │ ├── img_align_celeba_png.7z + │ └── img_align_celeba.zip + ├── Eval + │ └── list_eval_partition.txt + └── Anno + ├── list_landmarks_celeba.txt + ├── list_landmarks_align_celeba.txt + ├── list_bbox_celeba.txt + ├── list_attr_celeba.txt + └── identity_CelebA.txt + + 您可以将数据集解压成如下的文件结构,并通过MindSpore的API进行读取。 + + .. code-block:: + + . + └── celeba_dataset_directory + ├── list_attr_celeba.txt + ├── 000001.jpg + ├── 000002.jpg + ├── 000003.jpg + ├── ... + + **引用:** + + .. code-block:: + + @article{DBLP:journals/corr/LiuLWT14, + author = {Ziwei Liu and Ping Luo and Xiaogang Wang and Xiaoou Tang}, + title = {Deep Learning Face Attributes in the Wild}, + journal = {CoRR}, + volume = {abs/1411.7766}, + year = {2014}, + url = {http://arxiv.org/abs/1411.7766}, + archivePrefix = {arXiv}, + eprint = {1411.7766}, + timestamp = {Tue, 10 Dec 2019 15:37:26 +0100}, + biburl = {https://dblp.org/rec/journals/corr/LiuLWT14.bib}, + bibsource = {dblp computer science bibliography, https://dblp.org}, + howpublished = {http://mmlab.ie.cuhk.edu.hk/projects/CelebA.html} + } diff --git a/docs/api/api_python/dataset/mindspore.dataset.CocoDataset.rst b/docs/api/api_python/dataset/mindspore.dataset.CocoDataset.rst new file mode 100644 index 00000000000..4acbc487190 --- /dev/null +++ b/docs/api/api_python/dataset/mindspore.dataset.CocoDataset.rst @@ -0,0 +1,150 @@ +mindspore.dataset.CocoDataset +============================== + +Class mindspore.dataset.CocoDataset(dataset_dir, annotation_file, task='Detection', num_samples=None, num_parallel_workers=None, shuffle=None, decode=False, sampler=None, num_shards=None, shard_id=None, cache=None, extra_metadata=False) + + 用于读取和解析COCO数据集的源数据文件。 + 该API支持解析COCO2017数据集,支持四种类型的机器学习任务,分别是目标检测、关键点检测、物体分割和全景分割。 + + 根据不同`task`参数设置,生成数据集具有不同的输出列: + - `task` = :py:obj:`Detection`, 输出列: :py:obj:`[image, dtype=uint8]`, :py:obj:`[bbox, dtype=float32]`, :py:obj:`[category_id, dtype=uint32]`, :py:obj:`[iscrowd, dtype=uint32]`. + - `task` = :py:obj:`Stuff`, 输出列: :py:obj:`[image, dtype=uint8]`, :py:obj:`[segmentation,dtype=float32]`, :py:obj:`[iscrowd,dtype=uint32]`. + - `task` = :py:obj:`Keypoint`, 输出列: :py:obj:`[image, dtype=uint8]`, :py:obj:`[keypoints, dtype=float32]`, :py:obj:`[num_keypoints, dtype=uint32]`. + - `task` = :py:obj:`Panoptic`, 输出列: :py:obj:`[image, dtype=uint8]`, :py:obj:`[bbox, dtype=float32]`, :py:obj:`[category_id, dtype=uint32]`, :py:obj:`[iscrowd, dtype=uint32]`, :py:obj:`[area, dtype=uint32]`. + + **参数:** + - **dataset_dir** (str):包含数据集文件的根目录路径。 + - **annotation_file** (str):数据集标注JSON文件的路径。 + - **task** (str,可选):指定COCO数据的任务类型。支持的任务类型包括:`Detection`、`Stuff`、`Panoptic`和`Keypoint`(默认为`Detection`)。 + - **num_samples** (int,可选):指定从数据集中读取的样本数(可以小于数据集总数,默认值为None,即全部样本图片)。 + - **num_parallel_workers** (int,可选):指定读取数据的工作线程数(默认值None,即使用mindspore.dataset.config中配置的线程数)。 + - **shuffle** (bool,可选):是否混洗数据集(默认为None,下表中会展示不同配置的预期行为)。 + - **decode** (bool,可选):是否对读取的图像进行解码操作(默认为False)。 + - **sampler** (Sampler,可选):指定从数据集中选取样本的采样器(默认为None,下表中会展示不同配置的预期行为)。 + - **num_shards** (int, 可选):指定分布式训练时将数据集进行划分的分片数(默认值None)。指定此参数后, `num_samples` 表示每个分片的最大样本数。 + - **shard_id** (int, 可选):指定分布式训练时使用的分片ID号(默认值None)。只有当指定了 `num_shards` 时才能指定此参数。 + - **cache** (DatasetCache, 可选):数据缓存客户端实例,用于加快数据集处理速度(默认为None,不使用缓存)。 + - **extra_metadata** (bool,可选):用于指定是否额外输出一列数据用于表示图像元信息。如果为True,则将额外输出一列数据,名为:py:obj:`[_meta-filename, dtype=string]` (默认值为False)。 + + **异常:** + - **RuntimeError**: 参数`dataset_dir`不包含任何数据文件。 + - **RuntimeError**: 参数`num_parallel_workers`超过系统最大线程数。 + - **RuntimeError**: 同时指定了`sampler`和`shuffle`。 + - **RuntimeError**: 同时指定了`sampler`和`num_shards`。 + - **RuntimeError**: 指定了`num_shards`参数,但是未指定`shard_id`参数。 + - **RuntimeError**: 指定了`shard_id`参数,但是未指定`num_shards`参数。 + - **RuntimeError**: 解析JSON文件失败。 + - **ValueError**: 指定的任务不为`Detection`,`Stuff`,`Panoptic`或`Keypoint`。 + - **ValueError**: 参数`annotation_file`对应的文件不存在。 + - **ValueError**: 参数`dataset_dir`路径不存在。 + - **ValueError**: 参数`shard_id`错误(小于0或者大于等于 `num_shards`)。 + + **注:** + - 当指定`extra_metadata`为True时,除非显式使用`rename`算子以删除元信息列明的前缀('_meta-'), + 否则迭代的数据行中不会出现'[_meta-filename, dtype=string]'列。 + - CocoDataset的`sampler`参数不支持指定PKSampler。 + - 此数据集可以指定`sampler`参数,但`sampler` 和 `shuffle` 是互斥的。下表展示了几种合法的输入参数及预期的行为。 + + .. list-table:: 配置`sampler`和`shuffle`的不同组合得到的预期排序结果 + :widths: 25 25 50 + :header-rows: 1 + + * - 参数`sampler` + - 参数`shuffle` + - 预期数据顺序 + * - None + - None + - 随机排列 + * - None + - True + - 随机排列 + * - None + - False + - 顺序排列 + * - 参数`sampler` + - None + - 由`sampler`行为定义的顺序 + * - 参数`sampler` + - True + - 不允许 + * - 参数`sampler` + - False + - 不允许 + + **样例:** + >>> coco_dataset_dir = "/path/to/coco_dataset_directory/images" + >>> coco_annotation_file = "/path/to/coco_dataset_directory/annotation_file" + >>> + >>> # 1)读取COCO数据集中`Detection`任务中的数据。 + >>> dataset = ds.CocoDataset(dataset_dir=coco_dataset_dir, + ... annotation_file=coco_annotation_file, + ... task='Detection') + >>> + >>> # 2)读取COCO数据集中`Stuff`任务中的数据。 + >>> dataset = ds.CocoDataset(dataset_dir=coco_dataset_dir, + ... annotation_file=coco_annotation_file, + ... task='Stuff') + >>> + >>> # 3)读取COCO数据集中`Panoptic`任务中的数据。 + >>> dataset = ds.CocoDataset(dataset_dir=coco_dataset_dir, + ... annotation_file=coco_annotation_file, + ... task='Panoptic') + >>> + >>> # 4)读取COCO数据集中`Keypoint`任务中的数据。 + >>> dataset = ds.CocoDataset(dataset_dir=coco_dataset_dir, + ... annotation_file=coco_annotation_file, + ... task='Keypoint') + >>> + >>> # 在生成的COCO数据集对象中,每一次迭代得到的数据行都有"image"和"annotation"两个键。 + + **关于COCO数据集:** + + Microsoft Common Objects in Context(COCO)是一个大型数据集,该数据集专门为目标检测,语义分割和字幕生成任务而设计。 + 它拥有330K张图像(标记数量大于200K个)、1500000个目标实例、80个目标类别、91个对象类别、每张图片均有5个字幕、带关键点标注的人有250000个。 + 与流行的ImageNet数据集相比,COCO的类别较少,但每个类别中的图片样本非常多。 + + 您可以解压缩原始COCO-2017数据集文件如下目录结构,并通过MindSpore的API读取。 + + .. code-block:: + + . + └── coco_dataset_directory + ├── train2017 + │ ├── 000000000009.jpg + │ ├── 000000000025.jpg + │ ├── ... + ├── test2017 + │ ├── 000000000001.jpg + │ ├── 000000058136.jpg + │ ├── ... + ├── val2017 + │ ├── 000000000139.jpg + │ ├── 000000057027.jpg + │ ├── ... + └── annotation + ├── captions_train2017.json + ├── captions_val2017.json + ├── instances_train2017.json + ├── instances_val2017.json + ├── person_keypoints_train2017.json + └── person_keypoints_val2017.json + + **引用:** + + .. code-block:: + + @article{DBLP:journals/corr/LinMBHPRDZ14, + author = {Tsung{-}Yi Lin and Michael Maire and Serge J. Belongie and + Lubomir D. Bourdev and Ross B. Girshick and James Hays and + Pietro Perona and Deva Ramanan and Piotr Doll{\'{a}}r and C. Lawrence Zitnick}, + title = {Microsoft {COCO:} Common Objects in Context}, + journal = {CoRR}, + volume = {abs/1405.0312}, + year = {2014}, + url = {http://arxiv.org/abs/1405.0312}, + archivePrefix = {arXiv}, + eprint = {1405.0312}, + timestamp = {Mon, 13 Aug 2018 16:48:13 +0200}, + biburl = {https://dblp.org/rec/journals/corr/LinMBHPRDZ14.bib}, + bibsource = {dblp computer science bibliography, https://dblp.org} + } diff --git a/docs/api/api_python/dataset/mindspore.dataset.Dataset.add_sampler.rst b/docs/api/api_python/dataset/mindspore.dataset.Dataset.add_sampler.rst new file mode 100644 index 00000000000..78451a0f59f --- /dev/null +++ b/docs/api/api_python/dataset/mindspore.dataset.Dataset.add_sampler.rst @@ -0,0 +1,13 @@ + ..py:method:: add_sampler(new_sampler) + + 为当前数据集添加采样器。 + + **参数:** + + **new_sampler** (Sampler) :作用于当前数据集的采样器。 + + 样例: + >>> # dataset为任意数据集实例 + >>> # 对该数据集应用DistributedSampler + >>> new_sampler = ds.DistributedSampler(10, 2) + >>> dataset.add_sampler(new_sampler) \ No newline at end of file diff --git a/docs/api/api_python/dataset/mindspore.dataset.Dataset.use_sampler.rst b/docs/api/api_python/dataset/mindspore.dataset.Dataset.use_sampler.rst new file mode 100644 index 00000000000..23db6278c93 --- /dev/null +++ b/docs/api/api_python/dataset/mindspore.dataset.Dataset.use_sampler.rst @@ -0,0 +1,13 @@ + ..py:method:: use_sampler(new_sampler) + + 为当前数据集更换一个新的采样器。 + + **参数:** + + **new_sampler** (Sampler) :替换的新采样器。 + + 样例: + >>> # dataset为任意数据集实例 + >>> # 将该数据集的采样器更换为DistributedSampler + >>> new_sampler = ds.DistributedSampler(10, 2) + >>> dataset.use_sampler(new_sampler) \ No newline at end of file diff --git a/docs/api/api_python/dataset/mindspore.dataset.GeneratorDataset.rst b/docs/api/api_python/dataset/mindspore.dataset.GeneratorDataset.rst new file mode 100644 index 00000000000..e6f2801c465 --- /dev/null +++ b/docs/api/api_python/dataset/mindspore.dataset.GeneratorDataset.rst @@ -0,0 +1,124 @@ +mindspore.dataset.GeneratorDataset +=================================== + +Class mindspore.dataset.GeneratorDataset(source, column_names=None, column_types=None, schema=None, num_samples=None, num_parallel_workers=1, shuffle=None, sampler=None, num_shards=None, shard_id=None, python_multiprocessing=True, max_rowsize=6) + + 通过调用Python数据源从Python中生成数据作为源数据集。 + 生成的数据集的列名和列类型取决于用户定义的Python数据源。 + + **参数:** + - **source** (Union[Callable, Iterable, Random Accessible]): + 一个Python的可调用对象,可以是一个可迭代的Python对象,或支持随机访问的Python对象。 + 要求传入的可调用对象,可以通过`source().next()`的方式返回一个由NumPy数组构成的元组。 + 要求传入的可迭代对象,可以通过`iter(source).next()`的方式返回一个由NumPy数组构成的元组。 + 要求传入的支持随机访问对象,可以通过`source[idx]`的方式返回一个由NumPy数组构成的元组。 + - **column_names** (Union[str, list[str]],可选):指定数据集生成的列名(默认值为None),用户必须提供此参数或通过参数`schema`指定列名。 + - **column_types** ((list[mindspore.dtype],可选):指定生成数据集各个数据列的数据类型(默认为None)。 + 如果未指定该参数,则自动推断类型;如果指定了该参数,将在数据输出时做类型匹配检查。 + - **schema** (Union[Schema, str],可选):读取模式策略,用于指定读取数据列的数据类型、数据维度等信息,支持传入JSON文件或`Schema`对象的路径。 + 对于数据集生成的列名,用户需要提供`column_names`或`schema`进行指定,如果同时指定两者,则将优先从`schema`获取列名信息。 + - **num_samples** (int,可选):指定从数据集中读取的样本数(默认为None)。 + - **num_parallel_workers** (int,可选):指定读取数据的工作线程数(默认值为1)。 + - **shuffle** (bool,可选):是否混洗数据集。只有输入的`source`参数带有可随机访问属性(__getitem__)时,才可以指定该参数。(默认值为None,下表中会展示不同配置的预期行为)。 + - **sampler** (Union[Sampler, Iterable],可选):指定从数据集中选取样本的采样器。只有输入的`source`参数带有可随机访问属性(__getitem__)时,才可以指定该参数(默认值为None,下表中会展示不同配置的预期行为)。 + - **num_shards** (int, 可选): 分布式训练时,将数据集划分成指定的分片数(默认值None)。指定此参数后,`num_samples` 表示每个分片的最大样本数。需要输入`data`支持可随机访问才能指定该参数。 + - **shard_id** (int, 可选): 分布式训练时,指定使用的分片ID号(默认值None)。只有当指定了 `num_shards` 时才能指定此参数。 + - **python_multiprocessing** (bool,可选):启用Python多进程模式加速运算(默认为True)。当传入Python对象的计算量很大时,开启此选项可能会有较好效果。 + - **max_rowsize** (int,可选):指定在多进程之间复制数据时,共享内存分配的最大空间(数量级为MB,默认为6MB),仅当参数`python_multiprocessing`设为True时,此参数才会生效。 + + **异常:** + - **RuntimeError**:Python对象`source`在执行期间引发异常。 + - **RuntimeError**:参数`column_names`指定的列名数量与`source`的输出数据数量不匹配。 + - **RuntimeError**:参数`num_parallel_workers`超过最大线程数。 + - **RuntimeError**: 同时指定了`sampler`和`shuffle`。 + - **RuntimeError**: 同时指定了`sampler`和`num_shards`。 + - **RuntimeError**: 指定了`num_shards`参数,但是未指定`shard_id`参数。 + - **RuntimeError**: 指定了`shard_id`参数,但是未指定`num_shards`参数。 + - **ValueError**: `shard_id`参数错误(小于0或者大于等于 `num_shards`)。 + + **注:** + - 此数据集可以指定`sampler`参数,但`sampler` 和 `shuffle` 是互斥的。下表展示了几种合法的输入参数及预期的行为。 + + .. list-table:: 配置`sampler`和`shuffle`的不同组合得到的预期排序结果 + :widths: 25 25 50 + :header-rows: 1 + + * - 参数`sampler` + - 参数`shuffle` + - 预期数据顺序 + * - None + - None + - 随机排列 + * - None + - True + - 随机排列 + * - None + - False + - 顺序排列 + * - 参数`sampler` + - None + - 由`sampler`行为定义的顺序 + * - 参数`sampler` + - True + - 不允许 + * - 参数`sampler` + - False + - 不允许 + + **样例:** + >>> import numpy as np + >>> + >>> # 1)定义一个Python生成器作为GeneratorDataset的可调用对象。 + >>> def generator_multidimensional(): + ... for i in range(64): + ... yield (np.array([[i, i + 1], [i + 2, i + 3]]),) + >>> + >>> dataset = ds.GeneratorDataset(source=generator_multidimensional, column_names=["multi_dimensional_data"]) + >>> + >>> # 2)定义一个Python生成器返回多列数据,作为GeneratorDataset的可调用对象。 + >>> def generator_multi_column(): + ... for i in range(64): + ... yield np.array([i]), np.array([[i, i + 1], [i + 2, i + 3]]) + >>> + >>> dataset = ds.GeneratorDataset(source=generator_multi_column, column_names=["col1", "col2"]) + >>> + >>> # 3)定义一个可迭代数据集对象,作为GeneratorDataset的可调用对象。 + >>> class MyIterable: + ... def __init__(self): + ... self._index = 0 + ... self._data = np.random.sample((5, 2)) + ... self._label = np.random.sample((5, 1)) + ... + ... def __next__(self): + ... if self._index >= len(self._data): + ... raise StopIteration + ... else: + ... item = (self._data[self._index], self._label[self._index]) + ... self._index += 1 + ... return item + ... + ... def __iter__(self): + ... self._index = 0 + ... return self + ... + ... def __len__(self): + ... return len(self._data) + >>> + >>> dataset = ds.GeneratorDataset(source=MyIterable(), column_names=["data", "label"]) + >>> + >>> # 4)定义一个支持随机访问数据集对象,作为GeneratorDataset的可调用对象。 + >>> class MyAccessible: + ... def __init__(self): + ... self._data = np.random.sample((5, 2)) + ... self._label = np.random.sample((5, 1)) + ... + ... def __getitem__(self, index): + ... return self._data[index], self._label[index] + ... + ... def __len__(self): + ... return len(self._data) + >>> + >>> dataset = ds.GeneratorDataset(source=MyAccessible(), column_names=["data", "label"]) + >>> + >>> # 注意,Python的list、dict、tuple也是支持随机可访问的,同样可以作为GeneratorDataset的输入 + >>> dataset = ds.GeneratorDataset(source=[(np.array(0),), (np.array(1),), (np.array(2),)], column_names=["col"]) diff --git a/docs/api/api_python/dataset/mindspore.dataset.ManifestDataset.rst b/docs/api/api_python/dataset/mindspore.dataset.ManifestDataset.rst new file mode 100644 index 00000000000..6acb3887546 --- /dev/null +++ b/docs/api/api_python/dataset/mindspore.dataset.ManifestDataset.rst @@ -0,0 +1,72 @@ +mindspore.dataset.ManifestDataset +================================== + +Class mindspore.dataset.ManifestDataset(dataset_file, usage='train', num_samples=None, num_parallel_workers=None, shuffle=None, sampler=None, class_indexing=None, decode=False, num_shards=None, shard_id=None, cache=None) + + 读取Manifest文件作为源数据集。 + + 生成的数据集有两列::py:obj:`[image, label]`。 + 列:py:obj:`image` 的数据类型为uint8类型。 + 列:py:obj:`label` 的数据类型是uint64类型的标量。 + + **参数:** + - **dataset_file** (str):数据集文件的目录路径。 + - **usage** (str,可选):指定数据集的子集,可取值为'train'、'eval'和'inference' (默认为'train')。 + - **num_samples** (int,可选):指定从数据集中读取的样本数(默认值为None,即全部样本图片)。 + - **num_parallel_workers** (int,可选):指定读取数据的工作线程数(默认值None,即使用mindspore.dataset.config中配置的线程数)。 + - **shuffle** (bool,可选):是否混洗数据集(默认为None,下表中会展示不同配置的预期行为)。 + - **sampler** (Sampler,可选):指定从数据集中选取样本的采样器(默认为None,下表中会展示不同配置的预期行为)。 + - **class_indexing** (dict,可选):指定文件夹名称到类标签的映射,要求映射规则为str到int(默认为None,文件夹名称将按字母顺序排列,每类都有一个唯一的索引,从0开始)。 + - **decode** (bool, 可选):是否对读取的图像进行解码操作(默认为False)。 + - **num_shards** (int, 可选): 分布式训练时,将数据集划分成指定的分片数(默认值None)。指定此参数后,`num_samples` 表示每个分片的最大样本数。 + - **shard_id** (int, 可选): 分布式训练时,指定使用的分片ID号(默认值None)。只有当指定了 `num_shards` 时才能指定此参数。 + - **cache** (DatasetCache, 可选):数据缓存客户端实例,用于加快数据集处理速度(默认为None,不使用缓存)。 + + **异常:** + - **RuntimeError**:参数`dataset_files`不存在或无效。 + - **RuntimeError**:参数`num_parallel_workers`超过系统最大线程数。 + - **RuntimeError**:同时指定了`sampler`和`shuffle`。 + - **RuntimeError**:同时指定了`sampler`和`num_shards`或`shard_id`。 + - **RuntimeError**: 指定了`num_shards`参数,但是未指定`shard_id`参数。 + - **RuntimeError**: 指定了`shard_id`参数,但是未指定`num_shards`参数。 + - **RuntimeError**:参数`class_indexing`的类型不是字典。 + - **ValueError**: `shard_id`参数错误(小于0或者大于等于 `num_shards`)。 + + **注:** + - 如果`decode`参数指定为False,则`image`列的shape为[image_size],否则为[H,W,C]。 + - 此数据集可以指定`sampler`参数,但`sampler` 和 `shuffle` 是互斥的。下表展示了几种合法的输入参数及预期的行为。 + + .. list-table:: 配置`sampler`和`shuffle`的不同组合得到的预期排序结果 + :widths: 25 25 50 + :header-rows: 1 + + * - 参数`sampler` + - 参数`shuffle` + - 预期数据顺序 + * - None + - None + - 随机排列 + * - None + - True + - 随机排列 + * - None + - False + - 顺序排列 + * - 参数`sampler` + - None + - 由`sampler`行为定义的顺序 + * - 参数`sampler` + - True + - 不允许 + * - 参数`sampler` + - False + - 不允许 + + **样例:** + >>> manifest_dataset_dir = "/path/to/manifest_dataset_file" + >>> + >>> # 1)使用八个线程读取Manifest数据集文件,并指定读取"train"子集数据 + >>> dataset = ds.ManifestDataset(dataset_file=manifest_dataset_dir, usage="train", num_parallel_workers=8) + >>> + >>> # 2) 对Manifest数据集进行分布式训练,并将数据集拆分为2个分片,当前数据集仅加载分片ID号为0的数据 + >>> dataset = ds.ManifestDataset(dataset_file=manifest_dataset_dir, num_shards=2, shard_id=0) diff --git a/docs/api/api_python/dataset/mindspore.dataset.MindDataset.rst b/docs/api/api_python/dataset/mindspore.dataset.MindDataset.rst new file mode 100644 index 00000000000..f5a39a7d836 --- /dev/null +++ b/docs/api/api_python/dataset/mindspore.dataset.MindDataset.rst @@ -0,0 +1,67 @@ +mindspore.dataset.MindDataset +============================== + +Class mindspore.dataset.MindDataset(dataset_file, columns_list=None, num_parallel_workers=None, shuffle=None, num_shards=None, shard_id=None, sampler=None, padded_sample=None, num_padded=None, num_samples=None, cache=None) + + 读取和解析MindRecord数据文件作为源数据集。 + 生成的数据集的列名和列类型取决于MindRecord文件中的保存的列名与类型。 + + **参数:** + - **dataset_file** (Union[str, list[str]]):MindRecord文件路径,支持单文件路径字符串、多文件路径字符串列表。 + 如果`dataset_file`的类型是字符串,则它代表一组具有相同前缀名的MindRecord文件,同一路径下具有相同前缀名的其他MindRecord文件将会被自动寻找并加载。 + 如果`dataset_file`的类型是列表,则它表示所需读取的MindRecord数据文件。 + - **columns_list** (list[str],可选):指定从MindRecord文件中读取的数据列(默认为None,读取所有列)。 + - **num_parallel_workers** (int,可选):指定读取数据的工作线程数(默认值None,即使用mindspore.dataset.config中配置的线程数)。 + - **shuffle** (Union[bool, Shuffle level], 可选):每个epoch中数据混洗的模式(默认为为mindspore.dataset.Shuffle.GLOBAL)。 + 如果为False,则不混洗;如果为True,等同于将`shuffle`设置为mindspore.dataset.Shuffle.GLOBAL。另外也可以传入枚举变量设置shuffle级别: + - Shuffle.GLOBAL:混洗文件和样本。 + - Shuffle.FILES:仅混洗文件。 + - Shuffle.INFILE:保持读入文件的序列,仅混洗每个文件中的数据。 + - **num_shards** (int, 可选): 分布式训练时,将数据集划分成指定的分片数(默认值None)。指定此参数后,`num_samples` 表示每个分片的最大样本数。 + - **shard_id** (int, 可选): 分布式训练时,指定使用的分片ID号(默认值None)。只有当指定了 `num_shards` 时才能指定此参数。 + - **sampler** (Sampler,可选):指定从数据集中选取样本的采样器(默认为None,下表中会展示不同配置的预期行为)。 + 当前此数据集仅支持以下采样器:SubsetRandomSampler、PkSampler、RandomSampler、SequentialSampler和DistributedSampler。 + - **padded_sample** (dict,可选): 指定额外添加到数据集的样本,可用于在分布式训练时补齐分片数据,注意字典的键名需要与column_list指定的列名相同。 + - **num_padded** (int,可选):指定额外添加的数据集样本的数量。在分布式训练时可用于为数据集补齐样本,使得总样本数量可被num_shards整除。 + - **num_samples** (int,可选):指定从数据集中读取的样本数(默认值为None,表示所有样本)。 + - **cache** (DatasetCache, 可选):数据缓存客户端实例,用于加快数据集处理速度(默认为None,不使用缓存)。 + + **异常:** + - **RuntimeError**:参数`dataset_files`无效或不存在。 + - **RuntimeError**:参数`num_parallel_workers`超过最大线程数。 + - **RuntimeError**:指定了`num_shards`,但`shard_id`为None。 + - **RuntimeError**:指定了`shard_id`,但`num_shards`为None。 + - **ValueError**: `shard_id`参数错误(小于0或者大于等于 `num_shards`)。 + + **注:** + - 此数据集可以指定`sampler`参数,但`sampler` 和 `shuffle` 是互斥的。下表展示了几种合法的输入参数及预期的行为。 + + .. list-table:: 配置`sampler`和`shuffle`的不同组合得到的预期排序结果 + :widths: 25 25 50 + :header-rows: 1 + + * - 参数`sampler` + - 参数`shuffle` + - 预期数据顺序 + * - None + - None + - 随机排列 + * - None + - True + - 随机排列 + * - None + - False + - 顺序排列 + * - 参数`sampler` + - None + - 由`sampler`行为定义的顺序 + * - 参数`sampler` + - True + - 不允许 + * - 参数`sampler` + - False + - 不允许 + + **样例:** + >>> mind_dataset_dir = ["/path/to/mind_dataset_file"] # 此列表可以包含1个或多个MindRecord文件 + >>> dataset = ds.MindDataset(dataset_file=mind_dataset_dir) diff --git a/docs/api/api_python/dataset/mindspore.dataset.TFRecordDataset.rst b/docs/api/api_python/dataset/mindspore.dataset.TFRecordDataset.rst new file mode 100644 index 00000000000..db0ade22e81 --- /dev/null +++ b/docs/api/api_python/dataset/mindspore.dataset.TFRecordDataset.rst @@ -0,0 +1,53 @@ +mindspore.dataset.TFRecordDataset +================================= + +Class mindspore.dataset.TFRecordDataset(dataset_files, schema=None, columns_list=None, num_samples=None, num_parallel_workers=None, shuffle=, num_shards=None, shard_id=None, shard_equal_rows=False, cache=None) + + 读取和解析以TFData格式存储的数据集文件作为源数据集。 + 生成的数据集的列名和列类型取决于TFRecord文件中的保存的列名与类型。 + + **参数:** + - **dataset_files** (Union[str, list[str]]):数据集文件路径,支持单文件路径字符串、多文件路径字符串列表或可被glob库模式匹配的字符串,文件列表将在内部进行字典排序。 + - **schema** (Union[str, Schema],可选):读取模式策略,用于指定读取数据列的数据类型、数据维度等信息。 + 支持传入JSON文件或`Schema`对象的路径(默认为None,将使用TFData文件中的元数据构造`Schema`对象)。 + - **columns_list** (list[str],可选):指定从TFRecord文件中读取的数据列(默认为None,读取所有列)。 + - **num_samples** (int,可选):指定从数据集中读取的样本数(默认为None)。 + 如果`num_samples`为None,并且numRows字段(由参数`schema`定义)不存在,则读取所有数据集; + 如果`num_samples`为None,并且numRows字段(由参数`schema`定义)的值大于0,则读取numRows条数据; + 如果`num_samples`和numRows字段(由参数`schema`定义)的值都大于0,仅有参数`num_samples`生效且读取给定数量的数据。 + - **num_parallel_workers** (int,可选):指定读取数据的工作线程数(默认值None,即使用mindspore.dataset.config中配置的线程数)。 + - **shuffle** (Union[bool, Shuffle level], 可选):每个epoch中数据混洗的模式(默认为为mindspore.dataset.Shuffle.GLOBAL)。 + 如果为False,则不混洗;如果为True,等同于将`shuffle`设置为mindspore.dataset.Shuffle.GLOBAL。另外也可以传入枚举变量设置shuffle级别: + - Shuffle.GLOBAL:混洗文件和样本。 + - Shuffle.FILES:仅混洗文件。 + - **num_shards** (int, 可选): 分布式训练时,将数据集划分成指定的分片数(默认值None)。指定此参数后,`num_samples` 表示每个分片的最大样本数。 + - **shard_id** (int, 可选): 分布式训练时,指定使用的分片ID号(默认值None)。只有当指定了 `num_shards` 时才能指定此参数。 + - **shard_equal_rows** (bool,可选): 分布式训练时,为所有分片获取等量的数据行数(默认为False)。 + 如果`shard_equal_rows`为False,则可能会使得每个分片的数据条目不相等,从而导致分布式训练失败。 + 因此当每个TFRecord文件的数据数量不相等时,建议将此参数设置为True。注意,只有当指定了 `num_shards` 时才能指定此参数。 + - **cache** (DatasetCache, 可选):数据缓存客户端实例,用于加快数据集处理速度(默认为None,不使用缓存)。 + + **异常:** + - **RuntimeError**:参数`dataset_files`无效或不存在。 + - **RuntimeError**:参数`num_parallel_workers`超过最大线程数。 + - **RuntimeError**:指定了`num_shards`,但`shard_id`为None。 + - **RuntimeError**:指定了`shard_id`,但`num_shards`为None。 + - **ValueError**:参数`shard_id`无效(小于0或者大于等于`num_shards`)。 + + **示例:** + >>> from mindspore import dtype as mstype + >>> + >>> tfrecord_dataset_dir = ["/path/to/tfrecord_dataset_file"] # 此列表可以包含1个或多个TFRecord文件 + >>> tfrecord_schema_file = "/path/to/tfrecord_schema_file" + >>> + >>> # 1) 从tfrecord_dataset_dir路径的文件读取数据集。 + >>> # 由于未指定Schema,则将TFRecord文件数据的第一行的元数据将用作Schema。 + >>> dataset = ds.TFRecordDataset(dataset_files=tfrecord_dataset_dir) + >>> + >>> # 2) 用户使用自定义的Schema从tfrecord_dataset_dir路径的文件读取数据集。 + >>> schema = ds.Schema() + >>> schema.add_column(name='col_1d', de_type=mstype.int64, shape=[2]) + >>> dataset = ds.TFRecordDataset(dataset_files=tfrecord_dataset_dir, schema=schema) + >>> + >>> # 3) 用户通过传入JSON文件构造Schema,从tfrecord_dataset_dir路径的文件读取数据集。 + >>> dataset = ds.TFRecordDataset(dataset_files=tfrecord_dataset_dir, schema=tfrecord_schema_file) diff --git a/docs/api/api_python/dataset/mindspore.dataset.TextFileDataset.rst b/docs/api/api_python/dataset/mindspore.dataset.TextFileDataset.rst new file mode 100644 index 00000000000..5fe09b67ca0 --- /dev/null +++ b/docs/api/api_python/dataset/mindspore.dataset.TextFileDataset.rst @@ -0,0 +1,29 @@ +mindspore.dataset.TextFileDataset +================================== + +Class mindspore.dataset.TextFileDataset(dataset_files, num_samples=None, num_parallel_workers=None, shuffle=, num_shards=None, shard_id=None, cache=None) + + 用于读取和解析文本格式的文件作为源数据集。 + 生成的数据集有一个数据列:py:obj:`[text]`,类型为string。 + + **参数:** + - **dataset_files** (Union[str, list[str]]):数据集文件路径,支持单文件路径字符串、多文件路径字符串列表或可被glob库模式匹配的字符串,文件列表将在内部进行字典排序。 + - **num_samples** (int,可选):指定从数据集中读取的样本数(默认为None,即读取所有样本)。 + - **num_parallel_workers** (int,可选):指定读取数据的工作线程数(默认值None,即使用mindspore.dataset.config中配置的线程数)。 + - **shuffle** (Union[bool, Shuffle level], 可选):每个epoch中数据混洗的模式(默认为为mindspore.dataset.Shuffle.GLOBAL)。 + 如果为False,则不混洗;如果为True,等同于将`shuffle`设置为mindspore.dataset.Shuffle.GLOBAL。另外也可以传入枚举变量设置shuffle级别: + - Shuffle.GLOBAL:混洗文件和样本。 + - Shuffle.FILES:仅混洗文件。 + - **num_shards** (int, 可选):指定分布式训练时将数据集进行划分的分片数(默认值None)。指定此参数后, `num_samples` 表示每个分片的最大样本数。 + - **shard_id** (int, 可选):指定分布式训练时使用的分片ID号(默认值None)。只有当指定了 `num_shards` 时才能指定此参数。 + - **cache** (DatasetCache, 可选):数据缓存客户端实例,用于加快数据集处理速度(默认为None,不使用缓存)。 + + **异常:** + - **RuntimeError**:`dataset_files` 所指的文件无效或不存在。 + - **RuntimeError**:`num_parallel_workers` 超过系统最大线程数。 + - **RuntimeError**:指定了`num_shards`参数,但是未指定`shard_id`参数。 + - **RuntimeError**:指定了`shard_id`参数,但是未指定`num_shards`参数。 + + **样例:** + >>> text_file_dataset_dir = ["/path/to/text_file_dataset_file"] # # 此列表可以包含1个或多个文本文件 + >>> dataset = ds.TextFileDataset(dataset_files=text_file_dataset_dir) diff --git a/docs/api/api_python/dataset/mindspore.dataset.rst b/docs/api/api_python/dataset/mindspore.dataset.rst new file mode 100644 index 00000000000..a4c397f1699 --- /dev/null +++ b/docs/api/api_python/dataset/mindspore.dataset.rst @@ -0,0 +1,18 @@ +mindspore.dataset + +该模块提供了加载和处理各种通用数据集的API,如MNIST、CIFAR-10、CIFAR-100、VOC、COCO、ImageNet、CelebA、CLUE等, +也支持加载业界标准格式的数据集,包括MindRecord、TFRecord、Manifest等。此外,用户还可以使用此模块定义和加载自己的数据集。 + +该模块还提供了在加载时进行数据采样的API,如SequentialSample、RandomSampler、DistributedSampler等。 + +大多数数据集可以通过指定参数`cache`启用缓存服务,以提升整体数据处理效率。 +请注意Windows平台上还不支持缓存服务,因此在Windows上加载和处理数据时,请勿使用。更多介绍和限制, +请参考`Single-Node Tensor Cache `_。 + + +在API示例中,常用的模块导入方法如下: + +.. code-block:: + + import mindspore.dataset as ds + from mindspore.dataset.transforms import c_transforms diff --git a/mindspore/dataset/engine/datasets.py b/mindspore/dataset/engine/datasets.py index 1cc68ff44ea..f9f97c30171 100644 --- a/mindspore/dataset/engine/datasets.py +++ b/mindspore/dataset/engine/datasets.py @@ -1745,8 +1745,8 @@ class Dataset: >>> import numpy as np >>> >>> def generator1(): - >>> for i in range(1, 100): - >>> yield np.ones((16, i, 83)), np.array(i) + ... for i in range(1, 100): + ... yield np.ones((16, i, 83)), np.array(i) >>> >>> dataset = ds.GeneratorDataset(generator1, ["data1", "data2"]) >>> dataset.set_dynamic_columns(columns={"data1": [16, None, 83], "data2": []}) @@ -1767,8 +1767,8 @@ class Dataset: >>> import numpy as np >>> >>> def generator1(): - >>> for i in range(1, 100): - >>> yield np.ones((16, i, 83)), np.array(i) + ... for i in range(1, 100): + ... yield np.ones((16, i, 83)), np.array(i) >>> >>> dataset = ds.GeneratorDataset(generator1, ["data1", "data2"]) >>> dataset.set_dynamic_columns(columns={"data1": [16, None, 83], "data2": []}) @@ -5799,6 +5799,7 @@ class Schema: RuntimeError: If column's type field is missing. Examples: + >>> from mindspore.dataset import Schema >>> schema = Schema() >>> columns1 = [{'name': 'image', 'type': 'int8', 'shape': [3, 3]}, >>> {'name': 'label', 'type': 'int8', 'shape': [1]}] @@ -6126,7 +6127,7 @@ class VOCDataset(MappableDataset): Examples: >>> voc_dataset_dir = "/path/to/voc_dataset_directory" >>> - >>> dataset = ds.VOCDataset(dataset_dir=voc_dataset_dir) + >>> dataset = ds.VOCDataset(dataset_dir=voc_dataset_dir, task="Detection") >>> class_indexing = dataset.get_class_indexing() """ if self.task != "Detection":