From 319c67df14a740813a87fc3ce2af89792a5d532a Mon Sep 17 00:00:00 2001 From: yingchen Date: Sat, 27 Nov 2021 16:09:05 +0800 Subject: [PATCH] update api format --- .../mindspore.dataset.ImageFolderDataset.rst | 94 +++++++------ .../mindspore.dataset.MnistDataset.rst | 10 +- .../mindspore.dataset.NumpySlicesDataset.rst | 95 ++++++------- .../dataset/mindspore.dataset.PKSampler.rst | 46 ++++--- .../mindspore.dataset.PaddedDataset.rst | 27 ++-- .../mindspore.dataset.RandomSampler.rst | 34 +++-- .../dataset/mindspore.dataset.Schema.rst | 106 ++++++++------- .../mindspore.dataset.SequentialSampler.rst | 36 +++-- .../mindspore.dataset.SubsetRandomSampler.rst | 34 +++-- .../mindspore.dataset.SubsetSampler.rst | 38 +++--- .../dataset/mindspore.dataset.VOCDataset.rst | 128 +++++++++--------- .../mindspore.dataset.WaitedDSCallback.rst | 4 +- ...indspore.dataset.WeightedRandomSampler.rst | 44 +++--- 13 files changed, 380 insertions(+), 316 deletions(-) diff --git a/docs/api/api_python/dataset/mindspore.dataset.ImageFolderDataset.rst b/docs/api/api_python/dataset/mindspore.dataset.ImageFolderDataset.rst index 8ba625fa0dd..3c233af66dc 100644 --- a/docs/api/api_python/dataset/mindspore.dataset.ImageFolderDataset.rst +++ b/docs/api/api_python/dataset/mindspore.dataset.ImageFolderDataset.rst @@ -1,42 +1,47 @@ -Class mindspore.dataset.ImageFolderDataset(dataset_dir, num_samples=None, num_parallel_workers=None, shuffle=None, sampler=None, extensions=None, class_indexing=None, decode=False, num_shards=None, shard_id=None, cache=None) +mindspore.dataset.ImageFolderDataset +===================================== + +.. py:class:: mindspore.dataset.ImageFolderDataset(dataset_dir, num_samples=None, num_parallel_workers=None, shuffle=None, sampler=None, extensions=None, class_indexing=None, decode=False, num_shards=None, shard_id=None, cache=None) 从树状结构的文件目录中读取图像作为源数据集，同一个文件夹中的所有图像都具有相同的标签。 生成的数据集有两列： :py:obj:`[image, label]`。列:py:obj:`image` 的数据为uint8类型，列:py:obj:`label` 的数据是uint32类型的标量。 **参数：** - - **dataset_dir** (str)：包含数据集文件的根目录的路径。 - - **num_samples** (int, 可选): 指定从数据集中读取的样本数（可以小于数据集总数，默认值为None，即全部样本图片）。 - - **num_parallel_workers** (int, 可选): 指定读取数据的工作线程数（默认值None，即使用mindspore.dataset.config中配置的线程数）。 - - **shuffle** (bool, 可选): 是否混洗数据集（默认为None，下表中会展示不同配置的预期行为）。 - - **sampler** (Sampler, 可选): 指定从数据集中选取样本的采样器（默认为None，下表中会展示不同配置的预期行为）。 - - **extensions** (list[str], 可选)：指定文件扩展后缀，仅读取这些后续的文件到数据集中（默认为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, 即不使用缓存加速）。 + + - **dataset_dir** (str)：包含数据集文件的根目录的路径。 + - **num_samples** (int, 可选): 指定从数据集中读取的样本数（可以小于数据集总数，默认值为None，即全部样本图片）。 + - **num_parallel_workers** (int, 可选): 指定读取数据的工作线程数（默认值None，即使用 `mindspore.dataset.config` 中配置的线程数）。 + - **shuffle** (bool, 可选): 是否混洗数据集（默认为None，下表中会展示不同配置的预期行为）。 + - **sampler** (Sampler, 可选): 指定从数据集中选取样本的采样器（默认为None，下表中会展示不同配置的预期行为）。 + - **extensions** (list[str], 可选)：指定文件扩展后缀，仅读取这些后续的文件到数据集中（默认为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_dir不包含任何数据文件。 - - **RuntimeError**：num_parallel_workers超过系统最大线程数。 - - **RuntimeError**：同时指定了采样器和shuffle。 - - **RuntimeError**：同时指定了采样器和分片。 - - **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` 是互斥的。下表展示了几种合法的输入参数及预期的行为。 + - **RuntimeError**：`dataset_dir` 不包含任何数据文件。 + - **RuntimeError**：`num_parallel_workers` 超过系统最大线程数。 + - **RuntimeError**：同时指定了采样器和 `shuffle` 。 + - **RuntimeError**：同时指定了采样器和分片。 + - **RuntimeError**: 指定了 `num_shards` 参数，但是未指定 `shard_id` 参数。 + - **RuntimeError**: 指定了 `shard_id` 参数，但是未指定 `num_shards` 参数。 + - **RuntimeError**：`class_indexing` 的类型不是字典。 + - **ValueError**: `shard_id` 参数错误（小于0或者大于等于 `num_shards`）。 - .. list-table:: 配置`sampler`和`shuffle`的不同组合得到的预期排序结果 + .. note:: + - 如果 `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` + * - 参数 `sampler` + - 参数 `shuffle` - 预期数据顺序 * - None - None @@ -47,30 +52,31 @@ Class mindspore.dataset.ImageFolderDataset(dataset_dir, num_samples=None, num_pa * - None - False - 顺序排列 - * - 参数`sampler` + * - 参数 `sampler` - None - - 由`sampler`行为定义的顺序 - * - 参数`sampler` + - 由 `sampler` 行为定义的顺序 + * - 参数 `sampler` - True - 不允许 - * - 参数`sampler` + * - 参数 `sampler` - False - 不允许 - **示例：** - >>> image_folder_dataset_dir = "/path/to/image_folder_dataset_directory" - >>> - >>> # 1）使用8个线程读取image_folder_dataset_dir中的所有图像文件。 - >>> dataset = ds.ImageFolderDataset(dataset_dir=image_folder_dataset_dir, - ... num_parallel_workers=8) - >>> - >>> # 2）从标签为0和1的cat文件夹为和dog文件夹中读取所有图像文件。 - >>> dataset = ds.ImageFolderDataset(dataset_dir=image_folder_dataset_dir, - ... class_indexing={"cat":0, "dog":1}) - >>> - >>> # 3）读取image_folder_dataset_dir中所有扩展名为.JPEG和.png（区分大小写）的图像文件。 - >>> dataset = ds.ImageFolderDataset(dataset_dir=image_folder_dataset_dir, - ... extensions=[".JPEG", ".png"]) + **样例：** + + >>> image_folder_dataset_dir = "/path/to/image_folder_dataset_directory" + >>> + >>> # 1）使用8个线程读取image_folder_dataset_dir中的所有图像文件。 + >>> dataset = ds.ImageFolderDataset(dataset_dir=image_folder_dataset_dir, + ... num_parallel_workers=8) + >>> + >>> # 2）从标签为0和1的cat文件夹为和dog文件夹中读取所有图像文件。 + >>> dataset = ds.ImageFolderDataset(dataset_dir=image_folder_dataset_dir, + ... class_indexing={"cat":0, "dog":1}) + >>> + >>> # 3）读取image_folder_dataset_dir中所有扩展名为.JPEG和.png（区分大小写）的图像文件。 + >>> dataset = ds.ImageFolderDataset(dataset_dir=image_folder_dataset_dir, + ... extensions=[".JPEG", ".png"]) **关于ImageFolderDataset：** diff --git a/docs/api/api_python/dataset/mindspore.dataset.MnistDataset.rst b/docs/api/api_python/dataset/mindspore.dataset.MnistDataset.rst index a22e14e5b79..263fbfe5177 100644 --- a/docs/api/api_python/dataset/mindspore.dataset.MnistDataset.rst +++ b/docs/api/api_python/dataset/mindspore.dataset.MnistDataset.rst @@ -23,11 +23,11 @@ mindspore.dataset.MnistDataset - **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`）。 + - **RuntimeError**: 同时指定了 `sampler` 和 `shuffle` 参数。 + - **RuntimeError**: 同时指定了 `sampler` 和 `num_shards` 参数。 + - **RuntimeError**: 指定了 `num_shards` 参数，但是未指定 `shard_id` 参数。 + - **RuntimeError**: 指定了 `shard_id` 参数，但是未指定`num_shards` 参数。 + - **ValueError**: `shard_id` 参数错误（小于0或者大于等于 `num_shards` ）。 .. note:: 此数据集可以指定 `sampler` 参数，但 `sampler` 和 `shuffle` 是互斥的。下表展示了几种合法的输入参数及预期的行为。 diff --git a/docs/api/api_python/dataset/mindspore.dataset.NumpySlicesDataset.rst b/docs/api/api_python/dataset/mindspore.dataset.NumpySlicesDataset.rst index b6374aa8cf0..85e832b6c87 100644 --- a/docs/api/api_python/dataset/mindspore.dataset.NumpySlicesDataset.rst +++ b/docs/api/api_python/dataset/mindspore.dataset.NumpySlicesDataset.rst @@ -1,30 +1,29 @@ -Class mindspore.dataset.NumpySlicesDataset(data, column_names=None, num_samples=None, num_parallel_workers=1, shuffle=None, sampler=None, num_shards=None, shard_id=None) +mindspore.dataset.NumpySlicesDataset +===================================== - 由Python数据构建源数据集。 - 生成的数据集的列名和列类型取决于用户传入的Python数据。 +.. py:class:: mindspore.dataset.NumpySlicesDataset(data, column_names=None, num_samples=None, num_parallel_workers=1, shuffle=None, sampler=None, num_shards=None, shard_id=None) + + 由Python数据构建源数据集。生成的数据集的列名和列类型取决于用户传入的Python数据。 **参数：** - - **data** (Union[list, tuple, dict])：输入的Python数据。支持的数据类型包括：list、tuple、dict和其他NumPy格式。 - 输入数据将沿着第一个维度切片，并生成额外的行。如果输入是单个list，则将生成一个数据列，若是嵌套多个list，则生成多个数据列。 - 不建议通过这种方式加载大量的数据，因为可能会在数据加载到内存时等待较长时间。 - - **column_names** (list[str], 可选): 指定数据集生成的列名（默认值为None）。 - 如果未指定列名称，且当输入数据的类型是dict时，输出列名称将被命名为dict的键名，否则它们将被命名为column_0，column_1...。 - - **num_samples** (int, 可选): 指定从数据集中读取的样本数（默认值为None，所有样本）。 - - **num_parallel_workers** (int, 可选): 指定读取数据的工作线程数（默认值为1）。 - - **shuffle** (bool, 可选): 是否混洗数据集。只有输入的`data`参数带有可随机访问属性（__getitem__）时，才可以指定该参数。（默认值为None，下表中会展示不同配置的预期行为）。 - - **sampler** (Union[Sampler, Iterable], 可选): 指定从数据集中选取样本的采样器。只有输入的`data`参数带有可随机访问属性（__getitem__）时，才可以指定该参数（默认值为None，下表中会展示不同配置的预期行为）。 - - **num_shards** (int, 可选): 分布式训练时，将数据集划分成指定的分片数（默认值None）。指定此参数后，`num_samples` 表示每个分片的最大样本数。需要输入`data`支持可随机访问才能指定该参数。 - - **shard_id** (int, 可选): 分布式训练时，指定使用的分片ID号（默认值None）。只有当指定了 `num_shards` 时才能指定此参数。 - **注：** - - 此数据集可以指定`sampler`参数，但`sampler` 和 `shuffle` 是互斥的。下表展示了几种合法的输入参数及预期的行为。 + - **data** (Union[list, tuple, dict])：输入的Python数据。支持的数据类型包括：list、tuple、dict和其他NumPy格式。输入数据将沿着第一个维度切片，并生成额外的行。如果输入是单个list，则将生成一个数据列，若是嵌套多个list，则生成多个数据列。不建议通过这种方式加载大量的数据，因为可能会在数据加载到内存时等待较长时间。 + - **column_names** (list[str], 可选): 指定数据集生成的列名（默认值为None）。如果未指定列名称，且当输入数据的类型是dict时，输出列名称将被命名为dict的键名，否则它们将被命名为column_0，column_1...。 + - **num_samples** (int, 可选): 指定从数据集中读取的样本数（默认值为None，所有样本）。 + - **num_parallel_workers** (int, 可选): 指定读取数据的工作线程数（默认值为1）。 + - **shuffle** (bool, 可选): 是否混洗数据集。只有输入的 `data` 参数带有可随机访问属性（__getitem__）时，才可以指定该参数。（默认值为None，下表中会展示不同配置的预期行为）。 + - **sampler** (Union[Sampler, Iterable], 可选): 指定从数据集中选取样本的采样器。只有输入的 `data` 参数带有可随机访问属性（__getitem__）时，才可以指定该参数（默认值为None，下表中会展示不同配置的预期行为）。 + - **num_shards** (int, 可选): 分布式训练时，将数据集划分成指定的分片数（默认值None）。指定此参数后，`num_samples` 表示每个分片的最大样本数。需要输入 `data` 支持可随机访问才能指定该参数。 + - **shard_id** (int, 可选): 分布式训练时，指定使用的分片ID号（默认值None）。只有当指定了 `num_shards` 时才能指定此参数。 - .. list-table:: 配置`sampler`和`shuffle`的不同组合得到的预期排序结果 + .. note:: 此数据集可以指定 `sampler` 参数，但 `sampler` 和 `shuffle` 是互斥的。下表展示了几种合法的输入参数及预期的行为。 + + .. list-table:: 配置 `sampler` 和 `shuffle` 的不同组合得到的预期排序结果 :widths: 25 25 50 :header-rows: 1 - * - 参数`sampler` - - 参数`shuffle` + * - 参数 `sampler` + - 参数 `shuffle` - 预期数据顺序 * - None - None @@ -35,39 +34,41 @@ Class mindspore.dataset.NumpySlicesDataset(data, column_names=None, num_samples= * - None - False - 顺序排列 - * - 参数`sampler` + * - 参数 `sampler` - None - - 由`sampler`行为定义的顺序 - * - 参数`sampler` + - 由 `sampler` 行为定义的顺序 + * - 参数 `sampler` - True - 不允许 - * - 参数`sampler` + * - 参数 `sampler` - False - 不允许 **异常：** - - **RuntimeError**: column_names列表的长度与数据的输出列表长度不匹配。 - - **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`）。 - **示例：** - >>> # 1) 输入的`data`参数类型为list - >>> data = [1, 2, 3] - >>> dataset = ds.NumpySlicesDataset(data=data, column_names=["column_1"]) - >>> - >>> # 2) 输入的`data`参数类型为dict，并且使用column_names的默认行为，即采用键名作为生成列名。 - >>> data = {"a": [1, 2], "b": [3, 4]} - >>> dataset = ds.NumpySlicesDataset(data=data) - >>> - >>> # 3) 输入的`data`参数类型是由list组成的tuple（或NumPy数组），每个元组分别生成一个输出列，共三个输出列 - >>> data = ([1, 2], [3, 4], [5, 6]) - >>> dataset = ds.NumpySlicesDataset(data=data, column_names=["column_1", "column_2", "column_3"]) - >>> - >>> # 4) 从CSV文件加载数据 - >>> import pandas as pd - >>> df = pd.read_csv(filepath_or_buffer=csv_dataset_dir[0]) - >>> dataset = ds.NumpySlicesDataset(data=dict(df), shuffle=False) + - **RuntimeError**: `column_names` 列表的长度与数据的输出列表长度不匹配。 + - **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` ）。 + + **样例：** + + >>> # 1) 输入的`data`参数类型为list + >>> data = [1, 2, 3] + >>> dataset = ds.NumpySlicesDataset(data=data, column_names=["column_1"]) + >>> + >>> # 2) 输入的`data`参数类型为dict，并且使用column_names的默认行为，即采用键名作为生成列名。 + >>> data = {"a": [1, 2], "b": [3, 4]} + >>> dataset = ds.NumpySlicesDataset(data=data) + >>> + >>> # 3) 输入的`data`参数类型是由list组成的tuple（或NumPy数组），每个元组分别生成一个输出列，共三个输出列 + >>> data = ([1, 2], [3, 4], [5, 6]) + >>> dataset = ds.NumpySlicesDataset(data=data, column_names=["column_1", "column_2", "column_3"]) + >>> + >>> # 4) 从CSV文件加载数据 + >>> import pandas as pd + >>> df = pd.read_csv(filepath_or_buffer=csv_dataset_dir[0]) + >>> dataset = ds.NumpySlicesDataset(data=dict(df), shuffle=False) diff --git a/docs/api/api_python/dataset/mindspore.dataset.PKSampler.rst b/docs/api/api_python/dataset/mindspore.dataset.PKSampler.rst index 161eccbc27e..9c2a08b9fce 100644 --- a/docs/api/api_python/dataset/mindspore.dataset.PKSampler.rst +++ b/docs/api/api_python/dataset/mindspore.dataset.PKSampler.rst @@ -1,27 +1,33 @@ -Class mindspore.dataset.PKSampler(num_val, num_class=None, shuffle=False, class_column='label', num_samples=None) +mindspore.dataset.PKSampler +============================== + +.. py:class:: mindspore.dataset.PKSampler(num_val, num_class=None, shuffle=False, class_column='label', num_samples=None) 为数据集中的每个P类采样K个元素。 - 参数： - num_val (int): 每个类要采样的元素数量。 - num_class (int, optional): 要采样的类数量（默认值为None，采样所有类）。当前不支持指定该参数。 - shuffle (bool, optional): 如果为True，则class ID将被打乱，否则它将不会被打乱（默认值为False）。 - class_column (str, optional): 具有MindDataset类标签的列的名称（默认值'label'）。 - num_samples (int, optional): 要采样的样本数（默认值为None，对所有元素进行采样）。 + **参数：** - 示例： - >>> # 创建一个PKSampler，从每个类中获取3个样本。 - >>> sampler = ds.PKSampler(3) - >>> dataset = ds.ImageFolderDataset(image_folder_dataset_dir, - ... num_parallel_workers=8, - ... sampler=sampler) + - **num_val** (int): 每个类要采样的元素数量。 + - **num_class** (int, optional): 要采样的类数量（默认值为None，采样所有类）。当前不支持指定该参数。 + - **shuffle** (bool, optional): 如果为True，则class ID将被打乱，否则它将不会被打乱（默认值为False）。 + - **class_column** (str, optional): 具有MindDataset类标签的列的名称（默认值'label'）。 + - **num_samples** (int, optional): 要采样的样本数（默认值为None，对所有元素进行采样）。 - 异常： - TypeError：shuffle不是bool值。 - TypeError：class_column不是str值。 - TypeError：num_samples不是整数值。 - NotImplementedError: num_class不为None。 - RuntimeError: num_val不是正值。 - ValueError：num_samples为负值。 + **样例：** + + >>> # 创建一个PKSampler，从每个类中获取3个样本。 + >>> sampler = ds.PKSampler(3) + >>> dataset = ds.ImageFolderDataset(image_folder_dataset_dir, + ... num_parallel_workers=8, + ... sampler=sampler) + + **异常：** + + - **TypeError：** `shuffle` 不是bool值。 + - **TypeError：** `class_column` 不是str值。 + - **TypeError：** `num_samples` 不是整数值。 + - **NotImplementedError:** `num_class` 不为None。 + - **RuntimeError:** `num_val` 不是正值。 + - **ValueError：** `num_samples` 为负值。 .. include:: mindspore.dataset.BuiltinSampler.rst \ No newline at end of file diff --git a/docs/api/api_python/dataset/mindspore.dataset.PaddedDataset.rst b/docs/api/api_python/dataset/mindspore.dataset.PaddedDataset.rst index f365a62bcd0..f1606b76bee 100644 --- a/docs/api/api_python/dataset/mindspore.dataset.PaddedDataset.rst +++ b/docs/api/api_python/dataset/mindspore.dataset.PaddedDataset.rst @@ -1,17 +1,22 @@ -Class mindspore.dataset.PaddedDataset(padded_samples) +mindspore.dataset.PaddedDataset +================================ - 使用用户提供的填充数据创建数据集。 - 可用于在分布式训练时给原始数据集添加样本，使数据集能平均分配给不同的分片。 +.. py:class:: mindspore.dataset.PaddedDataset(padded_samples) + + 使用用户提供的填充数据创建数据集。可用于在分布式训练时给原始数据集添加样本，使数据集能平均分配给不同的分片。 **参数：** - - **padded_samples** (list(dict)): 用户提供的样本数据。 + + **padded_samples** (list(dict)): 用户提供的样本数据。 **异常：** - - **TypeError**：padded_samples的类型不为list。 - - **TypeError**：padded_samples的元素类型不为dict。 - - **ValueError**：padded_samples为空列表。 - **示例：** - >>> import numpy as np - >>> data = [{'image': np.zeros(1, np.uint8)}, {'image': np.zeros(2, np.uint8)}] - >>> dataset = ds.PaddedDataset(padded_samples=data) + - **TypeError**：`padded_samples` 的类型不为list。 + - **TypeError**：`padded_samples` 的元素类型不为dict。 + - **ValueError**：`padded_samples` 为空列表。 + + **样例：** + + >>> import numpy as np + >>> data = [{'image': np.zeros(1, np.uint8)}, {'image': np.zeros(2, np.uint8)}] + >>> dataset = ds.PaddedDataset(padded_samples=data) diff --git a/docs/api/api_python/dataset/mindspore.dataset.RandomSampler.rst b/docs/api/api_python/dataset/mindspore.dataset.RandomSampler.rst index 7bd045e746a..27b94393e4f 100644 --- a/docs/api/api_python/dataset/mindspore.dataset.RandomSampler.rst +++ b/docs/api/api_python/dataset/mindspore.dataset.RandomSampler.rst @@ -1,21 +1,27 @@ -Class mindspore.dataset.RandomSampler(replacement=False, num_samples=None) +mindspore.dataset.RandomSampler +================================ + +.. py:class:: mindspore.dataset.RandomSampler(replacement=False, num_samples=None) 随机采样器。 - 参数： - replacement (bool, optional): 如果为True，则将样本ID放回下一次采样（默认值为False）。 - num_samples (int, optional): 要采样的元素数量（默认值为None，采样所有元素）。 + **参数：** - 示例： - >>> # 创建一个RandomSampler - >>> sampler = ds.RandomSampler() - >>> dataset = ds.ImageFolderDataset(image_folder_dataset_dir, - ... num_parallel_workers=8, - ... sampler=sampler) + - **replacement** (bool, optional): 如果为True，则将样本ID放回下一次采样（默认值为False）。 + - **num_samples** (int, optional): 要采样的元素数量（默认值为None，采样所有元素）。 - 异常： - TypeError：replacement不是bool值。 - TypeError：num_samples不是整数值。 - ValueError：num_samples为负值。 + **样例：** + + >>> # 创建一个RandomSampler + >>> sampler = ds.RandomSampler() + >>> dataset = ds.ImageFolderDataset(image_folder_dataset_dir, + ... num_parallel_workers=8, + ... sampler=sampler) + + **异常：** + + - **TypeError：** `replacement` 不是bool值。 + - **TypeError：** `num_samples` 不是整数值。 + - **ValueError：** `num_samples` 为负值。 .. include:: mindspore.dataset.BuiltinSampler.rst \ No newline at end of file diff --git a/docs/api/api_python/dataset/mindspore.dataset.Schema.rst b/docs/api/api_python/dataset/mindspore.dataset.Schema.rst index 83b5166ed89..2a020311202 100644 --- a/docs/api/api_python/dataset/mindspore.dataset.Schema.rst +++ b/docs/api/api_python/dataset/mindspore.dataset.Schema.rst @@ -1,79 +1,93 @@ -Class mindspore.dataset.Schema(schema_file=None) +mindspore.dataset.Schema +========================= + +.. py:class:: mindspore.dataset.Schema(schema_file=None) 代表一个解析和存储数据列属性的类。 - 参数： - schema_file(str): schema文件的路径（默认值为None）。 + **参数：** - 返回： - schema对象，关于数据集的行列配置的策略信息。 + **schema_file** (str): schema文件的路径（默认值为None）。 - 异常： - RuntimeError: 模式文件加载失败。 + **返回：** - 示例： - >>> from mindspore import dtype as mstype - >>> - >>> # 创建模式；指定列名、mindspore.dtype和列shape。 - >>> schema = ds.Schema() - >>> schema.add_column(name='col1', de_type=mstype.int64, shape=[2]) + schema对象，关于数据集的行列配置的策略信息。 + + **异常：** + + **RuntimeError:** 模式文件加载失败。 + + **样例：** + + >>> from mindspore import dtype as mstype + >>> + >>> # 创建模式；指定列名、mindspore.dtype和列shape。 + >>> schema = ds.Schema() + >>> schema.add_column(name='col1', de_type=mstype.int64, shape=[2]) -add_column(name, de_type, shape=None) + .. py:method::add_column(name, de_type, shape=None) 向schema中添加新列。 - 参数： - name (str): 列的新名称。 - de_type (str): 列的数据类型。 - shape (list[int], optional): 列shape（默认值为None，[-1]表示rank 1的未知shape）。 + **参数：** - 异常： - ValueError：列类型未知。 + - **name** (str): 列的新名称。 + - **de_type** (str): 列的数据类型。 + - **shape** (list[int], optional): 列shape（默认值为None，[-1]表示rank 1的未知shape）。 + + **异常：** + + **ValueError：** 列类型未知。 -from_json(json_obj) + .. py:method::from_json(json_obj) 从JSON对象获取schema文件。 - 参数： - json_obj(dictionary): 解析的JSON对象。 + **参数：** - 异常： - RuntimeError：对象中存在未知的项。 - RuntimeError：对象中缺少数据集类型。 - RuntimeError：对象中缺少列。 + **json_obj** (dictionary): 解析的JSON对象。 + + **异常：** + + - **RuntimeError：** 对象中存在未知的项。 + - **RuntimeError：** 对象中缺少数据集类型。 + - **RuntimeError：** 对象中缺少列。 -parse_columns(columns) + .. py:method::parse_columns(columns) 解析传入的数据列的属性并将其添加到自身的schema中。 - 参数： - columns (Union[dict, list[dict], tuple[dict]]): 数据集属性信息，从schema文件解码。 + **参数：** - - list[dict]，'name'和'type'必须为key值，'shape'可选。 + - **columns** (Union[dict, list[dict], tuple[dict]]): 数据集属性信息，从schema文件解码。 - - dict，columns.keys()作为名称，columns.values()是dict，其中包含'type'，'shape'可选。 + - list[dict]，'name'和'type'必须为key值，'shape'可选。 + - dict，columns.keys()作为名称，columns.values()是dict，其中包含'type'，'shape'可选。 - 异常： - RuntimeError: 解析列失败。 - RuntimeError: 列name字段缺失。 - RuntimeError: 列type字段缺失。 + **异常：** - 示例： - >>> schema = Schema() - >>> columns1 = [{'name': 'image', 'type': 'int8', 'shape': [3, 3]}, - >>> {'name': 'label', 'type': 'int8', 'shape': [1]}] - >>> schema.parse_columns(columns1) - >>> columns2 = {'image': {'shape': [3, 3], 'type': 'int8'}, 'label': {'shape': [1], 'type': 'int8'}} - >>> schema.parse_columns(columns2) + - **RuntimeError:** 解析列失败。 + - **RuntimeError:** 列name字段缺失。 + - **RuntimeError:** 列type字段缺失。 + + **样例：** + + >>> schema = Schema() + >>> columns1 = [{'name': 'image', 'type': 'int8', 'shape': [3, 3]}, + >>> {'name': 'label', 'type': 'int8', 'shape': [1]}] + >>> schema.parse_columns(columns1) + >>> columns2 = {'image': {'shape': [3, 3], 'type': 'int8'}, 'label': {'shape': [1], 'type': 'int8'}} + >>> schema.parse_columns(columns2) -to_json() + .. py:method::to_json() 获取schema的JSON字符串。 - 返回： - str，模式的JSON字符串。 + **返回：** + + str，模式的JSON字符串。 \ No newline at end of file diff --git a/docs/api/api_python/dataset/mindspore.dataset.SequentialSampler.rst b/docs/api/api_python/dataset/mindspore.dataset.SequentialSampler.rst index 168a2d220ba..3f054f4a27d 100644 --- a/docs/api/api_python/dataset/mindspore.dataset.SequentialSampler.rst +++ b/docs/api/api_python/dataset/mindspore.dataset.SequentialSampler.rst @@ -1,22 +1,28 @@ -Class mindspore.dataset.SequentialSampler(start_index=None, num_samples=None) +mindspore.dataset.SequentialSampler +=================================== + +.. py:class:: mindspore.dataset.SequentialSampler(start_index=None, num_samples=None) 按顺序采样数据集元素，相当于不使用采样器。 - 参数： - start_index (int, optional): 开始采样的索引。（默认值为None，从第一个ID开始） - num_samples (int, optional): 要采样的元素数量。（默认值为None，采样所有元素） + **参数：** - 示例： - >>> # 创建SequentialSampler - >>> sampler = ds.SequentialSampler() - >>> dataset = ds.ImageFolderDataset(image_folder_dataset_dir, - ... num_parallel_workers=8, - ... sampler=sampler) + - **start_index** (int, optional): 开始采样的索引。（默认值为None，从第一个ID开始） + - **num_samples** (int, optional): 要采样的元素数量。（默认值为None，采样所有元素） - 异常： - TypeError：start_index不是整数值。 - TypeError：num_samples不是整数值。 - RuntimeError: start_index为负值。 - ValueError：num_samples为负值。 + *样例：** + + >>> # 创建SequentialSampler + >>> sampler = ds.SequentialSampler() + >>> dataset = ds.ImageFolderDataset(image_folder_dataset_dir, + ... num_parallel_workers=8, + ... sampler=sampler) + + **异常：** + + - **TypeError：** `start_index` 不是整数值。 + - **TypeError：** `num_samples` 不是整数值。 + - **RuntimeError:** `start_index` 为负值。 + - **ValueError：** `num_samples` 为负值。 .. include:: mindspore.dataset.BuiltinSampler.rst \ No newline at end of file diff --git a/docs/api/api_python/dataset/mindspore.dataset.SubsetRandomSampler.rst b/docs/api/api_python/dataset/mindspore.dataset.SubsetRandomSampler.rst index c6b190329dc..985a4c52000 100644 --- a/docs/api/api_python/dataset/mindspore.dataset.SubsetRandomSampler.rst +++ b/docs/api/api_python/dataset/mindspore.dataset.SubsetRandomSampler.rst @@ -1,21 +1,27 @@ -Class mindspore.dataset.SubsetRandomSampler(indices, num_samples=None) +mindspore.dataset.SequentialSampler +==================================== + +.. py:class:: mindspore.dataset.SubsetRandomSampler(indices, num_samples=None) 对索引序列中的元素进行随机采样。 - 参数： - indices (Any iterable Python object but string): 索引的序列。 - num_samples (int, optional): 要采样的元素数量（默认值为None，采样所有元素）。 + **参数：** - 示例： - >>> indices = [0, 1, 2, 3, 7, 88, 119] - >>> - >>> # 创建一个SubsetRandomSampler，从提供的索引中采样 - >>> sampler = ds.SubsetRandomSampler(indices) - >>> data = ds.ImageFolderDataset(image_folder_dataset_dir, num_parallel_workers=8, sampler=sampler) + - **indices** (Any iterable Python object but string): 索引的序列。 + - **num_samples** (int, optional): 要采样的元素数量（默认值为None，采样所有元素）。 - 异常： - TypeError：indices的类型不是数字。 - TypeError：num_samples不是整数值。 - ValueError：num_samples为负值。 + **样例：** + + >>> indices = [0, 1, 2, 3, 7, 88, 119] + >>> + >>> # 创建一个SubsetRandomSampler，从提供的索引中采样 + >>> sampler = ds.SubsetRandomSampler(indices) + >>> data = ds.ImageFolderDataset(image_folder_dataset_dir, num_parallel_workers=8, sampler=sampler) + + **异常：** + + - **TypeError：** `indices` 的类型不是数字。 + - **TypeError：** `num_samples` 不是整数值。 + - **ValueError：** `num_samples` 为负值。 .. include:: mindspore.dataset.BuiltinSampler.rst \ No newline at end of file diff --git a/docs/api/api_python/dataset/mindspore.dataset.SubsetSampler.rst b/docs/api/api_python/dataset/mindspore.dataset.SubsetSampler.rst index b77c6931f09..98a095878fd 100644 --- a/docs/api/api_python/dataset/mindspore.dataset.SubsetSampler.rst +++ b/docs/api/api_python/dataset/mindspore.dataset.SubsetSampler.rst @@ -1,23 +1,29 @@ -Class mindspore.dataset.SubsetSampler(indices, num_samples=None) +mindspore.dataset.SequentialSampler +==================================== + +.. py:class:: mindspore.dataset.SubsetSampler(indices, num_samples=None) 对索引序列中的元素进行采样。 - 参数： - indices (Any iterable Python object but string): 索引的序列。 - num_samples (int, optional): 要采样的元素数量（默认值为None，采样所有元素）。 + **参数：** - 示例： - >>> indices = [0, 1, 2, 3, 4, 5] - >>> - >>> # 创建SubsetSampler，从提供的索引采样 - >>> sampler = ds.SubsetSampler(indices) - >>> dataset = ds.ImageFolderDataset(image_folder_dataset_dir, - ... num_parallel_workers=8, - ... sampler=sampler) + - **indices** (Any iterable Python object but string): 索引的序列。 + - **num_samples** (int, optional): 要采样的元素数量（默认值为None，采样所有元素）。 - 异常： - TypeError：索引元素的类型不是数字。 - TypeError：num_samples不是整数值。 - ValueError：num_samples为负值。 + **样例：** + + >>> indices = [0, 1, 2, 3, 4, 5] + >>> + >>> # 创建SubsetSampler，从提供的索引采样 + >>> sampler = ds.SubsetSampler(indices) + >>> dataset = ds.ImageFolderDataset(image_folder_dataset_dir, + ... num_parallel_workers=8, + ... sampler=sampler) + + **异常：** + + - **TypeError：** 索引元素的类型不是数字。 + - **TypeError：** `num_samples` 不是整数值。 + - **ValueError：** `num_samples` 为负值。 .. include:: mindspore.dataset.BuiltinSampler.rst \ No newline at end of file diff --git a/docs/api/api_python/dataset/mindspore.dataset.VOCDataset.rst b/docs/api/api_python/dataset/mindspore.dataset.VOCDataset.rst index c7ca42b579e..47c4002c348 100644 --- a/docs/api/api_python/dataset/mindspore.dataset.VOCDataset.rst +++ b/docs/api/api_python/dataset/mindspore.dataset.VOCDataset.rst @@ -1,58 +1,59 @@ -Class mindspore.dataset.VOCDataset(dataset_dir, task='Segmentation', usage='train', class_indexing=None, num_samples=None, num_parallel_workers=None, shuffle=None, decode=False, sampler=None, num_shards=None, shard_id=None, cache=None, extra_metadata=False) +mindspore.dataset.VOCDataset +============================= + +.. py:class:: mindspore.dataset.VOCDataset(dataset_dir, task='Segmentation', usage='train', class_indexing=None, num_samples=None, num_parallel_workers=None, shuffle=None, decode=False, sampler=None, num_shards=None, shard_id=None, cache=None, extra_metadata=False) 用于读取和解析VOC数据集的源数据集文件。 根据给定的task配置，数据集会生成不同的输出列： - - task = :py:obj:`Detection`，输出列：:py:obj:`[image, dtype=uint8]`, :py:obj:`[bbox, dtype=float32]`, :py:obj:`[label, dtype=uint32]`, :py:obj:`[difficult, dtype=uint32]`, :py:obj:`[truncate, dtype=uint32]`。 - - task = :py:obj:`Segmentation`，输出列： :py:obj:`[image, dtype=uint8]`, :py:obj:`[target,dtype=uint8]`。 + - task = `Detection`，输出列： `[image, dtype=uint8]`, `[bbox, dtype=float32]`, `[label, dtype=uint32]`, `[difficult, dtype=uint32]`, `[truncate, dtype=uint32]`。 + - task = `Segmentation`，输出列： `[image, dtype=uint8]`, `[target,dtype=uint8]`。 **参数：** - - **dataset_dir** (str): 包含数据集文件的根目录的路径。 - - **task** (str, 可选): 指定读取VOC数据的任务类型，现在只支持`Segmentation`或`Detection`（默认值`Segmentation`）。 - - **usage** (str, 可选): 指定数据集的子集（默认值`train`）。 - 如果`task`参数为`Segmentation`，则将在./ImageSets/Segmentation/usage + ".txt"中加载数据集图像和标注信息； - 如果`task`参数为`Detection`，则将在./ImageSets/Main/usage + ".txt"中加载数据集图像和标注信息； - 如果未设置任务和用法，默认将加载./ImageSets/Segmentation/train.txt中的数据集图像和标注信息。 - - **class_indexing** (dict, 可选): 指定标签名称到类标签的映射，要求映射规则为str到int， - 仅在`Detection`任务中有效（默认值None，文件夹名称将按字母顺序排列，每类都有一个唯一的索引，从0开始)。 - - **num_samples** (int, 可选): 指定从数据集中读取的样本数（默认值为None，所有图像样本）。 - - **num_parallel_workers** (int, 可选): 指定读取数据的工作线程数（默认值None，即使用mindspore.dataset.config中配置的线程数）。 - - **shuffle** (bool, 可选): 是否混洗数据集（默认为None，下表中会展示不同配置的预期行为）。 - - **decode** (bool, 可选): 是否对读取的图像进行解码操作（默认值为False）。s - - **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）。 + + - **dataset_dir** (str): 包含数据集文件的根目录的路径。 + - **task** (str, 可选): 指定读取VOC数据的任务类型，现在只支持 `Segmentation` 或 `Detection` （默认值 `Segmentation` ）。 + - **usage** (str, 可选): 指定数据集的子集（默认值 `train` ）。如果 `task` 参数为 `Segmentation` ，则将在./ImageSets/Segmentation/usage + ".txt"中加载数据集图像和标注信息；如果 `task` 参数为 `Detection` ，则将在./ImageSets/Main/usage + ".txt"中加载数据集图像和标注信息；如果未设置任务和用法，默认将加载./ImageSets/Segmentation/train.txt中的数据集图像和标注信息。 + - **class_indexing** (dict, 可选): 指定标签名称到类标签的映射，要求映射规则为str到int， + 仅在`Detection`任务中有效（默认值None，文件夹名称将按字母顺序排列，每类都有一个唯一的索引，从0开始)。 + - **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，则将额外输出一列数据，名为 `[_meta-filename, dtype=string]` （默认值为False）。 **异常：** - - **RuntimeError**: dataset_dir不包含任何数据文件。 - - **RuntimeError**: num_parallel_workers超过系统最大线程数。 - - **RuntimeError**: 标注的xml文件格式异常或无效。 - - **RuntimeError**: 标注的xml文件缺失`object`属性。 - - **RuntimeError**: 标注的xml文件缺失`bndbox`属性。 - - **RuntimeError**: 同时指定了`sampler`和`shuffle`。 - - **RuntimeError**: 同时指定了`sampler`和`num_shards`。 - - **RuntimeError**: 指定了`num_shards`参数，但是未指定`shard_id`参数。 - - **RuntimeError**: 指定了`shard_id`参数，但是未指定`num_shards`参数。 - - **ValueError**： 指定的任务不为'Segmentation'或'Detection'。 - - **ValueError**： 指定任务为'Segmentation'时，class_indexing不为None。 - - **ValueError**： 与usage相关的txt文件不存在。 - - **ValueError**: `shard_id`参数错误（小于0或者大于等于 `num_shards`）。 - **注：** - - 当指定`extra_metadata`为True时，除非显式使用rename算子以删除元信息列明的前缀('_meta-')， + - **RuntimeError**: `dataset_dir` 不包含任何数据文件。 + - **RuntimeError**: `num_parallel_workers` 超过系统最大线程数。 + - **RuntimeError**: 标注的xml文件格式异常或无效。 + - **RuntimeError**: 标注的xml文件缺失 `object` 属性。 + - **RuntimeError**: 标注的xml文件缺失 `bndbox` 属性。 + - **RuntimeError**: 同时指定了 `sampler `和 `shuffle` 。 + - **RuntimeError**: 同时指定了 `sampler` 和 `num_shards` 。 + - **RuntimeError**: 指定了 `num_shards` 参数，但是未指定 `shard_id` 参数。 + - **RuntimeError**: 指定了 `shard_id` 参数，但是未指定 `num_shards` 参数。 + - **ValueError**： 指定的任务不为'Segmentation'或'Detection'。 + - **ValueError**： 指定任务为'Segmentation'时，class_indexing不为None。 + - **ValueError**： 与usage相关的txt文件不存在。 + - **ValueError**: `shard_id` 参数错误（小于0或者大于等于 `num_shards` ）。 + + .. note:: + - 当指定 `extra_metadata` 为True时，除非显式使用rename算子以删除元信息列明的前缀('_meta-')， 否则迭代的数据行中不会出现'[_meta-filename, dtype=string]'列。 - - - 此数据集可以指定`sampler`参数，但`sampler` 和 `shuffle` 是互斥的。下表展示了几种合法的输入参数及预期的行为。 + - 此数据集可以指定 `sampler` 参数，但 `sampler` 和 `shuffle` 是互斥的。下表展示了几种合法的输入参数及预期的行为。 - .. list-table:: 配置`sampler`和`shuffle`的不同组合得到的预期排序结果 + .. list-table:: 配置 `sampler` 和 `shuffle` 的不同组合得到的预期排序结果 :widths: 25 25 50 :header-rows: 1 - * - 参数`sampler` - - 参数`shuffle` + * - 参数 `sampler` + - 参数 `shuffle` - 预期数据顺序 * - None - None @@ -63,35 +64,36 @@ Class mindspore.dataset.VOCDataset(dataset_dir, task='Segmentation', usage='trai * - None - False - 顺序排列 - * - 参数`sampler` + * - 参数 `sampler` - None - - 由`sampler`行为定义的顺序 - * - 参数`sampler` + - 由 `sampler` 行为定义的顺序 + * - 参数 `sampler` - True - 不允许 - * - 参数`sampler` + * - 参数 `sampler` - False - 不允许 - **示例：** - >>> voc_dataset_dir = "/path/to/voc_dataset_directory" - >>> - >>> # 1) 读取VOC数据的Segmentation任务中的train部分进行训练 - >>> dataset = ds.VOCDataset(dataset_dir=voc_dataset_dir, task="Segmentation", usage="train") - >>> - >>> # 2) 读取VOC数据的Detection任务中的train部分进行训练 - >>> dataset = ds.VOCDataset(dataset_dir=voc_dataset_dir, task="Detection", usage="train") - >>> - >>> # 3) 以8个线程随机顺序读取voc_dataset_dir中的所有VOC数据集样本 - >>> dataset = ds.VOCDataset(dataset_dir=voc_dataset_dir, task="Detection", usage="train", - ... num_parallel_workers=8) - >>> - >>> # 4) 读voc_dataset_dir中的所有VOC数据集图片样本，且对图像进行解码 - >>> dataset = ds.VOCDataset(dataset_dir=voc_dataset_dir, task="Detection", usage="train", - ... decode=True, shuffle=False) - >>> - >>> # 在VOC数据集中，如果task='Segmentation'，每一次迭代得到的数据行都有"image"和"target"两个键。 - >>> # 在VOC数据集中，如果task='Detection'，每一次迭代得到的数据行都有"image"和"annotation"两个键。 + **样例：** + + >>> voc_dataset_dir = "/path/to/voc_dataset_directory" + >>> + >>> # 1) 读取VOC数据的Segmentation任务中的train部分进行训练 + >>> dataset = ds.VOCDataset(dataset_dir=voc_dataset_dir, task="Segmentation", usage="train") + >>> + >>> # 2) 读取VOC数据的Detection任务中的train部分进行训练 + >>> dataset = ds.VOCDataset(dataset_dir=voc_dataset_dir, task="Detection", usage="train") + >>> + >>> # 3) 以8个线程随机顺序读取voc_dataset_dir中的所有VOC数据集样本 + >>> dataset = ds.VOCDataset(dataset_dir=voc_dataset_dir, task="Detection", usage="train", + ... num_parallel_workers=8) + >>> + >>> # 4) 读voc_dataset_dir中的所有VOC数据集图片样本，且对图像进行解码 + >>> dataset = ds.VOCDataset(dataset_dir=voc_dataset_dir, task="Detection", usage="train", + ... decode=True, shuffle=False) + >>> + >>> # 在VOC数据集中，如果task='Segmentation'，每一次迭代得到的数据行都有"image"和"target"两个键。 + >>> # 在VOC数据集中，如果task='Detection'，每一次迭代得到的数据行都有"image"和"annotation"两个键。 **关于VOC数据集：** diff --git a/docs/api/api_python/dataset/mindspore.dataset.WaitedDSCallback.rst b/docs/api/api_python/dataset/mindspore.dataset.WaitedDSCallback.rst index ead96cd98ea..dcd6cbbdb00 100644 --- a/docs/api/api_python/dataset/mindspore.dataset.WaitedDSCallback.rst +++ b/docs/api/api_python/dataset/mindspore.dataset.WaitedDSCallback.rst @@ -67,7 +67,7 @@ mindspore.dataset.WaitedDSCallback .. py:method:: ds_step_end(ds_run_context) - 用于定义在每个数据step结束后执行的回调方法。 + 用于定义在每个数据step结束后执行的回调方法。 **参数：** @@ -107,7 +107,7 @@ mindspore.dataset.WaitedDSCallback .. py:method:: step_end(run_context) - 内部方法，不能被调用或重写。通过重写mindspore.train.callback.Callback.step_end来释放ds_step_begin的等待。 + 内部方法，不能被调用或重写。通过重写mindspore.train.callback.Callback.step_end来释放 `ds_step_begin` 的等待。 **参数：** diff --git a/docs/api/api_python/dataset/mindspore.dataset.WeightedRandomSampler.rst b/docs/api/api_python/dataset/mindspore.dataset.WeightedRandomSampler.rst index ce3d75812c9..60ddec4b31f 100644 --- a/docs/api/api_python/dataset/mindspore.dataset.WeightedRandomSampler.rst +++ b/docs/api/api_python/dataset/mindspore.dataset.WeightedRandomSampler.rst @@ -1,26 +1,32 @@ -Class mindspore.dataset.WeightedRandomSampler(weights, num_samples=None, replacement=True) +mindspore.dataset.WeightedRandomSampler +======================================= + +.. py:class:: mindspore.dataset.WeightedRandomSampler(weights, num_samples=None, replacement=True) 使用给定的权重（概率）进行随机采样[0，len(weights) - 1]中的元素。 - 参数： - weights (list[float, int])：权重序列，总和不一定为1。 - num_samples (int, optional)：待采样的元素数量（默认值为None，代表采样所有元素）。 - replacement (bool)：如果值为True，则将样本ID放回下一次采样（默认值为True）。 + **参数：** - 示例： - >>> weights = [0.9, 0.01, 0.4, 0.8, 0.1, 0.1, 0.3] - >>> - >>> # creates a WeightedRandomSampler that will sample 4 elements without replacement - >>> sampler = ds.WeightedRandomSampler(weights, 4) - >>> dataset = ds.ImageFolderDataset(image_folder_dataset_dir, - ... num_parallel_workers=8, - ... sampler=sampler) + - **weights** (list[float, int])：权重序列，总和不一定为1。 + - **num_samples** (int, optional)：待采样的元素数量（默认值为None，代表采样所有元素）。 + - **replacement** (bool)：如果值为True，则将样本ID放回下一次采样（默认值为True）。 - 异常： - TypeError：weights元素的类型不是number。 - TypeError：num_samples不是整数值。 - TypeError：replacement不是布尔值。 - RuntimeError：weights为空或全为零。 - ValueError：num_samples为负值。 + **样例：** + + >>> weights = [0.9, 0.01, 0.4, 0.8, 0.1, 0.1, 0.3] + >>> + >>> # 创建一个WeightedRandomSampler，在没有replacement的情况下对4个元素进行采样 + >>> sampler = ds.WeightedRandomSampler(weights, 4) + >>> dataset = ds.ImageFolderDataset(image_folder_dataset_dir, + ... num_parallel_workers=8, + ... sampler=sampler) + + **异常：** + + - **TypeError：** `weights` 元素的类型不是number。 + - **TypeError：** `num_samples` 不是整数值。 + - **TypeError：** `replacement` 不是布尔值。 + - **RuntimeError：** `weights` 为空或全为零。 + - **ValueError：** `num_samples` 为负值。 .. include:: mindspore.dataset.BuiltinSampler.rst \ No newline at end of file