本页翻译不是最新的。点击此处可查看最新英文版本。

delimitedTextImportOptions

为带分隔符的文本导入选项对象

说明

DelimitedTextImportOptions 对象允许您指定 MATLAB^® 如何从分隔的文本文件中导入表格数据。此对象包含的属性可以控制数据导入过程，包括如何处理错误和缺失的数据。

创建对象

您可以使用 detectImportOptions 函数或 delimitedTextImportOptions 函数（下文介绍）创建 DelimitedTextImportOptions 对象：

• 使用 detectImportOptions 根据 filename 中指定的分隔文本文件的内容检测并填充导入属性。

  opts = detectImportOptions(filename);

• 使用 delimitedTextImportOptions 根据导入要求定义导入属性。

语法

opts = delimitedTextImportOptions

opts = delimitedTextImportOptions('NumVariables',numVars)

opts = delimitedTextImportOptions(___,Name,Value)

描述

opts = delimitedTextImportOptions 使用一个变量创建 DelimitedTextImportOptions 对象。

opts = delimitedTextImportOptions('NumVariables',numVars) 使用 numVars 中指定的变量数目创建该对象。

opts = delimitedTextImportOptions(___,Name,Value) 使用一个或多个名称-值对组参数指定 DelimitedTextImportOptions 对象的其他属性。

输入参数

numVars — 变量的数目

正整数标量

变量的数目，指定为正整数标量。

属性

变量属性

VariableNames — 变量名称

字符向量元胞数组 | 字符串数组

变量名称，指定为字符向量元胞数组或字符串数组。VariableNames 属性包含导入变量时要使用的名称。

如果数据中包含 N 个变量，但未指定变量名称，VariableNames 属性中将包含 {'Var1','Var2',...,'VarN'}。

要支持无效的 MATLAB 标识符作为变量名称，例如包含空白和非 ASCII 字符的变量名称，请将 VariableNamingRule 的值设置为 'preserve'。

示例: opts.VariableNames 返回当前（检测到的）变量名称。

示例: opts.VariableNames(3) = {'Height'} 将第三个变量的名称更改为 Height。

数据类型: char | string | cell

VariableNamingRule — 保留变量名称的标志

"modify" (默认) | "preserve"

保留变量名称的标志，指定为 "modify" 或 "preserve"。

• "modify" - 将无效变量名称（由 isvarname 函数确定）转换为有效的 MATLAB 标识符。

• "preserve" - 保留作为无效 MATLAB 标识符的变量名称，如包含空白和非 ASCII 字符的变量名称。

从 R2019b 开始，变量名称和行名称可以包含任何字符，包括空格和非 ASCII 字符。此外，它们可以由任何字符（而不仅仅是字母）开头。变量名称和行名称可以不是有效的 MATLAB 标识符（由 isvarname 函数决定）。要保留这些变量名称和行名称，请将 VariableNamingRule 的值设置为 "preserve"。当 VariableNamingRule 的值从 "modify" 更改为 "preserve" 时，变量名称不会刷新。

数据类型: char | string

VariableTypes — 变量的数据类型

字符向量元胞数组 | 字符串数组

变量的数据类型，指定为字符向量元胞数组，或包含一组有效数据类型名称的字符串数组。VariableTypes 属性指定导入变量时要使用的数据类型。

要更新 VariableTypes 属性，请使用 setvartype 函数。

示例: opts.VariableTypes 返回当前变量数据类型。

示例: opts = setvartype(opts,'Height',{'double'}) 将变量 Height 的数据类型更改为 double。

SelectedVariableNames — 要导入的变量子集

字符向量 | 字符串标量 | 字符向量元胞数组 | 字符串数组 | 数值索引数组

要导入的变量子集，指定为字符向量、字符串标量、字符向量元胞数组、字符串数组或数值索引数组。

SelectedVariableNames 必须是 VariableNames 属性中包含的名称的子集。默认情况下，SelectedVariableNames 包含 VariableNames 属性中的所有变量名称，也就是说将导入所有变量。

可以使用 SelectedVariableNames 属性只导入相关变量。使用 SelectedVariableNames 属性指定变量子集，然后使用 readtable 只导入该子集。

要支持无效的 MATLAB 标识符作为变量名称，例如包含空白和非 ASCII 字符的变量名称，请将 VariableNamingRule 的值设置为 'preserve'。

示例: opts.SelectedVariableNames = {'Height','LastName'} 只为导入操作选择两个变量，即 Height 和 LastName。

示例: opts.SelectedVariableNames = [1 5] 只为导入操作选择两个变量，即第一个变量和第五个变量。

示例: T = readtable(filename,opts) 返回一个表，其中只包含在 opts 对象的 SelectedVariableNames 属性中指定的变量。

数据类型: uint16 | uint32 | uint64 | char | string | cell

VariableOptions — 类型特定的变量导入选项

由变量导入选项对象组成的数组

类型特定的变量导入选项，以变量导入选项对象数组形式返回。此数组为 VariableNames 属性中指定的每个变量包含一个对应的对象。数组中的每个对象均包含一些属性，支持导入特定数据类型的数据。

变量选项支持以下数据类型：数值、文本、logical、datetime 或 categorical。

要查询变量的当前（或检测到的）选项，请使用 getvaropts 函数。

要为变量设置和自定义选项，请使用 setvaropts 函数。

示例: opts.VariableOptions 返回 VariableImportOptions 对象的集合，每个对象对应于数据中的一个变量。

示例: getvaropts(opts,'Height') 返回 Height 变量的 VariableImportOptions 对象。

示例: opts = setvaropts(opts,'Height','FillValue',0) 将变量 Height 的 FillValue 属性设置为 0。

位置属性

DataLines — 数据位置

正整数标量 | 正整数标量数组

数据位置，指定为正整数标量或由正整数标量组成的 N-×-2 数组。使用以下形式之一指定 DataLines。

指定为	描述
n	指定包含数据的第一行。使用 n 指定值会将 DataLines 属性的值设置为 [n inf]。导入函数读取从第 n 行到文件末尾之间的所有行。 n 必须是大于零的正整数。
[n1 n2]	指定包含数据的行范围。n1 是包含数据的第一行，n2 是包含数据的最后一行。 数组 [n1 n2] 中的值必须为非零正整数，且 n2 必须大于 n1。
[n1 n2; n3 n4;...]	使用包含 N 个不同行范围的 N-×-2 数组来指定要读取的多个行范围。 含有多个行范围的有效数组必须满足以下条件： 以递增顺序指定行范围，也就是说，数组中指定的第一个行范围出现在文件中的其他行范围之前。 仅包含不重叠的行范围。 指定多个行范围时，仅在指定数组中最后一个行范围的结尾时使用 Inf。例如，[1 3; 5 6; 8 Inf]。

示例: opts.DataLines = 5 将 DataLines 属性设置为值 [5 inf]。读取从第 5 行开始到文件末尾之间的所有数据行。

示例: opts.DataLines = [2 6] 将属性设置为从第 2 行读取到第 6 行。

示例: opts.DataLines = [1 3; 5 6; 8 inf] 将属性设置为读取第 1 行、第 2 行、第 3 行、第 5 行、第 6 行以及从第 8 行到文件末尾之间的所有行。

数据类型: single | double | uint8 | uint16 | uint32 | uint64

RowNamesColumn — 行名称的位置

0 (默认) | 正整数标量

行名称的位置，指定为正整数标量。RowNamesColumn 属性指定包含行名称的列的位置。

如果 RowNamesColumn 指定为 0，则不导入行名称。否则，将从指定的列中导入行名称。

示例: opts.RowNamesColumn = 2;

数据类型: single | double | uint8 | uint16 | uint32 | uint64

VariableNamesLine — 变量名称的位置

0 (默认) | 正整数标量

变量名称的位置，指定为正整数标量。VariableNamesLine 属性指定变量名称所在的行号。

如果 VariableNamesLine 指定为 0，则不导入变量名称。否则，将从指定的行中导入变量名称。

示例: opts.VariableNamesLine = 6;

数据类型: single | double | uint8 | uint16 | uint32 | uint64

VariableDescriptionsLine — 变量描述的位置

0 (默认) | 正整数标量

变量描述的位置，指定为正整数标量。VariableDescriptionsLine 属性指定变量描述所在的行号。

如果 VariableDescriptionsLine 指定为 0，则不导入变量描述。否则，将从指定的行中导入变量描述。

示例: opts.VariableDescriptionsLine = 7;

数据类型: single | double | uint8 | uint16 | uint32 | uint64

VariableUnitsLine — 变量单位的位置

0 (默认) | 正整数标量

变量单位的位置，指定为正整数标量。VariableUnitsLine 属性指定变量单位所在的行号。

如果 VariableUnitsLine 指定为 0，则不导入变量单位。否则，将从指定的行中导入变量单位。

示例: opts.VariableUnitsLine = 8;

数据类型: single | double | uint8 | uint16 | uint32 | uint64

带分隔符的文本属性

Delimiter — 字段分隔符

字符串数组 | 字符向量 | 字符向量元胞数组

带分隔符的文本文件中的字段分隔符，指定为字符串数组、字符向量或字符向量元胞数组。

示例: "Delimiter","|"

示例: "Delimiter",[";","*"]

Whitespace — 要视为空白的字符

字符向量 | 字符串标量

要视为空白的字符，指定为包含一个或多个字符的字符向量或字符串标量。

示例: 'Whitespace',' _'

示例: 'Whitespace','?!.,'

LineEnding — 行尾字符

["\n","\r","\r\n"] (默认) | 字符串数组 | 字符向量 | 字符向量元胞数组

行尾字符，指定为字符串数组、字符向量或字符向量元胞数组。

示例: "LineEnding","\n"

示例: "LineEnding","\r\n"

示例: "LineEnding",["\b",":"]

CommentStyle — 注释样式

字符串数组 | 字符向量 | 字符向量元胞数组

注释样式，指定为字符串数组、字符向量或字符向量元胞数组。对于单行和多行注释，起始标识符必须为第一个非空白字符。对于单行注释，请指定一个标识符，以便将以该标识符开头的行视为注释。对于多行注释，从起始（第一个）标识符到结束（第二个）标识符的行被视为注释。最多只能指定两个由标识符组成的字符向量。

例如，要忽略百分号后面的行作为第一个非空白字符，请将 CommentStyle 指定为 "%"。

示例: "CommentStyle",["/*"]

示例: "CommentStyle",["/*","*/"]

ConsecutiveDelimitersRule — 管理连续分隔符的过程

"split" | "join" | "error"

管理带分隔符的文本文件中的连续分隔符的过程，指定为下表中的值之一。

值	行为
"split"	将连续分隔符拆分为多个字段。
"join"	将多个分隔符合并成一个分隔符。
"error"	返回错误并取消导入操作。

LeadingDelimitersRule — 管理前导分隔符的过程

"keep" | "ignore" | "error"

管理带分隔符的文本文件中的前导分隔符的过程，指定为下表中的值之一。

值	行为
"keep"	保留分隔符。
"ignore"	忽略分隔符。
"error"	返回错误并取消导入操作。

TrailingDelimitersRule — 管理尾部分隔符的过程

'keep' | 'ignore' | 'error'

管理带分隔符的文本文件中的尾部分隔符的过程，指定为下表中的值之一。

前导分隔符规则	行为
'keep'	保留分隔符。
'ignore'	忽略分隔符。
'error'	返回错误并中止导入操作。

Encoding — 字符编码方案

'' | 'UTF-8' | 'system' | 'ISO-8859-1' | 'windows-1251' | 'windows-1252' | ...

与文件关联的字符编码方案，指定为以逗号分隔的对组，其中包含 'Encoding' 和 'system' 或标准字符编码方案名称。

如果您没有指定任何编码，则该函数在读取文件时将使用自动字符集检测来确定编码。

示例: 'Encoding','system' 使用系统默认编码。

数据类型: char | string

替代规则

MissingRule — 管理缺失数据的过程

'fill' (默认) | 'error' | 'omitrow' | 'omitvar'

管理缺失数据的过程，指定为下表中的值之一。

缺失规则	行为
'fill'	用 FillValue 属性的内容替代缺失的数据。 FillValue 属性在要导入的变量的 VariableImportOptions 对象中指定。有关访问 FillValue 属性的详细信息，请参阅 getvaropts。
'error'	停止导入并显示一条错误消息，指出缺失的记录和字段。
'omitrow'	忽略包含缺失数据的行。
'omitvar'	忽略包含缺失数据的变量。

示例: opts.MissingRule = 'omitrow';

数据类型: char | string

EmptyLineRule — 处理空行的方式

'skip' | 'read' | 'error'

处理数据中的空行的方式，指定为 'skip'、'read' 或 'error'。导入函数将空白解释为空。

空行规则	行为
'skip'	跳过空行。
'read'	导入空行。导入函数根据 VariableWidths、VariableOptions、MissingRule 中指定的值和其他相关属性（例如 Whitespace）来解析空行。
'error'	显示错误消息并中止导入操作。

示例: opts.EmptyLineRule = 'skip';

数据类型: char | string

ImportErrorRule — 处理导入错误的过程

'fill' (默认) | 'error' | 'omitrow' | 'omitvar'

处理导入错误的过程，指定为下表中的值之一。

导入错误规则	行为
'fill'	用 FillValue 属性的内容替代出现错误的数据。 FillValue 属性在要导入的变量的 VariableImportOptions 对象中指定。有关访问 FillValue 属性的详细信息，请参阅 getvaropts。
'error'	停止导入并显示一条错误消息，指出导致出错的记录和字段。
'omitrow'	忽略发生错误的行。
'omitvar'	忽略发生错误的变量。

示例: opts.ImportErrorRule = 'omitvar';

数据类型: char | string

ExtraColumnsRule — 处理附加列的过程

'addvars' | 'ignore' | 'wrap' | 'error'

处理数据中的附加列的过程，指定为下表中的值之一。

附加列规则	行为
'addvars'	要导入附加列，需要创建新变量。如果有 N 个附加列，将以 'ExtraVar1', 'ExtraVar2',..., 'ExtraVarN' 的形式导入新变量。导入附加列数据，就好像其 VariableTypes 是 char 一样。
'ignore'	忽略附加列数据。
'wrap'	将附加列数据换行到新记录中。此操作不会更改变量的数量。
'error'	显示错误消息并中止导入操作。

数据类型: char | string

对象函数

getvaropts	获取变量导入选项
setvaropts	设置变量导入选项
setvartype	设置变量数据类型
preview	使用导入选项预览文件中的八行数据

示例

在分隔文本文件中定义变量的导入选项

定义导入选项对象以从 patients.dat 读取多个变量。

根据文件的内容，定义下列变量属性：名称、类型、分隔符、数据起始位置和附加列规则。

varNames = {'LastName','Gender','Age','Location','Height','Weight','Smoker'} ;
varTypes = {'char','categorical','int32','char','double','double','logical'} ;
delimiter = ',';
dataStartLine = 2;
extraColRule = 'ignore';

使用 delimitedTextImportOptions 函数和变量信息初始化导入选项对象 opts。

opts = delimitedTextImportOptions('VariableNames',varNames,...
                                'VariableTypes',varTypes,...
                                'Delimiter',delimiter,...
                                'DataLines', dataStartLine,...
                                'ExtraColumnsRule',extraColRule); 

将 preview 函数与导入选项对象结合使用以预览数据。

preview('patients.dat',opts)

ans=8×7 table
      LastName      Gender    Age              Location               Height    Weight    Smoker
    ____________    ______    ___    _____________________________    ______    ______    ______

    {'Smith'   }    Male      38     {'County General Hospital'  }      71       176      false 
    {'Johnson' }    Male      43     {'VA Hospital'              }      69       163      false 
    {'Williams'}    Female    38     {'St. Mary's Medical Center'}      64       131      false 
    {'Jones'   }    Female    40     {'VA Hospital'              }      67       133      false 
    {'Brown'   }    Female    49     {'County General Hospital'  }      64       119      false 
    {'Davis'   }    Female    46     {'St. Mary's Medical Center'}      68       142      false 
    {'Miller'  }    Female    33     {'VA Hospital'              }      64       142      false 
    {'Wilson'  }    Male      40     {'VA Hospital'              }      68       180      false 

使用 readtable 导入数据。

T = readtable('patients.dat',opts);
whos T

  Name        Size            Bytes  Class    Attributes

  T         100x7             30563  table              

提示

• 引入时间：

  • R2016b - DelimitedTextImportOptions 对象

  • R2018b - delimitedTextImportOptions 函数

另请参阅

函数

• readtable | detectImportOptions

实时编辑器任务

• 导入数据