Main Content

setvaropts

设置变量导入选项

说明

opts = setvaropts(opts,Name,Value) 根据 Name,Value 参量中的设定更新 opts 对象中的所有变量,并返回 opts 对象。

opts = setvaropts(opts,selection,Name,Value) 根据 Name,Value 参量中的指定,更新并返回 selection 参量中指定的变量的 opts

示例

示例

全部折叠

创建一个导入选项对象、为选定的变量设置选项,并使用自定义的选项和 readtable 函数导入数据。

为电子表格 patients.xls 创建一个选项对象。

opts = detectImportOptions('patients.xls');

SmokerDiastolicSystolic 变量设置 FillValue 属性。

opts = setvaropts(opts,'Smoker','FillValue',false);
opts = setvaropts(opts,{'Diastolic','Systolic'},'FillValue',0);

选择要导入的变量。

opts.SelectedVariableNames = {'Smoker','Diastolic','Systolic'};

导入变量并显示摘要。

T = readtable('patients.xls',opts); 
summary(T) 
T: 100x3 table

Variables:

    Smoker: logical (34 true)
    Diastolic: double
    Systolic: double

Statistics for applicable variables:

                 NumMissing      Min        Median         Max          Mean           Std    

    Diastolic        0            68        81.5000         99         82.9600        6.9325  
    Systolic         0           109            122        138        122.7800        6.7128  

导入包含缺失或不完整字段的数据需要识别缺失的实例,并决定如何导入缺失的实例。可使用 importOptions 捕获这些决定,并使用 readtable 获取数据。

为文件创建一个导入选项对象、更新那些控制缺失数据导入的属性,然后使用 readtable 导入数据。请注意,数据集 airlinesmall_subset.csv 有两个数值变量(ArrDelayDepDelay)包含缺失数据,由 NA 指示。

airlinesmall_subset_NA_screenshot.png

从文件中创建一个导入选项对象。

opts = detectImportOptions("airlinesmall_subset.csv");

使用 TreatAsMissing 属性指定数据中作为缺失数据占位符的字符。在此示例中,两个数值变量 ArrDelayDepDelay 包含缺失字段,其中包含文本 NA

opts = setvaropts(opts,["ArrDelay","DepDelay"],"TreatAsMissing","NA");

指定导入函数导入缺失实例时要执行的操作。要了解更多选项,请参阅 ImportOptions 属性页。

opts.MissingRule = "fill";

指定导入函数发现缺失实例时要使用的值。这里,变量 ArrDelayDepDelay 中的缺失实例被替换为 0

opts = setvaropts(opts,["ArrDelay","DepDelay"],"FillValue",0);

选择您要使用的变量,并使用 readtable 导入它们。

opts.SelectedVariableNames = ["ArrDelay","DepDelay"]; 
T = readtable("airlinesmall_subset.csv",opts);

检查 ArrDelayDepDelay 中的值。验证导入函数已替换由 NA 指示的缺失值。

T(42:55,:)
ans=14×2 table
    ArrDelay    DepDelay
    ________    ________

        3          -4   
        0          -1   
       11          11   
        0           0   
        0           0   
        0           0   
       -9           5   
       -9          -3   
        2           6   
        0           0   
        1           1   
        0           4   
        9           0   
       -2           4   

readtable 函数自动检测具有 0x0b 前缀的十六进制和二进制数字。要导入这些数字不带前缀的形式,请使用导入选项对象。

为文件 hexAndBinary.txt 创建一个导入选项对象。其第三列包含十六进制数字,不带 0x 前缀。

opts = detectImportOptions('hexAndBinary.txt')
opts = 
  DelimitedTextImportOptions with properties:

   Format Properties:
                    Delimiter: {','}
                   Whitespace: '\b\t '
                   LineEnding: {'\n'  '\r'  '\r\n'}
                 CommentStyle: {}
    ConsecutiveDelimitersRule: 'split'
        LeadingDelimitersRule: 'keep'
       TrailingDelimitersRule: 'ignore'
                EmptyLineRule: 'skip'
                     Encoding: 'UTF-8'

   Replacement Properties:
                  MissingRule: 'fill'
              ImportErrorRule: 'fill'
             ExtraColumnsRule: 'addvars'

   Variable Import Properties: Set types by name using setvartype
                VariableNames: {'Var1', 'Var2', 'Var3' ... and 1 more}
                VariableTypes: {'auto', 'auto', 'char' ... and 1 more}
        SelectedVariableNames: {'Var1', 'Var2', 'Var3' ... and 1 more}
              VariableOptions: [1-by-4 matlab.io.VariableImportOptions] 
	Access VariableOptions sub-properties using setvaropts/getvaropts
           VariableNamingRule: 'modify'

   Location Properties:
                    DataLines: [1 Inf]
            VariableNamesLine: 0
               RowNamesColumn: 0
            VariableUnitsLine: 0
     VariableDescriptionsLine: 0 
	To display a preview of the table, use preview

要指定第三列应作为十六进制值导入,即使缺失前缀也要导入,请使用 setvaropts 函数。将第三个变量的变量类型设置为 int32。将用于导入第三列的进制设置为 hex

opts = setvaropts(opts,3,'NumberSystem','hex','Type','int32')
opts = 
  DelimitedTextImportOptions with properties:

   Format Properties:
                    Delimiter: {','}
                   Whitespace: '\b\t '
                   LineEnding: {'\n'  '\r'  '\r\n'}
                 CommentStyle: {}
    ConsecutiveDelimitersRule: 'split'
        LeadingDelimitersRule: 'keep'
       TrailingDelimitersRule: 'ignore'
                EmptyLineRule: 'skip'
                     Encoding: 'UTF-8'

   Replacement Properties:
                  MissingRule: 'fill'
              ImportErrorRule: 'fill'
             ExtraColumnsRule: 'addvars'

   Variable Import Properties: Set types by name using setvartype
                VariableNames: {'Var1', 'Var2', 'Var3' ... and 1 more}
                VariableTypes: {'auto', 'auto', 'int32' ... and 1 more}
        SelectedVariableNames: {'Var1', 'Var2', 'Var3' ... and 1 more}
              VariableOptions: [1-by-4 matlab.io.VariableImportOptions] 
	Access VariableOptions sub-properties using setvaropts/getvaropts
           VariableNamingRule: 'modify'

   Location Properties:
                    DataLines: [1 Inf]
            VariableNamesLine: 0
               RowNamesColumn: 0
            VariableUnitsLine: 0
     VariableDescriptionsLine: 0 
	To display a preview of the table, use preview

读取文件并将前三列作为数值导入。readtable 函数自动检测包含第一列和第二列包含十六进制和二进制值。导入选项对象指定第三列也包含十六进制值。

T = readtable('hexAndBinary.txt',opts)
T=3×4 table
    Var1     Var2    Var3        Var4    
    _____    ____    _____    ___________

      255    255     51193    {'Device1'}
      256      4      1471    {'Device2'}
    43981    129     61455    {'Device3'}

可使用 setvaropts 函数来更新那些控制文本数据导入的属性。首先,获取文件的导入选项对象。然后,检查并更新文本变量的选项。最后,使用 readtable 函数导入变量。

预览 patients.xls 中的数据。请注意 LastName 列中的文本数据。这里只显示前 10 行的预览。

获取导入选项对象。

opts = detectImportOptions('patients.xls');

获取并检查变量 LastNameVariableImportOptions

getvaropts(opts,'LastName')
ans = 
  TextVariableImportOptions with properties:

   Variable Properties:
              Name: 'LastName'
              Type: 'char'
         FillValue: ''
    TreatAsMissing: {}
         QuoteRule: 'remove'
          Prefixes: {}
          Suffixes: {}
    EmptyFieldRule: 'missing'

   String Options:
    WhitespaceRule: 'trim'

将该变量的数据类型设置为 string

opts = setvartype(opts,'LastName','string');

设置该变量的 FillValue 属性,将缺失值替换为 'NoName'

opts = setvaropts(opts,'LastName','FillValue','NoName');

选择、读取并显示该变量的前 10 行的预览。

opts.SelectedVariableNames = 'LastName';
T = readtable('patients.xls',opts); 
T.LastName(1:10)
ans = 10x1 string
    "Smith"
    "Johnson"
    "Williams"
    "Jones"
    "Brown"
    "Davis"
    "Miller"
    "Wilson"
    "Moore"
    "Taylor"

可使用 setvaropts 函数来更新那些控制 logical 数据导入的属性。首先,获取文件的导入选项对象。然后,检查并更新逻辑变量的选项。最后,使用 readtable 函数导入变量。

预览 airlinesmall_subset.xlsx 中的数据。请注意 Cancelled 列中的逻辑数据。这里只显示从第 30 行到第 40 行的预览。

获取导入选项对象。

opts = detectImportOptions('airlinesmall_subset.xlsx');

获取并检查变量 CancelledVariableImportOptions

getvaropts(opts,'Cancelled')
ans = 
  NumericVariableImportOptions with properties:

   Variable Properties:
                  Name: 'Cancelled'
                  Type: 'double'
             FillValue: NaN
        TreatAsMissing: {}
             QuoteRule: 'remove'
              Prefixes: {}
              Suffixes: {}
        EmptyFieldRule: 'missing'

   Numeric Options:
     ExponentCharacter: 'eEdD'
      DecimalSeparator: '.'
    ThousandsSeparator: ''
        TrimNonNumeric: 0
          NumberSystem: 'decimal'

将该变量的数据类型设置为 logical

opts = setvartype(opts,'Cancelled','logical');

设置该变量的 FillValue 属性,将缺失值替换为 true

opts = setvaropts(opts,'Cancelled','FillValue',true);

选择、读取并显示变量摘要。

opts.SelectedVariableNames = 'Cancelled';
T = readtable('airlinesmall_subset.xlsx',opts); 
summary(T)
T: 1338x1 table

Variables:

    Cancelled: logical (29 true)

可使用 DatetimeVariableImportOptions 属性来控制 datetime 数据的导入。首先,获取文件的 ImportOptions 对象。然后,检查并更新日期时间变量的 VariableImportOptions。最后,使用 readtable 导入变量。

预览 outages.csv 中的数据。请注意 OutageTimeRestorationTime 列中的日期时间数据。这里只显示前 10 行。

获取导入选项对象。

opts = detectImportOptions('outages.csv');

获取并检查日期时间变量 OutageTimeRestorationTimeVariableImportOptions

varOpts = getvaropts(opts,{'OutageTime','RestorationTime'})
varOpts = 
  1x2 DatetimeVariableImportOptions array with properties:

    Name
    Type
    FillValue
    TreatAsMissing
    QuoteRule
    Prefixes
    Suffixes
    EmptyFieldRule
    DatetimeFormat
    DatetimeLocale
    TimeZone
    InputFormat

设置变量的 FillValue 属性,将缺失值替换为当前日期时间。

opts = setvaropts(opts,{'OutageTime','RestorationTime'},...
                                           'FillValue','now');

选择、读取并预览这两个变量。请注意,RestorationTime 第二行的缺失值已填入当前日期时间。

opts.SelectedVariableNames = {'OutageTime','RestorationTime'};
T = readtable('outages.csv',opts); 
T(1:10,:)
ans=10×2 table
       OutageTime       RestorationTime 
    ________________    ________________

    2002-02-01 12:18    2002-02-07 16:50
    2003-01-23 00:49    2024-07-20 15:28
    2003-02-07 21:15    2003-02-17 08:14
    2004-04-06 05:44    2004-04-06 06:10
    2002-03-16 06:18    2002-03-18 23:23
    2003-06-18 02:49    2003-06-18 10:54
    2004-06-20 14:39    2004-06-20 19:16
    2002-06-06 19:28    2002-06-07 00:51
    2003-07-16 16:23    2003-07-17 01:12
    2004-09-27 11:09    2004-09-27 16:37

可使用 setvaropts 函数来更新那些控制 categorical 数据导入的属性。首先,获取文件的导入选项对象。然后,检查并更新分类变量的选项。最后,使用 readtable 函数导入变量。

预览 outages.csv 中的数据。请注意 RegionCause 列中的分类数据。此表只显示前 10 行。

获取导入选项对象。

opts = detectImportOptions('outages.csv');

获取并检查变量 RegionCause 的选项。

getvaropts(opts,{'Region','Cause'})
ans = 
  1x2 TextVariableImportOptions array with properties:

    Name
    Type
    FillValue
    TreatAsMissing
    QuoteRule
    Prefixes
    Suffixes
    EmptyFieldRule
    WhitespaceRule

将变量的数据类型设置为 categorical

opts = setvartype(opts,{'Region','Cause'},'categorical');

设置变量的 FillValue 属性,将缺失值替换为类别名称 'Miscellaneous'。将 TreatAsMissing 属性设置为 'unknown'

opts = setvaropts(opts,{'Region','Cause'},...
                                   'FillValue','Miscellaneous',...
                                   'TreatAsMissing','unknown');

选择、读取并显示这两个变量的摘要。

opts.SelectedVariableNames = {'Region','Cause'};
T = readtable('outages.csv',opts); 
summary(T)
T: 1468x2 table

Variables:

    Region: categorical (5 categories)
    Cause: categorical (10 categories)

Statistics for applicable variables:

              NumMissing

    Region        0     
    Cause         0     

导入表格数据,其中包含的变量带有不需要的前缀和后缀字符。首先,创建导入选项对象并预览数据。然后,选择感兴趣的变量并设置其变量类型和属性,以删除不需要的字符。最后,导入感兴趣的数据。

为文件创建导入选项并预览表格。

filename = 'pref_suff_trim.csv';
opts = detectImportOptions(filename);
preview(filename,opts)
Warning: Column headers from the file were modified to make them valid MATLAB identifiers before creating variable names for the table. The original column headers are saved in the VariableDescriptions property.
Set 'VariableNamingRule' to 'preserve' to use the original column headers as table variable names.
ans=8×5 table
              Time                   DayOfWeek            Power         Total_Fees      Temperature 
    _________________________    _________________    ______________    ___________    _____________

    {'Timestamp:1/1/06 0:00'}    {'& Sun %20'}    {'54.5448 MW'}    {'$1.23'  }    {'-7.2222 C'}
    {'Timestamp:1/2/06 1:00'}    {'& Thu %20'}    {'.3898 MW'  }    {'$300.00'}    {'-7.3056 C'}
    {'Timestamp:1/3/06 2:00'}    {'& Sun %20'}    {'51.6344 MW'}    {'£2.50'  }    {'-7.8528 C'}
    {'Timestamp:1/4/06 3:00'}    {'& Sun %20'}    {'51.5597 MW'}    {'$0.00'  }    {'-8.1778 C'}
    {'Timestamp:1/5/06 4:00'}    {'& Wed %20'}    {'51.7148 MW'}    {'¥4.00'  }    {'-8.9343 C'}
    {'Timestamp:1/6/06 5:00'}    {'& Sun %20'}    {'52.6898 MW'}    {'$0.00'  }    {'-8.7556 C'}
    {'Timestamp:1/7/06 6:00'}    {'& Mon %20'}    {'55.341 MW' }    {'$50.70' }    {'-8.0417 C'}
    {'Timestamp:1/8/06 7:00'}    {'& Sat %20'}    {'57.9512 MW'}    {'$0.00'  }    {'-8.2028 C'}

选择感兴趣的变量,指定其类型,并检查其变量导入选项值。

opts.SelectedVariableNames = {'Time','Total_Fees','Temperature'};
opts = setvartype(opts,'Time','datetime');
opts = setvaropts(opts,'Time','InputFormat','MM/dd/uu HH:mm'); % Specify datetime format
opts = setvartype(opts,{'Total_Fees','Temperature'},'double');
getvaropts(opts,{'Time','Total_Fees','Temperature'})
ans = 
    1×3 VariableImportOptions array with properties:

   Variable Options:
                         (1) |          (2) |           (3)
            Name:     'Time' | 'Total_Fees' | 'Temperature'
            Type: 'datetime' |     'double' |      'double'
       FillValue:        NaT |          NaN |           NaN
  TreatAsMissing:         {} |           {} |            {}
  EmptyFieldRule:  'missing' |    'missing' |     'missing'
       QuoteRule:   'remove' |     'remove' |      'remove'
        Prefixes:         {} |           {} |            {}
        Suffixes:         {} |           {} |            {}

	To access sub-properties of each variable, use getvaropts

将变量导入选项设置为 PrefixesSuffixesTrimNonNumeric 属性,以便从变量 Time 中删除 'Timestamp:',从变量 Temperature 中删除后缀 'C',并从变量 Total_Fees 中删除所有非数值字符。使用新的导入选项预览表格。

opts = setvaropts(opts,'Time','Prefixes','Timestamp:');
opts = setvaropts(opts,'Temperature','Suffixes','C');
opts = setvaropts(opts,'Total_Fees','TrimNonNumeric',true);
preview(filename,opts)
ans=8×3 table
         Time         Total_Fees    Temperature
    ______________    __________    ___________

    01/01/06 00:00       1.23         -7.2222  
    01/02/06 01:00        300         -7.3056  
    01/03/06 02:00        2.5         -7.8528  
    01/04/06 03:00          0         -8.1778  
    01/05/06 04:00          4         -8.9343  
    01/06/06 05:00          0         -8.7556  
    01/07/06 06:00       50.7         -8.0417  
    01/08/06 07:00          0         -8.2028  

使用 readtable 导入数据。

T = readtable(filename,opts);

为包含空字段的文件创建导入选项对象。使用 EmptyFieldRule 参数来管理数据中空字段的导入。首先,预览数据,然后为特定变量设置 EmptyFieldRule 参数。最后,为所有变量设置 EmptyFieldRule 并导入数据。

为包含空字段的文件创建导入选项对象。使用 preview 函数获取表的前八行。EmptyFieldRule 的默认值是 'missing'。因此,导入函数将空字段视为缺失,并将这些字段替换为该变量的 FillValue 值。使用 VariableOptions 作为第三个变量,预览数据。此处,preview 函数将第三个变量中的空字段导入为 NaN

filename = 'DataWithEmptyFields.csv';
opts = detectImportOptions(filename);
opts.VariableOptions(3) % Display the Variable Options for the 3rd Variable
ans = 
  NumericVariableImportOptions with properties:

   Variable Properties:
                  Name: 'Double'
                  Type: 'double'
             FillValue: NaN
        TreatAsMissing: {}
             QuoteRule: 'remove'
              Prefixes: {}
              Suffixes: {}
        EmptyFieldRule: 'missing'

   Numeric Options:
     ExponentCharacter: 'eEdD'
      DecimalSeparator: '.'
    ThousandsSeparator: ''
        TrimNonNumeric: 0
          NumberSystem: 'decimal'

preview(filename,opts)
ans=8×7 table
       Text       Categorical    Double     Datetime      Logical      Duration      String  
    __________    ___________    ______    __________    __________    ________    __________

    {'abc'   }    {'a'     }        1      01/14/0018    {'TRUE'  }    00:00:01    {'abc'   }
    {0x0 char}    {'b'     }        2      01/21/0018    {'FALSE' }    09:00:01    {'def'   }
    {'ghi'   }    {0x0 char}        3      01/31/0018    {'TRUE'  }    02:00:01    {'ghi'   }
    {'jkl'   }    {'a'     }      NaN      02/23/2018    {'FALSE' }    03:00:01    {'jkl'   }
    {'mno'   }    {'a'     }        4             NaT    {'FALSE' }    04:00:01    {'mno'   }
    {'pqr'   }    {'b'     }        5      01/23/0018    {0x0 char}    05:00:01    {'pqr'   }
    {'stu'   }    {'b'     }        5      03/23/0018    {'FALSE' }         NaN    {'stu'   }
    {0x0 char}    {'a'     }        6      03/24/2018    {'TRUE'  }    07:00:01    {0x0 char}

为表中的第二个变量设置 EmptyFieldRule。首先,选择该变量,然后将 EmptyFieldRule 设置为 'auto'。此处,readtable 函数将 categorical 变量的空字段导入为 <undefined>

opts.SelectedVariableNames = 'Categorical'; 
opts = setvartype(opts,'Categorical','categorical'); 
opts = setvaropts(opts,'Categorical','EmptyFieldRule','auto');
T = readtable(filename,opts)
T=10×1 table
    Categorical
    ___________

    a          
    b          
    <undefined>
    a          
    a          
    b          
    b          
    a          
    a          
    <undefined>

接下来,为表中的所有变量设置 EmptyFieldRule 参数。首先,适当地更新变量的数据类型。对于此示例,将第五个和第七个变量的数据类型分别设置为 logicalstring。然后,将所有变量的 EmptyFieldRule 设置为 'auto'。导入函数根据变量的数据类型导入空字段。此处,readtable 函数将 logical 变量的空字段导入为 0,将 categorical 变量的空字段导入为 <undefined>

VariableNames = opts.VariableNames;
opts.SelectedVariableNames =  VariableNames; % select all variables
opts = setvartype(opts,{'Logical','String'},{'logical','string'});
opts = setvaropts(opts,VariableNames,'EmptyFieldRule','auto');
T = readtable(filename,opts)
T=10×7 table
       Text       Categorical    Double     Datetime     Logical    Duration     String  
    __________    ___________    ______    __________    _______    ________    _________

    {'abc'   }    a                 1      01/14/0018     true      00:00:01    "abc"    
    {0x0 char}    b                 2      01/21/0018     false     09:00:01    "def"    
    {'ghi'   }    <undefined>       3      01/31/0018     true      02:00:01    "ghi"    
    {'jkl'   }    a               NaN      02/23/2018     false     03:00:01    "jkl"    
    {'mno'   }    a                 4             NaT     false     04:00:01    "mno"    
    {'pqr'   }    b                 5      01/23/0018     false     05:00:01    "pqr"    
    {'stu'   }    b                 5      03/23/0018     false          NaN    "stu"    
    {0x0 char}    a                 6      03/24/2018     true      07:00:01    ""       
    {0x0 char}    a                 7      03/25/2018     true      08:00:01    <missing>
    {'xyz'   }    <undefined>     NaN             NaT     true      06:00:01    "xyz"    

'missing''auto' 外,还可以将 EmptyFieldRule 参数设置为 'error'。将其设置为 'error' 时,readtable 函数将按照 ImportErrorRule 参数中指定的过程导入空字段。

输入参数

全部折叠

文件导入选项,指定为 detectImportOptions 函数创建的 SpreadsheetImportOptionsDelimitedTextImportOptionsFixedWidthImportOptions 对象。opts 对象包含控制数据导入过程的属性,例如变量属性、数据位置属性、替代规则等。

选定的变量,指定为字符向量、字符串标量、字符向量元胞数组、字符串数组、数值索引数组或逻辑数组。

变量的名称(或索引)必须为 opts 对象的 VariableNames 属性中包含的名称的子集。

示例: 'Height'

示例: {'Height','LastName'}

示例: [5 9]

数据类型: char | string | cell | uint64 | logical

名称-值参数

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

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

示例: opts = setvaropts(opts,'Weight','FillValue',0) 将变量 WeightFillValue 设置为 0

所有变量类型的通用选项

全部折叠

变量的数据类型,指定为下表中列出的数据类型。

数据类型

描述

'char'

'string'

文本。

'single'

'double'

单精度或双精度浮点数。

'int8', 'int16', 'int32', 'int64'

'uint8', 'uint16', 'uint32', 'uint64'

有符号或无符号整数,存储为 8 位、16 位、32 位或 64 位整数。

整数数据类型不定义与浮点数 NaN-Inf+Inf 对应的值。因此,当您将浮点数据作为整数数组导入时,导入函数会转换未定义的浮点数:

  • NaN 被转换为 0

  • -Inf 使用 intmin 函数转换为指定整数数据类型的最小整数。

  • +Inf 使用 intmax 函数转换为指定整数数据类型的最大整数。

'logical'

true 或 false 值(例如,truefalse10)。

'datetime'

指定时间点的日期时间(例如,2019-12-10 09:12:56 指定 2019 年 12 月 10 日上午 9:12:56)。

'duration'

时间长度(例如,05:13:45 指定 5 小时 13 分 45 秒)。

'categorical'

指定类别的数字或文本数据(例如,'red''green''blue' 指定三个类别的名称)。

缺失数据的替换值,取决于变量的类型,指定为字符向量、字符串标量、数值标量或者逻辑值 truefalse

变量的类型描述
文本

替换文本,指定为字符向量或字符串标量。

示例:'not applicable'

数值

要替换缺失实例的数值标量

导入函数将 FillValue 的输入转换为由变量的 Type 属性指定的数据类型。例如,如果 Type 属性值为 uint8,导入函数也会将 FillValue 属性的值转换为 uint8

示例:0

逻辑值

truefalse

示例:false

日期时间

代表日期时间数据的字符向量、字符串标量或标量值。有关有效 datetime 输入的详细信息,请参阅 datetime 函数页。

示例:'now' 将缺失的日期时间实例设置为当前日期时间。

示例:[1998 12 1] 将缺失的日期时间实例设置为 1998 年 12 月 1 日。

持续时间

表示持续时间数据的字符向量、字符串标量或标量值。有关有效 duration 输入的详细信息,请参阅 duration 函数页。

示例:'12:30:16' 将缺失的持续时间实例设置为 12 小时 30 分钟 16 秒。

分类

字符向量或字符串标量,包含要用于替换类别的名称。

示例:'Miscellaneous' 将类别名称 Miscellaneous 赋给分类数据中缺失的实例。

要指定如何导入缺失的、无法转换的或导致错误的数据,请结合使用以下四个属性:FillValueTreatAsMissingMissingRuleErrorRule。在以下情况下,导入函数将使用 FillValue 属性中指定的值:

  • 数据无法转换,或者与 TreatAsMissing 中的值匹配。

  • MissingRuleErrorRule 设置为 fill

要解释为缺失数据的文本,指定为字符向量、字符串标量、字符向量元胞数组或字符串数组。

当导入函数发现缺失实例后,将根据 MissingRule 属性中的指定确定适当的操作。

示例: 'TreatAsMissing',{'NA','TBD'} 指示导入函数将 NATBD 的任何实例都视为缺失字段。

数据类型: char | string | cell

管理数据中的双引号的过程,指定为下表中的值之一。

引号规则处理
'remove'

在删除前导空白后,如果字符用双引号 (") 引起,导入函数将同时删除左侧双引号和被视为右侧双引号的下一个双引号。

示例"The" Example Text 导入为 The Example Text

示例The "Example" Text 导入为 The "Example" Text

如果字符用两组双引号 ("") 引起,导入函数将删除前面两个双引号。

示例""abc"" 导入为 abc""

示例"The" "Example" Text 导入为 The "Example" Text

示例The "Example" "Text" 导入为 The "Example" "Text"

如果字符用一对双引号引起,后面还有一个不成对的双引号,导入函数将忽略这个不成对的双引号。

示例"abc"" 导入为 abc"

示例"abc"def" 导入为 abcdef"

外层双引号内嵌套的转义双引号(两个双引号)将替换为单个双引号。

示例"The ""Example"" ""Text""" 导入为 The "Example" "Text"

'keep'

保留所有引号。

'error'转换以双引号 (") 开头的数据时报告错误。如果不允许用引号将字段引起,可以使用此设置。

数据类型: char | string

管理数据中空字段的过程,指定为下列值之一:

  • 'missing' - 将空字段视为 missing 值,并按照 MissingRule 属性中指定的过程进行操作。

  • 'error' - 将空字段视为导入错误,并按照 ImportErrorRule 属性中指定的过程进行操作。

  • 'auto' - 根据变量的数据类型导入空字段。将空文本值作为空(零长度)字符向量或字符串导入。将空分类值作为未定义的分类值导入。使用 ImportErrorRule 属性指定的过程导入所有其他数据类型。

示例: opts = setvaropts(opts,'RestorationTime','EmptyFieldRule','auto');

数据类型: char | string

要从变量值的前缀位置删除的文本,指定为字符向量、字符向量元胞数组、字符串标量或字符串数组。

示例: opts = setvaropts(opts,'Var1','Prefixes','$') 为变量 Var1 设置 Prefixes 选项。如果 Var1 包含值 '$500',则 readtable 将其读取为 '500'

数据类型: char | string | cell

要从变量值的后缀位置删除的文本,指定为字符向量、字符向量元胞数组、字符串标量或字符串数组。

示例: opts = setvaropts(opts,'Var1','Suffixes','/-') 为变量 Var1 设置 Suffixes 选项。如果 Var1 包含值 '$500/-',则 readtable 将其读取为 '$500'

数据类型: char | string | cell

文本变量选项

全部折叠

导入文本数据时管理前导和尾随空白的过程,指定为下表中的值之一。

空白规则处理
'trim'

删除文本中的任何前导或尾随空白。内部空白不受影响。

示例:' World Time ' 导入为 'World Time'

'trimleading'

仅删除前导空白。

示例:' World Time ' 导入为 'World Time '

'trimtrailing'

仅删除尾随空白。

示例:' World Time ' 导入为 ' World Time'

'preserve'

保留空白。

示例:' World Time ' 导入为 ' World Time '

数据类型: char | string

数值变量选项

全部折叠

表示指数的字符,指定为字符向量或字符串标量。导入函数使用 ExponentCharacter 属性来识别用科学记数法表示的数字中代表指数的字符。

示例: 如果 varOpts.ExponentCharacter = 'a',则导入函数将文本 "1.2a3" 导入为数字 1200

数据类型: char | string

表示数值变量中小数分隔符的字符,指定为字符向量或字符串标量。导入函数使用 DecimalSeparator 名称-值对组中指定的字符来区分数字的整数部分和小数部分。

转换为整数数据类型时,带小数部分的数字将被舍入为最接近的整数。

示例: 如果名称-值对组指定为 'DecimalSeparator',',',则导入函数将文本 "3,14159" 导入为数字 3.14159

数据类型: char | string

表示数值变量中千分位的字符,指定为字符向量或字符串标量。千分位字符作为视觉分隔符,将数字按三位数一组进行分组。导入函数使用 ThousandsSeparator 名称-值对组中指定的字符来解释要导入的数字。

示例: 如果名称-值对组指定为 'ThousandsSeparator',',',则导入函数将文本 "1,234,000" 导入为 1234000

数据类型: char | string

从数值变量中删除非数值字符,指定为逻辑值 truefalse

示例: 如果名称-值对组指定为 'TrimNonNumeric',true,则导入函数将 '$500/-' 读取为 500

数据类型: logical

用于解释数值变量的进制,指定为 'decimal''hex''binary'

'NumberSystem' 的值

描述

'decimal'

  • 将输入数值变量视为十进制值。

  • 将值解释为由 'Type' 名称-值对组指定的数据类型,如果未指定 'Type',则解释为 'double' 数据类型。

'hex'

  • 将输入数值变量视为十六进制(以 16 为基数)值。输入值可以有 '0x''0X' 作为前缀,但前缀不是必需的。

  • 将值解释为由 'Type' 名称-值对组指定的整数数据类型。

'binary'

  • 将输入数值变量视为二进制(以 2 为基数)值。输入值可以有 '0b''0B' 作为前缀,但前缀不是必需的。

  • 将值解释为由 'Type' 名称-值对组指定的整数数据类型。

逻辑变量选项

全部折叠

要视为逻辑值 true 的文本,指定为字符向量、字符串标量、字符向量元胞数组或字符串数组。

示例: 如果 varOpts.TrueSymbols = {'t','TRUE'},导入函数会将任何包含 tTRUE 的字段导入为逻辑值 true

数据类型: char | string | cell

要视为逻辑值 false 的文本,指定为字符向量、字符串标量、字符向量元胞数组或字符串数组。

示例: 如果 varOpts.FalseSymbols = {'f','FALSE'},导入函数会将任何包含 fFALSE 的字段导入为逻辑值 false

数据类型: char | string | cell

大小写是否匹配的指示符,指定为逻辑值 truefalse

要将输入数据解释为缺失、truefalse,导入函数会将数据与 TreatAsMissingTrueSymbolsFalseSymbols 中指定的值进行匹配。

日期时间变量选项

全部折叠

显示格式,指定为字符向量或字符串标量。DatetimeFormat 属性控制输出中日期时间的显示格式。可将 DatetimeFormat 指定为以下值之一。

DatetimeFormat 的值描述

'default'

使用默认的显示格式。

'defaultdate'

使用创建时无时间分量的日期时间值的默认显示格式。

'preserveinput'

使用输入格式 InputFormat 指定的格式。

自定义格式

使用字母 A-Za-zDatetimeFormat 构造一个自定义值。这些字母对应于日期的 Unicode® 区域设置数据标记语言 (LDML) 标准。可以使用连字符、空格或冒号等非 ASCII 或非字母字符来分隔字段。要将字母 A-Za-z 作为字面字符包括在格式中,请将它们包含在单引号中。

出厂默认格式取决于您的系统区域设置。要更改默认显示格式,请参阅默认 datetime 格式

数据类型: char | string

表示日期时间的输入文本的格式,指定为包含字母标识符的字符向量或字符串标量。

下表列举了多种常见的输入格式和纽约市 2014 年 4 月 19 日(星期六)下午 9:41:06 的格式化输入示例。

InputFormat 的值示例
'yyyy-MM-dd'2014-04-19
'dd/MM/yyyy'19/04/2014
'dd.MM.yyyy'19.04.2014
'yyyy年 MM月 dd日'2014年 04月 19日
'MMMM d, yyyy'April 19, 2014
'eeee, MMMM d, yyyy h:mm a'Saturday, April 19, 2014 9:41 PM
'MMMM d, yyyy HH:mm:ss Z'April 19, 2014 21:41:06 -0400
'yyyy-MM-dd''T''HH:mmXXX' 2014-04-19T21:41-04:00

有关有效字母标识符的完整列表,请参阅日期时间数组的 Format 属性。

示例: 'InputFormat','eeee, MMMM d, yyyy HH:mm:ss'

数据类型: char | string

用于解释日期的区域设置,指定为字符向量或字符串标量。DatetimeLocale 值决定导入函数如何解释表示日期时间的文本。

DatetimeLocale 设置为下列值之一:

  • 'system' - 指定系统区域设置。

  • 字符向量或字符串标量 - 采用 xx_YY 形式,其中 xx 是用于指定语言的小写 ISO 639-1 双字母代码,YY 是用于指定国家/地区的大写 ISO 3166-1 alpha-2 代码。

下表列出了区域设置的某些常用值。

区域设置 语言国家/地区
'de_DE'德语德国
'en_GB'英语英国
'en_US'英语美国
'es_ES'西班牙语西班牙
'fr_FR'法语法国
'it_IT'意大利语意大利
'ja_JP'日语日本
'ko_KR'韩语韩国
'nl_NL'荷兰荷兰
'zh_CN'简体中文中国

示例: varOpts.DatetimeLocale = 'de_DE' 将日期时间区域设置设置为德语。

注意

Locale 值确定如何解释输入值。显示格式和语言可通过预设项窗口中的日期时间格式部分的区域设置选项来指定。要更改默认的日期时间区域设置,请参阅设置命令行窗口预设项

数据类型: char | string

时区,指定为字符向量或字符串标量。TimeZone 的值指定导入函数用于解释输入数据的时区。TimeZone 还指定输出数组的时区。如果输入数据是包含时区的字符向量,则导入函数将所有值转换为指定的时区。

TimeZone 可使用以下任何值:

  • '',用于创建不属于某一特定时区的“未设置时区”的日期时间值。

  • IANA 时区数据库中的时区地区,例如 'America/Los_Angeles'。时区地区的名称根据在地理区域观察到的情况,考虑了其标准时和夏令时与 UTC 之间的偏移量的当前和历史规则。

  • +HH:mm-HH:mm 形式的 ISO 8601 字符向量。例如,'+01:00' 指定与 UTC 之间具有固定偏移量的时区。

  • 'UTC',用于创建以协调世界时表示的日期时间值。

  • 'UTCLeapSeconds',用于创建以协调世界时表示的、将闰秒计算在内的日期时间值。

下表列出了 IANA 时区数据库中的时区地区的某些通用名称。

TimeZone 的值UTC 偏移量UTC DST 偏移量
'Africa/Johannesburg'+02:00+02:00
'America/Chicago'−06:00−05:00
'America/Denver'−07:00−06:00
'America/Los_Angeles'−08:00−07:00
'America/New_York'−05:00−04:00
'America/Sao_Paulo'−03:00−02:00
'Asia/Hong_Kong'+08:00+08:00
'Asia/Kolkata'+05:30+05:30
'Asia/Tokyo'+09:00+09:00
'Australia/Sydney'+10:00+11:00
'Europe/London'+00:00+01:00
'Europe/Zurich'+01:00+02:00

未指定 TimeZone 的日期时间数组不能与 TimeZone 属性设置为特定时区的数组进行比较或合并。

数据类型: char | string

分类变量选项

全部折叠

预期的类别,指定为包含类别名称列表的字符向量元胞数组或字符串数组。

输入字段中的名称必须与 Categories 属性中指定的名称之一匹配,以避免转换错误。

示例: varOpts.Categories = {'BareLand','Forest','Water','Roads','Buildings'};

类别保护指示符,指定为逻辑值 truefalse。有序分类数组的类别始终受保护。如果 Ordinal 属性设置为 true,则 Protected 的默认值为 true。否则,Protected 的值为 false。有关分类数组的详细信息,请参阅 categorical 函数参考页。

数学排序方式指示符,指定为 falsetrue01。有关分类数组的详细信息,请参阅 categorical 函数参考页。

持续时间变量选项

全部折叠

表示持续时间数据的输入文本的格式,指定为字符向量或字符串数组。

可将 InputFormat 指定为下列任何格式,其中 ddhhmmss 分别表示天、小时、分钟和秒:

  • 'dd:hh:mm:ss'

  • 'hh:mm:ss'

  • 'mm:ss'

  • 'hh:mm'

  • 前三种格式中的任何一种,再加上最多九个 S 字符指示秒的小数位,例如 'hh:mm:ss.SSSS'

示例: varOpts.InputFormat = 'dd:hh:mm:ss'

数据类型: char | string

持续时间数据的显示格式,指定为字符向量或字符串标量。

对于带有时间单位的数字,请指定下列值之一:

  • 'y' - 固定长度的年,1 年等于 365.2425 天

  • 'd' - 固定长度的天,1 天等于 24 小时

  • 'h' - 小时

  • 'm' - 分钟

  • 's' - 秒

对于数字计时器,请指定下列格式之一:

  • 'dd:hh:mm:ss'

  • 'hh:mm:ss'

  • 'mm:ss'

  • 'hh:mm'

  • 前三种格式中的任何一种,再加上最多九个 S 字符指示秒的小数位,例如 'hh:mm:ss.SSSS'

示例: DurationFormat 可以是一个带有时间单位的数字(例如 0.5 yr),也可以是一个数字计时器(例如 10:30:15,表示 10 小时 30 分钟 15 秒)。

数据类型: char | string

分隔小数秒的字符,指定为字符向量或字符串标量。导入函数使用 DecimalSeparator 属性来区分持续时间值的整数部分和小数秒部分。

数据类型: char | string

指示持续时间数据中字段分隔的字符,指定为字符向量或字符串标量。

数据类型: char | string

版本历史记录

在 R2016b 中推出