このページの内容は最新ではありません。最新版の英語を参照するには、ここをクリックします。

spreadsheetImportOptions

スプレッドシートのインポート オプション オブジェクト

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

説明

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

作成

SpreadsheetImportOptions オブジェクトは、関数 detectImportOptions または関数 spreadsheetImportOptions (ここで説明します) を使用して作成できます。

  • detectImportOptions は、filename で指定したスプレッドシートの内容に基づいてインポート プロパティを検出および入力する場合に使用します。

    opts = detectImportOptions(filename);

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

構文

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

説明

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

例

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

例

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

例

入力引数

すべて展開する

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

プロパティ

すべて展開する

変数プロパティ

変数名。文字ベクトルの 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 に設定します。

位置プロパティ

読み取り元のシート。空の文字配列、シート名を含む文字ベクトルまたは string スカラー、あるいはシート インデックスを示す正の整数スカラーとして指定します。インポート関数は Sheet プロパティに指定された値に基づいて、表に説明されているように動作します。

指定動作
'' (既定)1 番目のシートからデータをインポートします。
名前スプレッドシート ファイル内のシートの順序に関係なく、一致する名前のシートからデータをインポートします。
整数スプレッドシート ファイル内のシート名に関係なく、整数で示された位置にあるシートからデータをインポートします。

データ型: char | string | single | double

インポートするデータの場所。文字ベクトル、string スカラー、文字ベクトルの cell 配列、string 配列、正のスカラー整数、または N 行 2 列の正のスカラー整数の配列として指定します。これらの形式の 1 つを使用して DataRange を指定します。

指定方法動作

'Cell' または n

開始するセルまたは開始する行

Excel® の A1 表記法を使用して、データの開始セルを指定します。たとえば、A5 は列 A と行 5 が交わる場所にあるセルの識別子です。

開始セルを使用して、インポート関数は、インポートを開始セルで開始し、最後の空の行またはフッター範囲で終了することで、データの範囲を自動的に検出します。

あるいは、正のスカラー行インデックスを使用して、データを含む最初の行を指定します。

インポート関数は、指定された行インデックスを使用して、指定された最初の行からデータの最後またはフッター範囲まで読み取ることにより、データの範囲を自動的に検出します。

例: 'A5' または 5

'Corner1:Corner2'

四角形の範囲

四角形の範囲フォームを使用して読み取る範囲を正確に指定します。Corner1 と Corner2 は読み取る範囲を定義する 2 つの対角です。

インポート関数は、指定された範囲内に含まれるデータのみを読み取ります。指定された範囲内の空のフィールドは欠損セルとしてインポートされます。

列数は NumVariables プロパティで指定された数と一致しなければなりません。

例: 'A5:K50'

'Row1:Row2' または 'Column1:Column2'

行範囲または列範囲

Excel の行番号を使用して、開始行と終了行を示して範囲を指定します。

インポート関数は、指定された行範囲を使用して、最初の空でない列からデータの最後まで読み取ることにより、列の範囲を自動的に検出し、列ごとに 1 つの変数を作成します。

例: '5:500'

あるいは、Excel の列の文字または数字を使用して開始列と終了列を示して、範囲を指定します。

インポート関数は、指定された列範囲を使用して、最初の空でない行からデータの最後またはフッター範囲まで読み取ることにより、行の範囲を自動的に検出します。

指定された範囲の列数は NumVariables プロパティで指定された数と一致しなければなりません。

例: 'A:K'

[n1 n2; n3 n4;...]

複数の行範囲

"複数の行範囲" を指定して、N の異なる行範囲を含む N 行 2 列の配列で読み取ります。

有効な複数の行範囲の配列は、次でなければなりません。

  • 行の範囲は昇順で指定する。すなわち、配列で指定された最初の行範囲は、他の行範囲より、ファイル内で先に出現する。

  • オーバーラップしない行範囲のみを含む。

Inf の使用は、複数の行範囲を指定する数値配列で最終行を示すためにのみサポートされます。たとえば、[1 3; 5 6; 8 Inf] とします。

例: [1 3; 5 6; 8 Inf]

''

指定なしまたは空

データを取得しません。

例: ''

データ型: char | string | cell | single | double

行名の位置。文字ベクトル、string スカラー、正のスカラー整数または空の文字配列として指定します。次の表のいずれかの値として RowNamesRange を指定します。

指定方法動作

'Cell'

Excel の A1 表記法を使用して、データの開始セルを指定します。たとえば、A5 は列 A と行 5 が交わる場所にあるセルの識別子です。

インポート関数はデータ内の各変数の名前を識別します。

例: 'A5'

'Corner1:Corner2'

四角形の範囲

四角形の範囲フォームを使用して読み取る範囲を正確に指定します。Corner1 と Corner2 は読み取る範囲を定義する 2 つの対角です。

RowNamesRange に含まれる行数はデータの行数と一致しなければならず、RowNamesRange で示される範囲は 1 列のみでなければなりません。

例: 'A5:A50'

'Row1:Row2'

行範囲

Excel の行番号を使用して、開始行と終了行を示して範囲を指定します。

行名は 1 列でなければなりません。

例: '5:50'

n

数値インデックス

正のスカラー列インデックスを使用して、行名を含む列を指定します。

例: 5

''

指定なしまたは空

行名がないことを示します。

例: ''

データ型: char | single | double

変数名の位置。文字ベクトル、string スカラー、正のスカラー整数または空の文字配列として指定します。次の表のいずれかの値として VariableNamesRange を指定します。

指定方法動作

'Cell'

Excel の A1 表記法を使用して、データの開始セルを指定します。たとえば、A5 は列 A と行 5 が交わる場所にあるセルの識別子です。

インポート関数は、データ内の各変数の名前を読み取ります。

例: 'A5'

'Corner1:Corner2'

四角形の範囲

四角形の範囲フォームを使用して読み取る範囲を正確に指定します。Corner1 と Corner2 は読み取る範囲を定義する 2 つの対角です。

列数は NumVariables プロパティで指定された数と一致しなければならず、範囲は 1 行のみでなければなりません。

例: 'A5:K5'

'Row1:Row2'

行範囲

Excel の行番号を使用して、開始行と終了行を示して範囲を指定します。

1 行でなければなりません。

例: '5:5'

n

数値インデックス

正のスカラー行インデックスを使用して、変数名を含む行を指定します。

例: 5

''

指定なしまたは空

変数名がないことを示します。

例: ''

データ型: char | single | double

変数の説明の位置。文字ベクトル、string スカラー、正のスカラー整数または空の文字配列として指定します。次の表のいずれかの値として VariableDescriptionRange を指定します。

指定方法動作

'Cell'

Excel の A1 表記法を使用して、データの開始セルを指定します。たとえば、A5 は列 A と行 5 が交わる場所にあるセルの識別子です。

インポート関数は、データ内の各変数の説明を読み取ります。

例: 'A5'

'Corner1:Corner2'

四角形の範囲

四角形の範囲フォームを使用して読み取る範囲を正確に指定します。Corner1 と Corner2 は読み取る範囲を定義する 2 つの対角です。

列数は NumVariables プロパティで指定された数と一致しなければならず、範囲は 1 行のみでなければなりません。

例: 'A5:K5'

'Row1:Row2'

行範囲

Excel の行番号を使用して、開始行と終了行を示して範囲を指定します。

1 行でなければなりません。

例: '5:5'

n

数値インデックス

正のスカラー行インデックスを使用して、説明を含む行を指定します。

例: 5

''

指定なしまたは空

変数の説明がないことを示します。

例: ''

データ型: char | string | single | double

変数の単位の位置。文字ベクトル、string スカラー、正のスカラー整数または空の文字配列として指定します。次の表のいずれかの値として VariableUnitsRange を指定します。

指定方法動作

'Cell'

Excel の A1 表記法を使用して、データの開始セルを指定します。たとえば、A5 は列 A と行 5 が交わる場所にあるセルの識別子です。

インポート関数は、データ内の各変数の単位を読み取ります。

例: 'A5'

'Corner1:Corner2'

四角形の範囲

四角形の範囲フォームを使用して読み取る範囲を正確に指定します。Corner1 と Corner2 は読み取る範囲を定義する 2 つの対角です。

列数は NumVariables プロパティで指定された数と一致しなければならず、範囲は 1 行のみでなければなりません。

例: 'A5:K5'

'Row1:Row2'

行範囲

Excel の行番号を使用して、開始行と終了行を示して範囲を指定します。

1 行でなければなりません。

例: '5:5'

n

数値インデックス

正のスカラー行インデックスを使用して、データ単位を含む行を指定します。

例: 5

''

指定なしまたは空

変数の単位がないことを示します。

例: ''

データ型: char | string | single | double

置換ルール

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

欠損ルール動作
'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

オブジェクト関数

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

例

すべて折りたたむ

ライブ スクリプトを開く

patients.xls ファイルから 1 つの変数を読み取るためのインポート オプション オブジェクトを作成します。

SpreadsheetImportOptions オブジェクトを初期化し、変数名、変数の型、データ開始セルを指定します。インポート オプション オブジェクトと共に関数 preview を使用して、データをプレビューします。 

opts = spreadsheetImportOptions; 
opts.VariableNames = 'LastName';
opts.VariableTypes = 'categorical';
opts.DataRange = 'A2';
preview('patients.xls',opts)
ans=8×1 table
    LastName
    ________

    Smith   
    Johnson 
    Williams
    Jones   
    Brown   
    Davis   
    Miller  
    Wilson

ファイルから変数をインポートします。 

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

  oneVar      100x1             14309  table
ライブ スクリプトを開く

複数の変数を patients.xls から読み取るためのインポート オプション オブジェクトを作成します。

ファイルの内容に基づいて、変数の数、変数名、変数の型、データ開始位置を定義します。 

numVars = 7;
varNames = {'LastName','Gender','Age','Location','Height','Weight','Smoker'} ;
varTypes = {'char','categorical','int32','char','double','double','logical'} ;
dataStartLoc = 'A2';

関数 spreadsheetImportOptions と変数情報を使用して、インポート オプション オブジェクト opts を初期化します。 

opts = spreadsheetImportOptions('NumVariables',numVars,...
                                'VariableNames',varNames,...
                                'VariableTypes',varTypes,...
                                'DataRange', dataStartLoc);

インポート オプションと共に関数 preview を使用してデータをプレビューします。 

preview('patients.xls',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.xls',opts);
whos T
  Name        Size            Bytes  Class    Attributes

  T         100x7             33987  table

バージョン履歴

R2016b で導入

すべて展開する

参考

| |