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');

変数 SmokerDiastolic および SystolicFillValue プロパティを設定します。

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) 
Variables:

    Smoker: 100x1 logical

        Values:

            True        34   
            False       66   

    Diastolic: 100x1 double

        Values:

            Min           68  
            Median      81.5  
            Max           99  

    Systolic: 100x1 double

        Values:

            Min         109   
            Median      122   
            Max         138   

欠損フィールドまたは不完全なフィールドを含むデータをインポートするには、欠損インスタンスを認識し、欠損インスタンスをインポートする方法を決定する必要があります。importOptions にこれら両方の決定をもたせ、readtable を使用してデータを取得します。

ファイルのインポート オプション オブジェクトを作成して、欠損データのインポートを制御するプロパティを更新し、readtable を使用してデータをインポートします。データセット airlinesmall_subset.csv には、NA によって示される欠損データを含む 2 つの数値変数 ArrDelayDepDelay がある点に注意してください。

airlinesmall_subset_NA_screenshot.png

ファイルからインポート オプション オブジェクトを作成します。

opts = detectImportOptions("airlinesmall_subset.csv");

TreatAsMissing プロパティを使用して、欠損インスタンスのプレース ホルダーとなるデータ内の文字を指定します。この例では、2 つの数値変数 ArrDelayDepDelay にテキスト NA を含む欠損フィールドが含まれています。

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

欠損インスタンスのインポート時に実行する、インポート関数のアクションを指定します。その他のオプションについては、ImportOptions プロパティのページを参照してください。

opts.MissingRule = "fill";

インポート関数が欠損インスタンスを見つけたときに使用する値を指定します。ここでは、変数 ArrDelay と変数 DepDelay 内の欠損インスタンスを 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 は接頭辞 0x および 0b の付いた 16 進数と 2 進数を自動的に検出します。接頭辞が付いていないときにこうした数値をインポートするには、インポート オプション オブジェクトを使用します。

ファイル hexAndBinary.txt のインポート オプション オブジェクトを作成します。その 3 列目には接頭辞 0x のない 16 進数が含まれます。

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

3 列目を 16 進数値としてインポートしなければならないことを指定するには、接頭辞がなくても関数 setvaropts を使用します。3 番目の変数の変数型を int32 に設定します。3 列目を 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

ファイルを読み取り、最初の 3 列を数値としてインポートします。関数 readtable は、1 列目と 2 列目に 16 進数値と 2 進数値が含まれていることを自動的に検出します。インポート オプション オブジェクトは、3 列目にも 16 進数値が含まれることを指定します。

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)
Variables:

    Cancelled: 1338x1 logical

        Values:

            True         29  
            False      1309  

DatetimeVariableImportOptions プロパティを使用して、datetime データのインポートを制御します。最初に、ファイルの ImportOptions オブジェクトを取得します。次に、datetime 変数の VariableImportOptions を調べて更新します。最後に、readtable を使用して変数をインポートします。

outages.csv 内のデータをプレビューします。列 OutageTime と列 RestorationTime の日付と時刻のデータに注目してください。以下は、最初の 10 行のみを示しています。

インポート オプション オブジェクトを取得します。

opts = detectImportOptions('outages.csv');

datetime 変数の OutageTime および RestorationTimeVariableImportOptions を取得して調べます。

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');

2 つの変数を選択して読み取り、プレビューします。RestorationTime の 2 番目の行の欠損値が現在の日付と時刻で埋められている点に注目してください。

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

    01-Feb-2002 12:18:00    07-Feb-2002 16:50:00
    23-Jan-2003 00:49:00    25-Jan-2024 22:25:41
    07-Feb-2003 21:15:00    17-Feb-2003 08:14:00
    06-Apr-2004 05:44:00    06-Apr-2004 06:10:00
    16-Mar-2002 06:18:00    18-Mar-2002 23:23:00
    18-Jun-2003 02:49:00    18-Jun-2003 10:54:00
    20-Jun-2004 14:39:00    20-Jun-2004 19:16:00
    06-Jun-2002 19:28:00    07-Jun-2002 00:51:00
    16-Jul-2003 16:23:00    17-Jul-2003 01:12:00
    27-Sep-2004 11:09:00    27-Sep-2004 16:37:00

関数 setvaropts を使用して、categorical データのインポートを制御するプロパティを更新します。最初に、ファイルのインポート オプション オブジェクトを取得します。次に、categorical 変数のオプションを調べて更新します。最後に、関数 readtable を使用して、変数をインポートします。

outages.csv 内のデータをプレビューします。列 Region と列 Cause 内のカテゴリカル データに注目してください。この表は最初の 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');

2 つの変数の概要を選択して読み取り、表示します。

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

    Region: 1468x1 categorical

        Values:

            MidWest        142   
            NorthEast      557   
            SouthEast      389   
            SouthWest       26   
            West           354   

    Cause: 1468x1 categorical

        Values:

            Miscellaneous          24   
            attack                294   
            earthquake              2   
            energy emergency      188   
            equipment fault       156   
            fire                   25   
            severe storm          338   
            thunder storm         201   
            wind                   95   
            winter storm          145   

不要な接頭辞文字または接尾辞文字をもつ変数を含む表形式データをインポートします。最初に、インポート オプション オブジェクトを作成し、データをプレビューします。次に、対象の変数を選択し、その変数の型およびプロパティを設定して、不要な文字を削除します。最終的に、対象のデータをインポートします。

ファイルのインポート オプションを作成し、テーブルをプレビューします。

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

変数のインポート オプション PrefixesSuffixes、および TrimNonNumeric プロパティを設定して、変数 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 を使用して、table の最初の 8 行を取得します。EmptyFieldRule の既定値は 'missing' です。そのため、インポート関数は空のフィールドを欠損として扱い、それらをその変数の FillValue 値に置き換えます。3 番目の VariableOptions を使用して、データをプレビューします。ここで、関数 preview は 3 番目の変数の空のフィールドを 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      14-Jan-0018    {'TRUE'  }    00:00:01    {'abc'   }
    {0x0 char}    {'b'     }        2      21-Jan-0018    {'FALSE' }    09:00:01    {'def'   }
    {'ghi'   }    {0x0 char}        3      31-Jan-0018    {'TRUE'  }    02:00:01    {'ghi'   }
    {'jkl'   }    {'a'     }      NaN      23-Feb-2018    {'FALSE' }    03:00:01    {'jkl'   }
    {'mno'   }    {'a'     }        4              NaT    {'FALSE' }    04:00:01    {'mno'   }
    {'pqr'   }    {'b'     }        5      23-Jan-0018    {0x0 char}    05:00:01    {'pqr'   }
    {'stu'   }    {'b'     }        5      23-Mar-0018    {'FALSE' }         NaN    {'stu'   }
    {0x0 char}    {'a'     }        6      24-Mar-2018    {'TRUE'  }    07:00:01    {0x0 char}

table の 2 番目の変数の 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>

次に、table 内にあるすべての変数に対し、EmptyFieldRule パラメーターを設定します。最初に、変数のデータ型を適切に更新します。この例では、5 番目と 7 番目の変数のデータ型をそれぞれ logicalstring に設定します。次に、すべての変数について、EmptyFieldRule'auto' に設定します。インポート関数は、変数のデータ型に基づいて空のフィールドをインポートします。ここで、関数 readtablelogical 変数の空のフィールドを 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      14-Jan-0018     true      00:00:01    "abc"    
    {0x0 char}    b                 2      21-Jan-0018     false     09:00:01    "def"    
    {'ghi'   }    <undefined>       3      31-Jan-0018     true      02:00:01    "ghi"    
    {'jkl'   }    a               NaN      23-Feb-2018     false     03:00:01    "jkl"    
    {'mno'   }    a                 4              NaT     false     04:00:01    "mno"    
    {'pqr'   }    b                 5      23-Jan-0018     false     05:00:01    "pqr"    
    {'stu'   }    b                 5      23-Mar-0018     false          NaN    "stu"    
    {0x0 char}    a                 6      24-Mar-2018     true      07:00:01    ""       
    {0x0 char}    a                 7      25-Mar-2018     true      08:00:01    <missing>
    {'xyz'   }    <undefined>     NaN              NaT     true      06:00:01    "xyz"    

EmptyFieldRule パラメーターは、'missing''auto' の他に 'error' に設定することもできます。'error' に設定した場合、関数 readtableImportErrorRule パラメーターで指定された手順に従って空のフィールドをインポートします。

入力引数

すべて折りたたむ

ファイル インポート オプション。関数 detectImportOptions によって作成された SpreadsheetImportOptions オブジェクト、DelimitedTextImportOptions オブジェクト、または FixedWidthImportOptions オブジェクトとして指定します。opts オブジェクトには、変数プロパティ、データの位置プロパティ、置換ルールなど、データのインポート プロセスを制御するプロパティが含まれます。

選択した変数。文字ベクトル、string スカラー、文字ベクトルの cell 配列、string 配列、数値インデックスの配列、または logical 配列として指定します。

変数名 (またはインデックス) は、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) は、変数 WeightFillValue0 に設定します。

すべての変数の型に共通するオプション

すべて折りたたむ

変数のデータ型。表に示されているデータ型で指定します。

データ型

説明

'char'

'string'

テキスト。

'single'

'double'

単精度または倍精度の浮動小数点数。

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

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

符号付きまたは符号なし整数。8、16、32、または 64 ビットの整数として格納されます。

整数データ型では浮動小数点数 NaN-Inf、および +Inf に対応する値は定義されません。したがって、浮動小数点データを整数の配列としてインポートするときに、インポート関数は未定義の浮動小数点数を変換します。

  • NaN0 に変換される。

  • -Inf は、関数 intmin を使用して、指定された整数データ型の最小の整数に変換されます。

  • +Inf は、関数 intmax を使用して、指定された整数データ型の最大の整数に変換されます。

'logical'

true 値または false 値 (たとえば、truefalse1、または 0)。

'datetime'

時点を指定する日時 (たとえば、2019-12-10 09:12:56 は 2019 年 12 月 10 日午前 9 時 12 分 56 秒を指定しています)。

'duration'

時間の長さ (たとえば、05:13:45 は 5 時間、13 分、および 45 秒を指定しています)。

'categorical'

カテゴリを指定する数値データまたはテキスト データ (たとえば、'red''green'、および 'blue' は 3 つのカテゴリの名前を指定しています)。

欠損データの置換値。変数の型により、文字ベクトル、string スカラー、スカラー数値、logical 値 true または false として指定します。

変数の型説明
テキスト

置換テキスト。文字ベクトルまたは string スカラーとして指定します。

例: 'not applicable'

数値

欠損インスタンスを置き換えるスカラー数値

インポート関数は、FillValue の入力を変数の Type プロパティで指定されたデータ型に変換します。たとえば、Type プロパティ値が uint8 の場合、インポート関数は FillValue プロパティの値も uint8 に変換します。

例: 0

logical

true または false

例: false

datetime

日付と時刻のデータを表す文字ベクトルまたは string スカラー、またはスカラー値。有効な datetime 入力の詳細については、関数 datetime のページを参照してください。

例: 'now' は欠損している datetime インスタンスを現在の日付と時刻に設定します。

例: [1998 12 1] は欠損している datetime インスタンスを 1998 年 12 月 1 日に設定します。

duration

期間のデータを表す文字ベクトル、string スカラー、またはスカラー値。有効な duration 入力の詳細については、関数 duration のページを参照してください。

例: '12:30:16' は欠損している duration インスタンスを 12 時間、30 分、16 秒の期間に設定します。

categorical

カテゴリの置換に使用する名前を含む文字ベクトルまたは string スカラー。

例: 'Miscellaneous' はカテゴリ名 Miscellaneous をカテゴリカル データ内の欠損インスタンスに割り当てます。

欠損データ、変換不能なデータ、またはエラーを引き起こすデータのインポートを指示するには、FillValueTreatAsMissingMissingRule および ErrorRule の 4 つのプロパティを一緒に使用します。次の場合、インポート関数は FillValue プロパティに指定された値を使用します。

  • データが変換不能であるか、または TreatAsMissing の値に一致する。

  • MissingRule または ErrorRulefill に設定されている。

欠損データとして解釈するテキスト。文字ベクトル、string スカラー、文字ベクトルの cell 配列、または string 配列として指定します。

インポート関数は、欠損インスタンスを見つけると、MissingRule プロパティ内の指定を使用して、適切なアクションを決定します。

例: 'TreatAsMissing',{'NA','TBD'} は、インポート関数に NA または TBD のすべての出現を欠損フィールドとして処理するように指示します。

データ型: char | string | cell

データ内の二重引用符を管理する処理。次の表のいずれかの値として指定します。

引用符のルール処理
'remove'

先頭の空白を削除した後、文字が二重引用符 (") で囲まれている場合、インポート関数は、開始二重引用符と、その次に出現する二重引用符を終了二重引用符として解釈して、両方とも削除します。

: "The" Example TextThe Example Text としてインポートされます。

: The "Example" TextThe "Example" Text としてインポートされます。

文字が 2 セットの二重引用符 ("") で囲まれている場合、インポート関数は最初の 2 つの出現を削除します。

: ""abc""abc"" としてインポートされます。

: "The" "Example" TextThe "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' — 変数のデータ型に基づいて空のフィールドをインポートします。空のテキスト値は、空の (長さゼロの) 文字ベクトルまたは string としてインポートします。空の categorical 値は、未定義の categorical 値としてインポートします。その他のすべてのデータ型は、ImportErrorRule プロパティで指定されている手順を使用してインポートします。

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

データ型: char | string

変数値の接頭辞の位置から削除するテキスト。文字ベクトル、文字ベクトルの cell 配列、string スカラー、string 配列として指定します。

例: opts = setvaropts(opts,'Var1','Prefixes','$') は変数 Var1Prefixes オプションを設定します。Var1'$500' の値が含まれる場合、readtable はこれを '500' として読み取ります。

データ型: char | string | cell

変数値の接尾辞の位置から削除するテキスト。文字ベクトル、文字ベクトルの cell 配列、string スカラー、string 配列として指定します。

例: opts = setvaropts(opts,'Var1','Suffixes','/-') は変数 Var1Suffixes オプションを設定します。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

数値変数オプション

すべて折りたたむ

指数を示す文字。文字ベクトルまたは string スカラーとして指定します。インポート関数は、ExponentCharacter プロパティを使用して、科学表記で表された数値の指数を示す文字を認識します。

例: varOpts.ExponentCharacter = 'a' の場合、インポート関数はテキスト "1.2a3" を数値 1200 としてインポートします。

データ型: char | string

数値変数内の小数点の区切りを示す文字。文字ベクトルまたは string スカラーとして指定します。インポート関数は、DecimalSeparator の名前と値のペアで指定される文字を使用して、数値の整数部分と小数部分を区別します。

整数データ型に変換すると、小数部分をもつ数値は最も近い整数に丸められます。

例: 名前と値のペアが 'DecimalSeparator',',' のように指定される場合、インポート関数はテキスト "3,14159" を数値 3.14159 としてインポートします。

データ型: char | string

数値変数内の 3 桁ごとの区切りを示す文字。文字ベクトルまたは string スカラーとして指定します。3 桁ごとの区切り文字は視覚的な区切りとして機能し、数値を 3 桁ごとにグループ化します。インポート関数は、ThousandsSeparator の名前と値のペアで指定される文字を使用して、インポートされる数値を解釈します。

例: 名前と値のペアが 'ThousandsSeparator',',' のように指定される場合、インポート関数はテキスト "1,234,000"1234000 としてインポートします。

データ型: char | string

非数値文字を数値変数から削除します。logical true または false として指定します。

例: 名前と値のペアが 'TrimNonNumeric',true のように指定される場合、インポート関数は '$500/-'500 として読み取ります。

データ型: logical

数値変数を解釈するシステム。'decimal''hex'、または 'binary' として指定します。

'NumberSystem' の値

説明

'decimal'

  • 入力数値変数が 10 進数の値を持つものとして処理する。

  • 値のデータ型が名前と値のペア 'Type' で指定されていると解釈するか、'Type' が指定されていない場合は 'double' であると解釈する。

'hex'

  • 入力数値変数が 16 進数の値を持つものとして処理する。入力値は接頭辞として '0x' または '0X' を使用できるが、接頭辞は必須ではない。

  • 値が名前と値のペア 'Type' によって指定された整数データ型を持っていると解釈する。

'binary'

  • 入力数値変数が 2 進数の値を持つものとして処理する。入力値は接頭辞として '0b' または '0B' を使用できるが、接頭辞は必須ではない。

  • 値が名前と値のペア 'Type' によって指定された整数データ型を持っていると解釈する。

logical 変数オプション

すべて折りたたむ

論理値 true として扱うテキスト。文字ベクトル、string スカラー、文字ベクトルの cell 配列、または string 配列として指定します。

例: varOpts.TrueSymbols = {'t','TRUE'} の場合、インポート関数は、論理値 true として t または TRUE を含むすべてのフィールドをインポートします。

データ型: char | string | cell

論理値 false として扱うテキスト。文字ベクトル、string スカラー、文字ベクトルの cell 配列、または string 配列として指定します。

例: varOpts.FalseSymbols = {'f','FALSE'} の場合、インポート関数は、論理値 false として f または FALSE を含むすべてのフィールドをインポートします。

データ型: char | string | cell

大文字小文字を区別するかどうかのインジケーター。論理値 true または false として指定します。

入力データを欠損値の true または false として解釈するために、インポート関数はデータを TreatAsMissingTrueSymbols および FalseSymbols に指定された値に一致させます。

datetime 変数オプション

すべて折りたたむ

表示形式。文字ベクトルまたは string スカラーとして指定します。DatetimeFormat プロパティは、出力内の日付と時刻の表示形式を制御します。DatetimeFormat は次の値のいずれかとして指定します。

DatetimeFormat の値説明

'default'

既定の表示形式を使用します。

'defaultdate'

時刻の成分を含めずに作成された datetime 値用の既定の表示形式を使用します。

'preserveinput'

入力形式 InputFormat で指定された形式を使用します。

カスタム形式

文字 A-Z および a-z を使用して DatetimeFormat のカスタムの値を構成します。これらの文字は Unicode® LDML (Locale Data Markup Language) の標準の日付表記に対応します。フィールドの区切りとして、ASCII 以外の文字やハイフン、スペース、コロンなどの記号を含めることができます。文字 A-Z および a-z をリテラル文字として形式に含めるには、文字を一重引用符で囲みます。

出荷時の既定の形式はシステムのロケールに依存します。既定の表示形式を変更するには、既定の datetime 形式を参照してください。

データ型: char | string

日付と時刻を表す入力テキストの形式。文字識別子を含む文字ベクトルまたは string スカラーとして指定します。

次の表に、一般的な入力形式と、ニューヨーク市の 2014 年 4 月 19 日 (土) 9:41:06 PM の書式設定された入力の例を示します。

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'4 月 19, 2014
'eeee, MMMM d, yyyy h:mm a'土曜日, 4 月 19, 2014 9:41 午後
'MMMM d, yyyy HH:mm:ss Z'4 月 19, 2014 21:41:06 -0400
'yyyy-MM-dd''T''HH:mmXXX' 2014-04-19T21:41-04:00

有効な文字識別子の完全な一覧については、datetime 配列の Format プロパティを参照してください。

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

データ型: char | string

日付を解釈するためのロケール。文字ベクトルまたは string スカラーとして指定します。DatetimeLocale 値は、インポート関数が日付と時刻を表すテキストを解釈する方法を決定します。

DatetimeLocale を次のいずれかの値に設定します。

  • 'system' — システムのロケールを指定します。

  • 文字ベクトルまたは string スカラー — xx_YY の形式を使用します。ここで xx は ISO 639-1 で定義された小文字 2 文字の言語コードで、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

タイム ゾーン。文字ベクトルまたは string スカラーとして指定します。TimeZone の値を指定すると、インポート関数で入力データを解釈するときにそのタイム ゾーンが使用されます。また、出力配列でも TimeZone で指定したタイム ゾーンが使用されます。入力データがタイム ゾーンを含む文字ベクトルである場合、インポート関数はすべての値を指定されたタイム ゾーンに変換します。

TimeZone は次の任意の値を使用します。

  • '' は特定のタイム ゾーンに属さない "ゾーンなし" の datetime 値を作成します。

  • IANA タイム ゾーン データベースのタイム ゾーン地域 (例 'America/Los_Angeles')。タイム ゾーン地域の名前では、各地域で使用される標準時および夏時間の UTC からのオフセットについて、現在および過去に実施されたルールが考慮されます。

  • ISO 8601 の +HH:mm または -HH:mm 形式の文字ベクトル。'+01:00' など、UTC からの固定オフセットのタイム ゾーンを指定します。

  • 'UTC'。協定世界時に基づいて datetime 値を作成します。

  • 'UTCLeapSeconds'。うるう秒が考慮された協定世界時に基づいて datetime 値を作成します。

次の表に 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 をもたない datetime 配列は、TimeZone プロパティをもつ配列と比較または結合して、特定のタイム ゾーンを設定することはできません。

データ型: char | string

categorical 変数オプション

すべて折りたたむ

期待されるカテゴリ。カテゴリ名のリストを含む、文字ベクトルの cell 配列、または string 配列として指定します。

変換エラーを避けるため、入力フィールドの名前は、Categories プロパティに指定された名前のいずれかと一致していなければなりません。

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

カテゴリ保護インジケーター。logical true または false として指定します。順序 categorical 配列のカテゴリは常に保護されます。Ordinal プロパティが true に設定されている場合、Protected の既定値は true です。それ以外の場合は、Protected の値は false です。categorical 配列の詳細については、関数 categorical のリファレンス ページを参照してください。

数学的な順序インジケーター。falsetrue0 または 1 のいずれかとして指定します。categorical 配列の詳細については、関数 categorical のリファレンス ページを参照してください。

Duration 変数オプション

すべて折りたたむ

duration データを表す入力テキスト。文字ベクトルまたは string 配列として指定します。

次のいずれかの形式で InputFormat を指定します。ここで、ddhhmm、および ss はそれぞれ日、時間、分、秒を表します。

  • 'dd:hh:mm:ss'

  • 'hh:mm:ss'

  • 'mm:ss'

  • 'hh:mm'

  • 最初の 3 つの形式のいずれかに、秒の小数部を表す文字 S (最大 9 桁) を加えた 'hh:mm:ss.SSSS' のような形式

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

データ型: char | string

duration データの表示形式。文字ベクトルまたは string スカラーとして指定します。

時間単位を伴う数値には、次のいずれかの値を指定します。

  • 'y' — 固定長の年数。ここで、1 年は 365.2425 日に等しい

  • 'd' — 固定長の日数。ここで、1 日は 24 時間に等しい

  • 'h' — 時間数

  • 'm' — 分数

  • 's' — 秒数

デジタル タイマーには、次のいずれかの形式を指定します。

  • 'dd:hh:mm:ss'

  • 'hh:mm:ss'

  • 'mm:ss'

  • 'hh:mm'

  • 最初の 3 つの形式のいずれかに、秒の小数部を表す文字 S (最大 9 桁) を加えた 'hh:mm:ss.SSSS' のような形式

例: DurationFormat は、時間単位を伴う単一の数値と (0.5 yr など) 、またはデジタル タイマー (10 時間 30 分 15 秒を表す 10:30:15 など) のいずれかにすることができます。

データ型: char | string

秒数の小数部を分ける文字。文字ベクトルまたは string スカラーとして指定します。インポート関数は DecimalSeparator プロパティを使用して duration 値の整数部を小数部と区別します。

データ型: char | string

duration データでフィールドの区切りを示す文字。文字ベクトルまたは string スカラーとして指定します。

データ型: char | string

バージョン履歴

R2016b で導入