fixedWidthImportOptions

固定幅テキスト ファイルのインポート オプション オブジェクト

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

説明

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

作成

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

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

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

    opts = detectImportOptions(filename)

構文

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

説明

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

例

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

例

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

例

入力引数

すべて展開する

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

プロパティ

すべて展開する

変数プロパティ

変数名。文字ベクトルの 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

固定幅のテキスト ファイルにおける変数のフィールド幅。正の整数値のベクトルとして指定します。ベクトルの正の整数はそれぞれ、フィールド内で変数を構成する文字数に対応します。VariableWidths プロパティには、VariableNames プロパティに指定された各変数に対応するエントリが含まれます。

変数のデータ型。一連の有効なデータ型の名前を含む文字ベクトルの 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

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

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

例: 'Whitespace',' _'

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

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

例: "LineEnding","\n"

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

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

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

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

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

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

ファイルに関連付けられた文字エンコード スキーム。'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'空行をインポートします。インポート関数は、VariableWidths、VariableOptions、MissingRule、およびその他の関連するプロパティ (Whitespace など) に指定された値を使用して、空の行を解析します。
'error'エラー メッセージを表示し、インポート操作を中止します。

例: opts.EmptyLineRule = 'skip';

データ型: char | string

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

欠損ルール動作
'fill'

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

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

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

例: opts.MissingRule = 'omitrow';

データ型: 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 行をプレビュー

例

すべて折りたたむ

ライブ スクリプトを開く

固定幅形式テキスト ファイルを確認し、インポート オプション オブジェクトを初期化してから、そのオブジェクトを使用してテキスト ファイルから table をインポートします。

固定幅テキスト ファイルの読み込みとプレビュー

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 オブジェクトと使用して table をインポートします。

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
ライブ スクリプトを開く

インポート オプション オブジェクトを定義して、固定幅形式のテキスト ファイルから乱雑なデータをインポートします。乱雑なデータを処理するオブジェクトを設定し、それを使用して table をインポートします。

固定幅テキスト ファイルの読み込みとプレビュー

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 Rule および ExtraColumnsRule の設定

EmptyLineRule を 'read' に設定して、データの空行を読み取ります。次に、MissingRule を 'fill' に設定して欠損インスタンスを事前定義値で埋めます。最後に、インポート時に余分な列を無視するように、ExtraColumnsRule を 'ignore' に設定します。プロパティと値の詳細については、FixedWidthImportOptions のドキュメンテーションを参照してください。 

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

PartialFieldRule の設定

部分フィールドは、インポート関数が変数の幅の末端に到達する前に、行末の文字に到達した場合に発生します。たとえば、次のプレビューではファイル fixed_width_patients_subset_messy.txt の最後の 3 行が該当します。ここでは、最後の列の最後の行で、変数の幅 3 の最後に到達する前に、行末の文字がフィールドの開始から 2 桁後に現れています。

この部分フィールドの出現はエラーを示している場合があります。そのため、PartialFieldRule を使用してこのデータの処理方法を決定します。部分フィールドのデータを維持して、適切なデータ型に変換するには、PartialFieldRule を 'keep' に設定します。PartialFieldRule の詳細については、FixedWidthImportOptions のドキュメンテーションを参照してください。

opts.PartialFieldRule = 'keep';

テーブルのインポート

関数 readtable と FixedWidthImportOptions オブジェクトを使用して table をインポートし、データをプレビューします。 

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

バージョン履歴

R2016b で導入

すべて展開する

参考

|