writeall

将数据存储写入文件

自 R2020a 起

全页折叠

语法

writeall(ds,outputLocation)

writeall(ds,outputLocation,Name,Value)

说明

示例

writeall(ds,outputLocation) 将来自输入数据存储 ds 中的数据写入 outputLocation 中指定位置的输出文件。输出文件的数量与数据存储引用的文件数量相同。

示例

writeall(ds,outputLocation,Name,Value) 使用一个或多个名称-值对组参数指定的其他选项写入数据。例如，您可以指定 'OutputType' 和文件扩展名（如 'csv'），以指定 writeall 创建的文件的类型。

示例

全部折叠

写入和重新构造数据存储

打开实时脚本

将一个数据存储写入磁盘，然后为写入的文件创建一个新数据存储。此过程对于保存您的工作或与同事共享数据存储非常有用。

为 airlinesmall.csv 数据集创建一个数据存储，将 'NA' 值视为缺失数据。仅选择 Year、Month 和 Carrier 变量。

ds = datastore('airlinesmall.csv');
ds.TreatAsMissing = 'NA';
ds.SelectedVariableNames = {'Month','Year','UniqueCarrier'};

预览该数据存储。

preview(ds)

ans=8×3 table
    Month    Year    UniqueCarrier
    _____    ____    _____________

     10      1987       {'PS'}    
     10      1987       {'PS'}    
     10      1987       {'PS'}    
     10      1987       {'PS'}    
     10      1987       {'PS'}    
     10      1987       {'PS'}    
     10      1987       {'PS'}    
     10      1987       {'PS'}

将此数据存储保存到 C:\ 盘上名为 ExampleData 的新文件夹中。（您可以指定不同的写入位置，特别是当您使用的不是 Windows® 计算机时。）将 'FolderLayout' 指定为 'flatten' 以将数据存储文件直接放入目标文件夹中，而不创建子文件夹。

location = 'C:\ExampleData';
writeall(ds,location,'Folderlayout','flatten')

从您的工作目录中清除 ds。要从磁盘还原数据存储，请创建一个新数据存储，该数据存储引用写入数据的同一文件夹。

clear ds
ds2 = datastore(location);

在输出位置复制或扁平化文件夹布局

将数据存储写入文件时，您可以通过设置 'FolderLayout' 参数来选择复制或扁平化文件夹结构。从输入位置创建一个图像数据存储，然后将该数据存储写入文件。接下来，通过复制文件夹布局在输出位置写入文件。最后，将这些文件作为扁平列表写入输出位置。

从位置 'C:\input\' 创建一个图像数据存储，其中包含一些汽车和火车的图像：

imds = imageDatastore('C:\input\','IncludeSubfolders',true);

此文件夹结构只是一个示例。您可以在包含图像文件的计算机上使用一种文件夹结构来尝试该功能。

检查输入数据存储的 Folders 属性，该属性包含输入数据集的完全限定路径。

imds.Folders

ans =

  1×1 cell array

    {'C:\input\'}

将数据存储写入输出位置 'C:\output\'。'FolderLayout' 参数的默认值为 'duplicate'。因此，writeall 函数会复制输入数据存储的 Folders 属性中包含的所有文件夹，然后将文件写入相应的输出文件夹。

writeall(imds,'C:\output\');

现在，通过将 'FolderLayout' 设置为 'flatten'，将数据存储中的文件作为扁平列表写入输出位置 'C:\output\'。在这种情况下，writeall 函数不会保留输入文件夹布局，而是将所有文件写入一个扁平输出位置。

writeall(imds,'C:\output\','FolderLayout','flatten');

有关详细信息，请参阅 FolderLayout。

向输出文件名添加前缀或后缀

您可以使用 FilenamePrefix 和 FilenameSuffix 参数将文本添加到输出文件名的开头或末尾。从输入位置创建一个图像数据存储。将该数据存储写入文件，并在文件名开头追加文本。然后再次写入该数据存储，并在文件名末尾追加文本。

从位置 'C:\input\' 创建一个图像数据存储，其中包含一些汽车和火车的图像：

imds = imageDatastore('C:\input\','IncludeSubfolders',true);

此文件夹结构只是一个示例。您可以在包含图像文件的计算机上使用一种文件夹结构来尝试该功能。

现在，将文件写入一个输出位置。将 FilenamePrefix 的值指定为 'png_'，以将该文本追加到每个输出文件名的开头。

writeall(imds,'C:\output\','FilenamePrefix','png_');

将文件写入一个不同输出位置。将 FilenameSuffix 的值指定为 '_image'，以将该文本追加到每个输出文件名的末尾。

writeall(imds,'C:\output2\','FilenameSuffix','_image');

输入参数

全部折叠

`ds` — 输入数据存储
数据存储对象

输入数据存储。您可以将下列数据存储用作 writeall 的输入：

如果您提供 'OutputFormat' 或 'WriteFcn' 名称-值对组，您也可以将这些数据存储与 writeall 结合使用：

`outputLocation` — 要写入数据的文件夹位置
字符向量 | 字符串标量

要写入数据的文件夹位置，指定为字符向量或字符串标量。outputLocation 可以指定完整或相对路径。

示例： outputLocation = '../../dir/data'

示例： outputLocation = "C:\Users\MyName\Desktop"

数据类型： char | string

名称-值参数

将可选的参数对组指定为 Name1=Value1,...,NameN=ValueN，其中 Name 是参数名称，Value 是对应的值。名称-值参数必须出现在其他参数之后，但参数对组的顺序无关紧要。

在 R2021a 之前，使用逗号分隔每个名称和值，并用引号将 Name 引起来。

示例： writeall(ds,outputLocation,'FolderLayout','flatten')

常规选项

全部折叠

`OutputFormat` — 输出文件格式
字符向量 | 字符串标量

输出文件格式，指定为逗号分隔的对组，其中包含 'OutputFormat' 和一个字符向量或字符串标量。

根据输入数据存储 ds 的类型，为输出文件选择下列值之一。您可以为下面列出的任何表格数据存储选择任一表格输出格式。

输入数据存储	输出格式
`TabulartextDatastore`, `SpreadsheetDatastore`, `ParquetDatastore`	`'txt'`、`'csv'`、`'xlsx'`、`'xls'`、`'parquet'` 或 `'parq'`
`ImageDatastore`	`'png'`、`'jpg'`、`'jpeg'`、`'tif'` 或 `'tiff'`
`AudioDatastore`	`'wav'`、`'ogg'`、`'flac'`、`'mp4'` 或 `'m4a'`
`FileDatastore`, `TransformedDatastore`, `CombinedDatastore`, `SequentialDatastore`	支持所有输出格式。

对于某些输出格式，您可以使用其他名称-值对组来优化写入操作。

输出格式	名称-值对组
`jpeg`, `jpg`	`'Quality'`
`wav`, `flac`	`'BitsPerSample'`
`mp4`, `m4a`	`'BitRate'`
`txt`, `csv`	`'WriteVariableNames'` `'Delimiter'` `Encoding` `'QuoteStrings'`
`xls`, `xlsx`	`'Sheet'`

数据类型： char | string

`FolderLayout` — 输出文件夹中文件的布局
`'duplicate'` （默认） | `'flatten'`

输出文件夹中文件的布局，指定为逗号分隔的对组，其中包含 'FolderLayout' 和 'duplicate' 或 'flatten'。

'duplicate' - writeall 函数将输入数据位置中包含的文件夹结构复制到指定的输出位置。输入数据位置包含输入数据存储的 Folders 属性。
'flatten' - writeall 函数将输入中的所有文件写入指定的不包含任何子文件夹的输出文件夹。

数据类型： char | string

`FilenamePrefix` — 文件名的前缀
字符向量 | 字符串标量

文件名的前缀，指定为逗号分隔的对组，其中包含 'FilenamePrefix' 和一个字符向量或字符串标量。

writeall 函数将指定的前缀添加到输出文件名。例如，以下代码将今天的日期添加到来自数据存储的所有输出文件名的开头：

prefixText = string(datetime('today'))
writeall(imds,'C:\myFolder','FilenamePrefix',prefixText);

数据类型： char | string

`FilenameSuffix` — 文件名的后缀
字符向量 | 字符串标量

文件名的后缀，指定为逗号分隔的对组，其中包含 'FilenameSuffix' 和一个字符向量或字符串标量。

writeall 函数将指定的后缀添加到输出文件名。例如，以下代码将描述性文本 'jpeg_70per' 添加到来自数据存储的所有输出文件名的末尾：

writeall(imds,'C:\myFolder','FilenameSuffix','jpeg_70per');

数据类型： char | string

`UseParallel` — 并行写入的指示符
`false` （默认） | `true` | `0` | `1`

并行写入的指示符，指定为逗号分隔的对组，其中包含 'UseParallel' 和 false 或 true (0) 或 1。

默认情况下，writeall 以串行方式写入。如果您将 UseParallel 设置为 true，则 writeall 会将写入操作分成若干单独的组且并行运行这些组，前提是满足以下条件：

安装了 Parallel Computing Toolbox™。
存在一个打开的并行池，或者在 Parallel Preferences 中启用了自动池创建。

否则，writeall 以串行方式写入，而不管 UseParallel 的值是什么。

writeall 不支持通过本地线程并行写入。

注意

对于 CombinedDatastore 对象或通过 transform 得到的应用于 CombinedDatastore 的数据存储，不支持并行写入。

数据类型： logical

`WriteFcn` — 自定义写函数
函数句柄

自定义写函数，指定为以逗号分隔的对组，其中包含 'WriteFcn' 和一个函数句柄。指定的函数负责创建输出文件。

您可以使用 'WriteFcn' 名称-值对组参数写入各种格式的数据，即使 writeall 不直接支持输出格式。

函数签名

自定义写入函数必须接受至少三个输入参数，即 data、writeInfo 和 outputType：

function myWriteFcn(data,writeInfo,outputType)

该函数还可以在前三个必需输入后接受其他输入，如名称-值对组。

data 包含对数据存储运行 read 方法的输出。

writeInfo 是 matlab.io.datastore.WriteInfo 类型的对象，包含下表中列出的字段。

字段	描述	类型
`ReadInfo`	`read` 方法的第二个输出	`struct`
`SuggestedOutputName`	满足位置和命名要求的完全限定的全局唯一文件名	`string`
`Location`	传递给数据存储写入的位置参数	`string`

outputType 是要写入的输出格式，例如 "txt" 或 "csv"。

示例函数

从数据存储中写入 Parquet 文件的写入函数是：

function myParquetWriteFcn(data, writeInfo, outputType)
if strcmp(outputType,"parquet")
  parquetwrite(writeInfo.SuggestedOutputName,data)
end
end

要调用 myParquetWriteFcn 作为数据存储 ds 的写入函数，请使用以下命令：

ds = parquetDatastore(location);
outputLocation = 'C:/tmp/MyData';
writeall(ds,outputLocation,'WriteFcn',@myParquetWriteFcn);

数据类型： function_handle

jpeg 或 jpg 输出的选项

全部折叠

`Quality` — JPEG 压缩文件的质量
`75` （默认） | 范围 [0，100] 内的标量

JPEG 压缩文件的质量，指定为以逗号分隔的对组，包含 'Quality' 和范围 [0，100] 内的标量，其中 0 表示较低质量和较高的压缩率，100 表示较高质量和较低的压缩率。

示例： 'Quality',25

wav 或 flac 输出的选项

全部折叠

`BitsPerSample` — 每样本输出位数
`16` （默认） | `8` | `24` | `32` | `64`

每样本的输出位数，指定为以逗号分隔的对组，其中包含 'BitsPerSample' 和 8、16、24、32 或 64。

对于 FLAC 文件，仅支持 8、16 或 24 的采样位数。

示例： 'BitsPerSample',32

mp4 或 m4a 输出的选项

全部折叠

`BitRate` — 千位/秒 (kbit/s)
128 （默认） | 64 | 96 | 160 | 192 | 256 | 320

用于已压缩的音频文件的千位/秒 (kbit/s) 数，指定为以逗号分隔的对组，其中包含 'BitRate' 和 64、96、128、160、192、256 或 320。在 Windows^® 7 或更高版本中，仅 96、128、160 和 192 为有效值。

通常，较大的 BitRate 值可以提高压缩质量。

示例： 'BitRate',96

txt 或 csv 输出的选项

全部折叠

`WriteVariableNames` — 指示将变量名称写入为列标题的指示符
`true` （默认） | `false`

指示将变量名称写入为列标题的指示符，指定为逗号分隔的对组，其中包含 'WriteVariableNames' 和 true 或 false。

指示符	行为
`true`	写入函数将变量名称作为输出的列标题包含在内。这是默认行为。
`false`	写入函数不会在输出中包含变量名称。

`Delimiter` — 字段分隔符
字符向量 | 字符串标量

字段分隔符，指定为逗号分隔的对组，由 'Delimiter' 和一个字符向量或字符串标量组成，该字符串标量包含以下设定符之一：

设定符	字段分隔符
`','` `'comma'`	逗号。这是默认行为。
`' '` `'space'`	空格
`'\t'` `'tab'`	制表符
`';'` `'semi'`	分号
`'\|'` `'bar'`	垂直条

您只能将 'Delimiter' 名称-值对组用于带分隔符的文本文件。

示例： 'Delimiter','space'

数据类型： char | string

`Encoding` — 字符编码方案
`'system'` （默认） | `'UTF-8'` | `'ISO-8859-1'` | `'windows-1251'` | `'windows-1252'` | ...

与文件关联的字符编码方案，指定为由 'Encoding' 和 'system' 组成的逗号分隔对组，或指定为标准字符编码方案名称，如下表所示的值之一。当您不指定任何编码或将编码指定为 'system' 时，写入函数将使用您系统的默认编码写入该文件。

`"Big5"`	`"ISO-8859-1"`	`"windows-874"`
`"Big5-HKSCS"`	`"ISO-8859-2"`	`"windows-949"`
`"CP949"`	`"ISO-8859-3"`	`"windows-1250"`
`"EUC-KR"`	`"ISO-8859-4"`	`"windows-1251"`
`"EUC-JP"`	`"ISO-8859-5"`	`"windows-1252"`
`"EUC-TW"`	`"ISO-8859-6"`	`"windows-1253"`
`"GB18030"`	`"ISO-8859-7"`	`"windows-1254"`
`"GB2312"`	`"ISO-8859-8"`	`"windows-1255"`
`"GBK"`	`"ISO-8859-9"`	`"windows-1256"`
`"IBM866"`	`"ISO-8859-11"`	`"windows-1257"`
`"KOI8-R"`	`"ISO-8859-13"`	`"windows-1258"`
`"KOI8-U"`	`"ISO-8859-15"`	`"US-ASCII"`
	`"Macintosh"`	`"UTF-8"`
	`"Shift_JIS"`

示例： 'UTF-8'

数据类型： char | string

`QuoteStrings` — 用于写入引用文本的指示符
`"minimal"` （默认） | `"all"` | `"none"`

用于写入引用文本的指示符，指定为 "minimal"、"all" 或 "none"。

如果 QuoteStrings 是 "minimal"，则该函数会将包含分隔符、换行符或双引号字符的任何变量用双引号字符引起来。
如果 QuoteStrings 是 "all"，则该函数会将所有文本、分类、日期时间和持续时间变量用双引号字符引起来。
如果 QuoteStrings 是 "none"，则该函数不会使用双引号字符将变量引起来。

您只能将 QuoteStrings 名称-值参数用于带分隔符的文本文件。

xls 或 xlsx 输出的选项

全部折叠

`Sheet` — 要写入的工作表
字符向量 | 字符串标量 | 正整数

要写入的工作表，指定为逗号分隔的对组，包含 'Sheet' 和一个包含工作表名称或正整数（指示工作表索引）的字符向量或字符串标量。工作表名称不能包含冒号 (:)。要确定电子表格文件中工作表的名称，请使用 sheets = sheetnames(filename)。有关详细信息，请参阅 sheetnames。

按名称或索引指定要写入的工作表：

名称 - 如果文件中不存在指定的工作表名称，则写入函数将在工作表集合的末尾添加一个新工作表。
索引 - 如果指定的工作表索引大于工作表数，则写入函数会追加空工作表，直至工作簿中的工作表数等于工作表索引。写入函数还会生成一条警告，指示已添加新工作表。

您只能将 'Sheet' 名称-值对组用于电子表格文件。

示例： 'Sheet',2

示例： 'Sheet', 'MySheetName'

扩展功能

自动并行支持
通过使用 Parallel Computing Toolbox™ 自动运行并行计算来加快代码执行。

要并行运行，请将 'UseParallel' 选项设置为 true。

有关并行计算的更多一般信息，请参阅Run MATLAB Functions with Automatic Parallel Support (Parallel Computing Toolbox)。

版本历史记录

在 R2020a 中推出

另请参阅

writeall

语法

说明

示例

写入和重新构造数据存储

在输出位置复制或扁平化文件夹布局

向输出文件名添加前缀或后缀

输入参数

ds — 输入数据存储 数据存储对象

outputLocation — 要写入数据的文件夹位置 字符向量 | 字符串标量

名称-值参数

OutputFormat — 输出文件格式 字符向量 | 字符串标量

FolderLayout — 输出文件夹中文件的布局 'duplicate' （默认） | 'flatten'

FilenamePrefix — 文件名的前缀 字符向量 | 字符串标量

FilenameSuffix — 文件名的后缀 字符向量 | 字符串标量

UseParallel — 并行写入的指示符 false （默认） | true | 0 | 1

WriteFcn — 自定义写函数 函数句柄

函数签名

示例函数

Quality — JPEG 压缩文件的质量 75 （默认） | 范围 [0，100] 内的标量

BitsPerSample — 每样本输出位数 16 （默认） | 8 | 24 | 32 | 64

BitRate — 千位/秒 (kbit/s) 128 （默认） | 64 | 96 | 160 | 192 | 256 | 320

WriteVariableNames — 指示将变量名称写入为列标题的指示符 true （默认） | false

Delimiter — 字段分隔符 字符向量 | 字符串标量

Encoding — 字符编码方案 'system' （默认） | 'UTF-8' | 'ISO-8859-1' | 'windows-1251' | 'windows-1252' | ...

QuoteStrings — 用于写入引用文本的指示符 "minimal" （默认） | "all" | "none"

Sheet — 要写入的工作表 字符向量 | 字符串标量 | 正整数

扩展功能

自动并行支持 通过使用 Parallel Computing Toolbox™ 自动运行并行计算来加快代码执行。

版本历史记录

另请参阅

WeChat

`ds` — 输入数据存储
数据存储对象

`outputLocation` — 要写入数据的文件夹位置
字符向量 | 字符串标量

`OutputFormat` — 输出文件格式
字符向量 | 字符串标量

`FolderLayout` — 输出文件夹中文件的布局
`'duplicate'` （默认） | `'flatten'`

`FilenamePrefix` — 文件名的前缀
字符向量 | 字符串标量

`FilenameSuffix` — 文件名的后缀
字符向量 | 字符串标量

`UseParallel` — 并行写入的指示符
`false` （默认） | `true` | `0` | `1`

`WriteFcn` — 自定义写函数
函数句柄

`Quality` — JPEG 压缩文件的质量
`75` （默认） | 范围 [0，100] 内的标量

`BitsPerSample` — 每样本输出位数
`16` （默认） | `8` | `24` | `32` | `64`

`BitRate` — 千位/秒 (kbit/s)
128 （默认） | 64 | 96 | 160 | 192 | 256 | 320

`WriteVariableNames` — 指示将变量名称写入为列标题的指示符
`true` （默认） | `false`

`Delimiter` — 字段分隔符
字符向量 | 字符串标量

`Encoding` — 字符编码方案
`'system'` （默认） | `'UTF-8'` | `'ISO-8859-1'` | `'windows-1251'` | `'windows-1252'` | ...

`QuoteStrings` — 用于写入引用文本的指示符
`"minimal"` （默认） | `"all"` | `"none"`

`Sheet` — 要写入的工作表
字符向量 | 字符串标量 | 正整数

自动并行支持
通过使用 Parallel Computing Toolbox™ 自动运行并行计算来加快代码执行。