delimitedTextImportOptions

区切りテキストのインポート オプション オブジェクト

このページをすべて展開する

説明

DelimitedTextImportOptions オブジェクトで MATLAB® が表形式データを区切り付きテキスト ファイルからインポートする方法を指定できます。オブジェクトには、エラーおよび欠損データの処理を含む、データのインポート プロセスを制御するプロパティが含まれています。

作成

DelimitedTextImportOptions オブジェクトは、関数 detectImportOptions または関数 delimitedTextImportOptions (ここで説明します) により作成できます。

  • detectImportOptions は、filename で指定した区切り付きテキスト ファイルの内容に基づいてインポート プロパティを検出して入力する場合に使用します。

    opts = detectImportOptions(filename);

  • delimitedTextImportOptions は、インポートの要件に基づいてインポート プロパティを定義する場合に使用します。

構文

opts = delimitedTextImportOptions
opts = delimitedTextImportOptions('NumVariables',numVars)
opts = delimitedTextImportOptions(___,Name,Value)

説明

opts = delimitedTextImportOptions は、1 つの変数をもつ DelimitedTextImportOptions オブジェクトを作成します。

例

opts = delimitedTextImportOptions('NumVariables',numVars) は、numVars で指定した数の変数をもつオブジェクトを作成します。

例

opts = delimitedTextImportOptions(___,Name,Value) は、名前と値のペアの引数を 1 つ以上使用して、DelimitedTextImportOptions オブジェクトの追加プロパティを指定します。

例

入力引数

すべて展開する

変数の数。正のスカラー整数として指定します。

プロパティ

すべて展開する

変数プロパティ

変数名。文字ベクトルの cell 配列または string 配列として指定します。VariableNames プロパティには、変数のインポート時に使用する名前が含まれます。

データに N 個の変数が含まれているが変数名が指定されない場合、VariableNames プロパティには {'Var1','Var2',...,'VarN'} が含まれます。

スペースおよび非 ASCII 文字を含む変数名など、無効な MATLAB 識別子を変数名としてサポートするには、VariableNamingRule の値を 'preserve' に設定します。

例: opts.VariableNames は、現在の (検出された) 変数名を返します。

例: opts.VariableNames(3) = {'Height'} は 3 番目の変数の名前を Height に変更します。

データ型: char | string | cell

変数名を保持するかどうかのフラグ。"modify" または "preserve" として指定します。

  • "modify" — 無効な変数名 (関数 isvarname で判定) を、有効な MATLAB 識別子に変換。

  • "preserve" — スペースや非 ASCII 文字を含む変数名など、有効な MATLAB 識別子ではない変数名を保持。

R2019b 以降、変数名と行名には、スペースや非 ASCII 文字など任意の文字を含めることができます。また、英字だけでなく任意の文字で始めることができます。変数名と行名は、有効な MATLAB 識別子 (関数 isvarname で判定) である必要はありません。これらの変数名と行名を保持するには、VariableNamingRule の値を "preserve" に設定します。VariableNamingRule の値を "modify" から "preserve" に変更すると、変数名が更新されなくなります。

データ型: char | string

変数のデータ型。一連の有効なデータ型の名前を含む文字ベクトルの cell 配列または string 配列として指定します。VariableTypes プロパティは、変数のインポート時に使用するデータ型を指定します。

VariableTypes プロパティを更新するには、関数 setvartype を使用します。

例: opts.VariableTypes は、現在の変数のデータ型を返します。

例: opts = setvartype(opts,'Height',{'double'}) は、変数 Height のデータ型を double に変更します。

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

SelectedVariableNames は VariableNames プロパティに含まれる名前のサブセットでなければなりません。既定では、SelectedVariableNames には VariableNames プロパティからのすべての変数名が含まれます。つまり、すべての変数がインポートされることを意味します。

特定の変数のみをインポートするには、SelectedVariableNames プロパティを使用します。SelectedVariableNames プロパティを使用して変数のサブセットを指定し、readtable を使用してそのサブセットのみをインポートします。

スペースおよび非 ASCII 文字を含む変数名など、無効な MATLAB 識別子を変数名としてサポートするには、VariableNamingRule の値を 'preserve' に設定します。

例: opts.SelectedVariableNames = {'Height','LastName'} は、インポート操作のために 2 つの変数 Height と LastName のみを選択します。

例: opts.SelectedVariableNames = [1 5] は、インポート操作のために最初の変数と 5 番目の変数の 2 つの変数のみを選択します。

例: T = readtable(filename,opts) は、opts オブジェクトの SelectedVariableNames プロパティで指定された変数のみを含む table を返します。

データ型: uint16 | uint32 | uint64 | char | string | cell

型固有の変数のインポート オプション。変数インポート オプション オブジェクトの配列として返されます。配列には、VariableNames プロパティで指定された各変数に対応するオブジェクトが含まれます。配列の各オブジェクトには、特定のデータ型でのデータのインポートをサポートするプロパティが含まれます。

変数オプションは、数値、テキスト、logical、datetime または categorical のデータ型をサポートします。

変数の現在の (または検出された) オプションをクエリするには、関数 getvaropts を使用します。

変数にオプションを設定してカスタマイズするには、関数 setvaropts を使用します。

例: opts.VariableOptions は、データの各変数に対応する VariableImportOptions オブジェクトの集合を返します。

例: getvaropts(opts,'Height') は、変数 Height の VariableImportOptions オブジェクトを返します。

例: opts = setvaropts(opts,'Height','FillValue',0) は変数 Height の FillValue プロパティを 0 に設定します。

位置プロパティ

データの場所。正のスカラー整数または正のスカラー整数の N- 行 -2 列の配列として指定します。これらの形式の 1 つを使用して DataLines を指定します。

次として指定

説明

n

データが含まれる "最初の行" を指定します。n を使用して値を指定すると、DataLines プロパティの値が [n inf] に設定されます。インポート関数は n とファイル終端の間のすべての行を読み取ります。

n はゼロより大きい正の整数にしなければなりません。

[n1 n2]

データが含まれる "行の範囲" を指定します。n1 はデータが含まれる最初の行で、n2 はデータが含まれる最後の行です。

配列 [n1 n2] 内の値は非ゼロの正の整数で、n2 は n1 より大きくなければなりません。

[n1 n2; n3 n4;...]

異なる N 行の範囲が含まれる N-by-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 プロパティは行名を含む列の位置を指定します。

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

区切りテキストのプロパティ

区切りテキスト ファイル内のフィールドの区切り記号。string 配列、文字ベクトル、または文字ベクトルの cell 配列として指定します。

例: "Delimiter","|"

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

空白として扱う文字。1 文字以上が含まれる文字ベクトルまたは string スカラーとして指定します。

例: 'Whitespace',' _'

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

行末の文字。string 配列、文字ベクトルまたは文字ベクトルの cell 配列として指定します。

例: "LineEnding","\n"

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

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

コメントのスタイル。string 配列、文字ベクトルまたは文字ベクトルの cell 配列として指定します。単一行および複数行のコメントでは、開始識別子は空白以外の最初の文字でなければなりません。単一行のコメントでは、単一の識別子を指定して、その識別子で開始している行をコメントとして扱います。複数行のコメントでは、開始識別子 (最初のもの) から終了識別子 (2 番目のもの) までの行がコメントとして扱われます。識別子の文字ベクトルを 2 つまで指定できます。

たとえば、空白以外の最初の文字としてパーセント記号に続く行を無視するには、CommentStyle を "%" に指定します。

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

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

区切りテキスト ファイル内の連続する区切り記号を管理する方法。次の表の値のいずれかとして指定します。

値動作
"split"連続する区切り記号を複数のフィールドに分割します。
"join"複数の区切り記号を結合して 1 つの区切り記号にします。
"error"エラーを返し、インポート操作をキャンセルします。

区切りテキスト ファイル内の先頭の区切り記号を管理する方法。次の表の値のいずれかとして指定します。

値動作
"keep"区切り記号を維持します。
"ignore"区切り記号を無視します。
"error"エラーを返し、インポート操作をキャンセルします。

区切りテキスト ファイル内の末尾の区切り記号を管理する方法。次の表の値のいずれかとして指定します。

先頭の区切り記号のルール動作
'keep'区切り記号を維持します。
'ignore'区切り記号を無視します。
'error'エラーを返し、インポート操作を中止します。

ファイルに関連付けられた文字エンコード スキーム。'Encoding' と 'system' で構成されるコンマ区切りのペア、または標準の文字エンコード スキーム名として指定します。

エンコードを指定しない場合、関数は自動文字セット検出を使用して、ファイルの読み取り時にエンコードを判断します。

例: 'Encoding','system' はシステムの既定のエンコードを使用します。

データ型: char | string

置換ルール

欠損データを管理する方法。次の表のいずれかの値として指定します。

欠損ルール動作
'fill'

欠損データを FillValue プロパティの内容に置き換えます。

FillValue プロパティは、インポートされる変数の VariableImportOptions オブジェクトで指定されます。FillValue プロパティへのアクセスの詳細については、setvaropts を参照してください。

'error'インポートを停止し、欠損しているレコードとフィールドを示すエラー メッセージを表示します。
'omitrow'欠損データを含む行を除外します。
'omitvar'欠損データを含む変数を除外します。

例: opts.MissingRule = 'omitrow';

データ型: char | string

データ内の空行を処理する手続き。'skip'、'read'、または 'error' として指定します。インポート関数は空白を空として解釈します。

空行のルール動作
'skip'空行をスキップします。
'read'空行をインポートします。インポート関数は、VariableWidths、VariableOptions、MissingRule、およびその他の関連するプロパティ (Whitespace など) に指定された値を使用して、空の行を解析します。
'error'エラー メッセージを表示し、インポート操作を中止します。

例: opts.EmptyLineRule = 'skip';

データ型: char | string

インポート エラーを処理する方法。次の表のいずれかの値として指定します。

インポート エラー ルール動作
'fill'

エラーが発生したデータを FillValue プロパティの内容に置き換えます。

FillValue プロパティは、インポートされる変数の VariableImportOptions オブジェクトで指定されます。FillValue プロパティへのアクセスの詳細については、setvaropts を参照してください。

'error'インポートを停止し、エラーの原因となるレコードとフィールドを示すエラー メッセージを表示します。
'omitrow'エラーが発生した行を除外します。
'omitvar'エラーが発生した変数を除外します。

例: opts.ImportErrorRule = 'omitvar';

データ型: char | string

データ内の余分な列を処理する方法。次の表のいずれかの値として指定します。

余分な列のルール動作
'addvars'

余分な列をインポートするには、新しい変数を作成します。余分な列が N 列ある場合、新しい変数を 'ExtraVar1', 'ExtraVar2',..., 'ExtraVarN' としてインポートします。データの余分な列は VariableTypes が char であるものとしてインポートされます。

'ignore'データの余分な列を無視します。
'wrap'データの余分な列を新しいレコードにラップします。このアクションで変数の数は変わりません。
'error'エラー メッセージを表示し、インポート操作を中止します。

データ型: char | string

オブジェクト関数

getvaropts変数インポート オプションの取得
setvaropts変数のインポート オプションの設定
setvartype変数のデータ型の設定
previewインポート オプションを使用してファイルから 8 行をプレビュー

例

すべて折りたたむ

ライブ スクリプトを開く

複数の変数を 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      true  
    {'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      true  
    {'Wilson'  }    Male      40     {'VA Hospital'              }      68       180      false

readtable を使用してデータをインポートします。 

T = readtable('patients.dat',opts);
whos T
  Name        Size            Bytes  Class    Attributes

  T         100x7             33987  table

バージョン履歴

R2016b で導入

すべて展開する

参考

関数

ライブ エディター タスク