本页对应的英文页面已更新,但尚未翻译。 若要查看最新内容,请点击此处访问英文页面。

fixedWidthImportOptions

等宽文本文件的导入选项对象

说明

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

创建对象

您可以使用 fixedWidthImportOptions 函数(下文介绍)或 detectImportOptions 函数创建 FixedWidthImportOptions 对象:

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

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

    opts = detectImportOptions(filename)

说明

示例

opts = fixedWidthImportOptions 使用一个变量创建 FixedWidthImportOptions 对象。

示例

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

示例

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

输入参数

全部展开

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

属性

全部展开

变量属性

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

如果数据中包含 N 个变量,但未检测到变量名称,VariableNames 属性中将包含 {'Var1','Var2',...,'VarN'}

要支持无效的 MATLAB 标识符作为变量名称,例如包含空格和非 ASCII 字符的变量名称,请将 PreserveVariableNames 参数设置为 true

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

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

数据类型: char | string | cell

保留变量名称的标志,指定为以逗号分隔的对组,由 PreserveVariableNamestruefalse 组成。

  • true - 保留作为无效 MATLAB 标识符的变量名称,如包含空格和非 ASCII 字符的变量名称。

  • false - 将无效变量名称(由 isvarname 函数确定)转换为有效的 MATLAB 标识符。

从 R2019b 开始,变量名称和行名称可以包含任何字符,包括空格和非 ASCII 字符。此外,它们可以由任何字符(而不仅仅是字母)开头。变量名称和行名称可以不是有效的 MATLAB 标识符(由 isvarname 函数决定)。要保留这些变量名称和行名称,请将 PreserveVariableNames 设置为 true

等宽文本文件中变量的字段宽度,指定为正整数值向量。该向量中的每个正整数对应于一个字段中构成变量的字符数。对于 VariableNames 属性中指定的每个变量,VariableWidths 属性中均包含一个对应的条目。

变量的数据类型,指定为字符向量元胞数组或字符串数组。VariableTypes 属性指定导入变量时要使用的数据类型。分配新值时,将 VariableTypes 指定为有效数据类型名称的元胞数组。

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

示例: opts.VariableTypes 返回当前(检测到的)变量数据类型。

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

数据类型: cell | single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | logical | char | string | categorical | datetime

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

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

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

要支持无效的 MATLAB 标识符作为变量名称,例如包含空格和非 ASCII 字符的变量名称,请将 PreserveVariableNames 参数设置为 true

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

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

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

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

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

变量选项支持以下数据类型:数值、文本、logicaldatetimecategorical

要查询变量的当前(或检测到的)选项,请使用 getvaropts 函数。

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

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

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

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

位置属性

数据位置,指定为正整数标量或由正整数标量组成的 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 = 5DataLines 属性设置为值 [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 属性指定包含行名称的列的位置。

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

示例: opts.RowNamesColumn = 2;

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

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

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

示例: opts.VariableNamesLine = 6;

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

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

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

示例: opts.VariableDescriptionsLine = 7;

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

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

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

示例: opts.VariableUnitsLine = 8;

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

带分隔符的文本属性

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

示例: 'Whitespace',' _'

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

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

示例: 'LineEnding','\n'

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

示例: 'LineEnding',{'\b',':'}

数据类型: char | string | cell

注释样式,指定为字符向量、字符串标量、字符向量元胞数组或字符串数组。

例如,要忽略同一行上百分号后面的文本,请将 CommentStyle 指定为 '%'

示例: 'CommentStyle',{'/*'}

数据类型: char | string | cell

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

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

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

数据类型: char | string

替代规则

处理数据中不完整字段的过程,指定为下表中的值之一。

不完整字段规则行为
'keep'

保留不完整字段数据并将文本转换为正确的数据类型。

在某些情况下,当导入函数无法解释不完整数据时,可能会发生转换错误。

'fill'

FillValue 属性的内容替代缺失的数据。

FillValue 属性在要导入的变量的 VariableImportOptions 对象中指定。有关访问 FillValue 属性的详细信息,请参阅 getvaropts

'omitrow'忽略包含不完整数据的行。
'omitvar'忽略包含不完整数据的变量。
'wrap'开始读取下一行字符。
'error'显示错误消息并中止导入操作。

示例: opts.PartialFieldRule = 'keep';

数据类型: char | string

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

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

示例: opts.EmptyLineRule = 'skip';

数据类型: char | string

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

缺失规则行为
'fill'

FillValue 属性的内容替代缺失的数据。

FillValue 属性在要导入的变量的 VariableImportOptions 对象中指定。有关访问 FillValue 属性的详细信息,请参阅 getvaropts

'error'停止导入并显示一条错误消息,指出缺失的记录和字段。
'omitrow'忽略包含缺失数据的行。
'omitvar'忽略包含缺失数据的变量。

示例: opts.MissingRule = 'omitrow';uint32

数据类型: char | string

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

导入错误规则行为
'fill'

FillValue 属性的内容替代出现错误的数据。

FillValue 属性在要导入的变量的 VariableImportOptions 对象中指定。有关访问 FillValue 属性的详细信息,请参阅 getvaropts

'error'停止导入并显示一条错误消息,指出导致出错的记录和字段。
'omitrow'忽略发生错误的行。
'omitvar'忽略发生错误的变量。

示例: opts.ImportErrorRule = 'omitvar';

数据类型: char | string

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

附加列规则行为
'addvars'

要导入附加列,需要创建新变量。如果有 N 个附加列,将以 'ExtraVar1', 'ExtraVar2',..., 'ExtraVarN' 的形式导入新变量。

注意:附加列作为 char 数据类型的文本导入。

'ignore'忽略附加列数据。
'wrap'将附加列数据换行到新记录中。此操作不会更改变量的数量。
'error'显示错误消息并中止导入操作。

数据类型: char | string

对象函数

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

示例

全部折叠

检查等宽的格式化文本文件、初始化导入选项对象,然后使用该对象导入文本文件中的表。

加载并预览等宽文本文件

加载文件 fixed_width_patients_subset_perfect.txt 并在文本编辑器中预览其内容。屏幕截图显示该文件包含等宽的格式化数据。

filename = 'fixed_width_patients_subset_perfect.txt';

检查并提取等宽文件的属性

等宽文本文件包含按开始位置、变量数目、变量名称和变量宽度组织的表格数据。可以捕获这些属性以及变量需要的数据类型。

DataStartLine = 2;
NumVariables = 7;
VariableNames  = {'LastName','Gender','Age','Location','Height',...
                                                      'Weight','Smoker'};
VariableWidths = [ 10,     7,     4,    26,     7, ...
                                                         7,     7 ] ;                                                  
DataType       = {'char','categorical','double','char','double',...
                                                     'double','logical'};

初始化并配置 FixedWidthImportOptions 对象

初始化一个 FixedWidthImportOptions 对象并配置其属性,以便与 fixed_width_patients_subset_perfect.txt 中的数据的属性相匹配。

opts = fixedWidthImportOptions('NumVariables',NumVariables,...
                               'DataLines',DataStartLine,...
                               'VariableNames',VariableNames,...
                               'VariableWidths',VariableWidths,...
                               'VariableTypes',DataType);

导入表

使用 readtable 函数和 FixedWidthImportOptions 对象导入表。

T = readtable(filename,opts)
T=10×7 table
      LastName      Gender    Age              Location               Height    Weight    Smoker
    ____________    ______    ___    _____________________________    ______    ______    ______

    {'Smith'   }    Male      38     {'County General Hospital'  }      71       176      true  
    {'Johnson' }    Male      43     {'VA Hospital'              }      69       163      false 
    {'Williams'}    Female    38     {'St. Mary's Medical Center'}      64       131      false 
    {'Brown'   }    Female    49     {'County General Hospital'  }      64       119      false 
    {'Miller'  }    Female    33     {'VA Hospital'              }      64       142      true  
    {'Wilson'  }    Male      40     {'VA Hospital'              }      68       180      false 
    {'Taylor'  }    Female    31     {'County General Hospital'  }      66       132      false 
    {'Thomas'  }    Female    42     {'St. Mary's Medical Center'}      66       137      false 
    {'Jackson' }    Male      25     {'VA Hospital'              }      71       174      false 
    {'Clark'   }    Female    48     {'VA Hospital'              }      65       133      false 

定义一个导入选项对象,以便从等宽格式化文本文件中导入杂乱的数据。配置该对象以处理杂乱的数据,并使用它来导入表。

加载并预览等宽文本文件

加载文件 fixed_width_patients_subset_messy.txt 并在文本编辑器中预览其内容。屏幕截图如下所示。屏幕截图显示该文件包含:

  • 空行 - 第 7 行、第 12 行和第 13 行

  • 附加列 - 第 8 列

  • 缺失数据 - 第 1 行、第 4 行、第 9 行和第 11 行

  • 不完整字段 - 最后 3 行

filename = 'fixed_width_patients_subset_messy.txt';

检查并捕获等宽文件的属性

等宽文本文件包含按开始位置、变量数目、变量名称和变量宽度组织的表格数据。可以捕获这些属性以及要为变量使用的数据类型。

DataStartLine = 2;  
NumVariables = 7;
VariableNames  = {'LastName','Gender','Age','Location','Height',...
                                                      'Weight','Smoker'};
VariableWidths = [ 10,     7,     4,    26,     7, ...
                                                         7,     7 ] ;                                                  
DataType       = {'char','categorical','double','char','double',...
                                                     'double','logical'};

初始化 FixedWidthImportOptions 对象并设置变量属性

初始化一个 FixedWidthImportOptions 对象并配置其属性,以便与数据的属性相匹配。

opts = fixedWidthImportOptions('NumVariables',NumVariables,...
                               'DataLines',DataStartLine,...
                               'VariableNames',VariableNames,...
                               'VariableWidths',VariableWidths,...
                               'VariableTypes',DataType);

设置 EmptyLinesRule Missing RuleExtraColumnsRule

通过将 EmptyLineRule 设置为 'read',读取数据中的空行。接下来,通过将 MissingRule 设置为 'fill',用预定义的值填充缺失实例。最后,要在导入过程中忽略多余列,请将 ExtraColumnsRule 设置为 'ignore'。有关这些属性及其值的详细信息,请参阅有关 FixedWidthImportOptions 的文档。

opts.EmptyLineRule = 'read';
opts.MissingRule = 'fill'; 
opts.ExtraColumnsRule ='ignore';

设置 PartialFieldRule

如果导入函数在遍历完整个变量宽度之前遇到行结束字符,就会出现不完整字段。例如,在此预览中,fixed_width_patients_subset_messy.txt 文件的最后三行就属于这种情况。这里,在最后一列的最后一行中,在该字段的头两个位置之后、在到达完整的变量宽度(三个位置)之前,出现了行结束字符。

出现这种不完整字段有时可能意味着出现错误。因此,可以使用 PartialFieldRule 决定如何处理这些数据。要保留不完整字段数据并将其转换为正确的数据类型,请将 PartialFieldRule 设置为 'keep'。有关 PartialFieldRule 的详细信息,请参阅有关 FixedWidthImportOptions 的文档。

opts.PartialFieldRule = 'keep';

导入表

使用 readtable 函数和 FixedWidthImportOptions 对象导入表并预览数据。

T = readtable(filename,opts)
T=15×7 table
      LastName        Gender       Age              Location               Height    Weight    Smoker
    ____________    ___________    ___    _____________________________    ______    ______    ______

    {'Smith'   }    Male            38    {'County General Hospital'  }      71       176      true  
    {'Johnson' }    Male            43    {'VA Hospital'              }      69       163      false 
    {'Williams'}    Female          38    {'St. Mary's Medical Center'}     NaN       NaN      false 
    {'Jones'   }    Female          40    {'VA Hospital'              }      67       133      false 
    {'Brown'   }    Female          49    {'County General Hospital'  }      64       119      false 
    {0×0 char  }    <undefined>    NaN    {0×0 char                   }     NaN       NaN      false 
    {'Wilson'  }    Male            40    {'VA Hospital'              }      68       180      false 
    {'Moore'   }    Male            28    {'St. Mary's Medical Center'}     NaN       183      false 
    {'Taylor'  }    Female          31    {'County General Hospital'  }      66       132      false 
    {'Anderson'}    Female          45    {'County General Hospital'  }      68       NaN      false 
    {0×0 char  }    <undefined>    NaN    {0×0 char                   }     NaN       NaN      false 
    {0×0 char  }    <undefined>    NaN    {0×0 char                   }     NaN       NaN      false 
    {'White'   }    Male            39    {'VA Hospital'              }      72         2      false 
    {'Harris'  }    Female          36    {'St. Mary's Medical Center'}      65        12      false 
    {'Martin'  }    Male            48    {'VA Hospital'              }      71       181      true  

提示

  • 引入时间:

    • R2017a - FixedWidthImportOptions 对象

    • R2018b - fixedWidthImportOptions 函数