ドキュメンテーション

最新のリリースでは、このページがまだ翻訳されていません。 このページの最新版は英語でご覧になれます。

spreadsheetDatastore

スプレッドシート ファイルのデータ ストア

説明

スプレッドシート ファイルの大規模な集合 (必ずしもメモリに収まるとは限らない) を管理するには、SpreadsheetDatastore オブジェクトを使用します。関数 spreadsheetDatastore を使用して SpreadsheetDatastore オブジェクトを作成し、そのプロパティを指定すると、オブジェクト関数を使用してデータをインポートできます。

作成

構文

ssds = spreadsheetDatastore(location)
ssds = spreadsheetDatastore(location,Name,Value)

説明

ssds = spreadsheetDatastore(location) は、location で指定されたデータの集合からスプレッドシートのデータ ストアを作成します。

ssds = spreadsheetDatastore(location,Name,Value) は、1 つ以上の名前と値のペアの引数を使用して、ssds の追加パラメーターとプロパティを指定します。たとえば、spreadsheetDatastore(location,'FileExtensions',{'.xlsx','.xls'}) はファイル拡張子に基づいて、データ ストアに含めるファイルを指定します。

入力引数

すべて展開する

データ ストアに含めるファイルまたはフォルダー。文字ベクトル、文字ベクトルの cell 配列、string スカラーまたは string 配列として指定します。ファイルが現在のフォルダーに存在しない場合、location は絶対パスまたは相対パスでなければなりません。指定したフォルダーのサブフォルダー内にあるファイルは、自動ではデータ ストアに含まれません。サポートされているファイル拡張子は .xls.xlsx.xlsm.xltx および .xltm です。

location を指定するときにワイルドカード文字 (*) を使用できます。この文字は、一致するフォルダー内にある、すべてのファイルまたは一致するすべてのファイルをデータ ストアに含めることを指定します。

ローカルで使用できないファイルについては、次の形式の IRI (国際化リソース識別子) を使用してファイルまたはフォルダーの絶対パスを指定しなければなりません。
hdfs:///path_to_file

Amazon S3™、Windows Azure® Blob Storage、および HDFS™ と共にデータ ストアを使用する方法の詳細については、リモート データの操作を参照してください。

location がフォルダーを表す場合、データ ストアにはサポートされているスプレッドシート ファイルの形式のみが含まれ、他の形式は無視されます。

例: 'file1.xlsx'

例: '../dir/data/file1.xlsx'

例: {'C:\dir\data\file1.xlsx','C:\dir\data\file2.xlsx'}

例: 's3://bucketname/path_to_files/*.xls'

データ型: char | cell | string

名前と値のペアの引数

オプションの Name,Value の引数ペアをコンマ区切りで指定します。Name は引数名で、Value は対応する値です。Name は引用符で囲まなければなりません。Name1,Value1,...,NameN,ValueN のように、複数の名前と値のペアの引数を任意の順序で指定できます。

例: ssds = spreadsheetDatastore('C:\dir\spreadsheetdata','FileExtensions',{'.xls','.xlsm'})

サブフォルダーを含めるかどうかのフラグ。'IncludeSubfolders' と、truefalse、0、1 のいずれかで構成されるコンマ区切りのペアとして指定します。各フォルダー内のすべてのファイルとサブフォルダーを含めるには true を指定し、各フォルダー内のファイルのみを含めるには false を指定します。

'IncludeSubfolders' を指定しない場合、既定値は false です。

例: 'IncludeSubfolders',true

データ型: logical | double

スプレッドシート ファイルの拡張子。'FileExtensions' と、文字ベクトル、文字ベクトルの cell 配列、string スカラーまたは string 配列で構成されるコンマ区切りのペアとして指定します。

  • 'FileExtensions' を指定しない場合、spreadsheetDatastore は、指定パス上の .xls.xlsx.xlsm.xltx および .xltm の拡張子をもつすべてのファイルを自動的に含めます。

  • 非標準のファイル拡張子をもつスプレッドシートを SpreadsheetDatastore に含める場合は、それらの拡張子を明示的に指定します。

  • 拡張子をもたないファイルの SpreadsheetDatastore を作成する場合は、'FileExtensions' を空の文字ベクトル '' として指定します。

例: 'FileExtensions',''

例: 'FileExtensions','.xls'

例: 'FileExtensions',{'.xlsx','.xlsm'}

データ型: char | cell | string

代替ファイル システムのルート パス。'AlternateFileSystemRoots' と string ベクトルまたは cell 配列で構成されるコンマ区切りのペアとして指定します。ローカル マシン上にデータ ストアを作成するが、別のマシン (異なるオペレーティング システムの可能性がある) 上でデータにアクセスして処理する必要がある場合は、'AlternateFileSystemRoots' を使用します。また、Parallel Computing Toolbox™ と MATLAB® Distributed Computing Server™ を使用してデータを処理し、そのデータがローカル マシンに保存され、そのデータのコピーが異なるプラットフォームのクラウドやクラスター マシンにある場合、'AlternateFileSystemRoots' を使用してルート パスを関連付けなければなりません。

  • 相互に対応する 1 組のルート パスを関連付けるには、'AlternateFileSystemRoots' を string ベクトルとして指定します。以下に例を示します。

    ["Z:\datasets","/mynetwork/datasets"]

  • データ ストアに対応する複数の組のルート パスを関連付けるには、複数行を含む cell 配列として 'AlternateFileSystemRoots' を指定します。各行は対応するルート パスの組を表します。cell 配列内の各行を string ベクトル、または文字ベクトルの cell 配列のいずれかとして指定します。以下に例を示します。

    • 'AlternateFileSystemRoots' を string ベクトルの cell 配列として指定します。

      {["Z:\datasets", "/mynetwork/datasets"];...
       ["Y:\datasets", "/mynetwork2/datasets","S:\datasets"]}

    • あるいは、'AlternateFileSystemRoots' を文字ベクトルの cell 配列からなる cell 配列として指定します。

      {{'Z:\datasets','/mynetwork/datasets'};...
       {'Y:\datasets', '/mynetwork2/datasets','S:\datasets'}}

'AlternateFileSystemRoots' の値は、次の条件を満たさなければなりません。

  • 1 行以上の行を含み、各行は 1 組の対応するルート パスを指定する。

  • 各行は複数のルート パスを指定し、各ルート パスは 2 文字以上を含まなければならない。

  • ルート パスは一意で、他のルート パスのサブフォルダーではない。

  • ファイルの場所を指す 1 つ以上のルート パス エントリを含む。

詳細については、異なるマシンまたはクラスターで処理するためのデータ ストアの設定を参照してください。

例: ["Z:\datasets","/mynetwork/datasets"]

データ型: string | cell

テキスト変数の出力データ型。'TextType''char' または 'string' のいずれかで構成されるコンマ区切りのペアとして指定します。

  • 関数 readreadall または preview の出力テーブルにテキスト変数が含まれる場合、'TextType' はこれらの変数のデータ型を指定します。

  • 'TextType''char' の場合、出力は文字ベクトルの cell 配列です。

  • 'TextType''string' の場合、出力の型は string です。

データ型: char | string

これらの名前と値のペアに加えて、このページの任意のプロパティも名前と値のペアとして指定できます。Files プロパティを除きます。

プロパティ

すべて展開する

SpreadsheetDatastore プロパティは datastore オブジェクト内のファイルの形式を記述し、データ ストアからデータを読み取る方法を制御します。datastore オブジェクトの作成時に、名前と値のペアの引数を使用して SpreadsheetDatastore プロパティの値を指定できます。Files プロパティを除きます。オブジェクトの作成後にプロパティの表示または変更を行うには、ドット表記を使用します。

ファイル プロパティ

データ ストアに含まれるファイル。文字ベクトルの cell 配列または string 配列として解決されます。各文字ベクトルまたは string はファイルへの絶対パスです。関数 spreadsheetDatastore および関数 datastorelocation 引数がこれらのファイルを定義します。

cell 配列で最初に指定するファイルにより、データ ストア内のすべてのファイルに対する変数名と形式の情報が決定されます。

例: {'C:\dir\data\file1.xls';'C:\dir\data\file2.xls'}

データ型: cell | string

読み取り時に各シートの先頭からスキップする行数。正の整数として指定します。Range プロパティも指定する場合、NumHeaderLines は指定されたデータ ブロックの先頭からスキップする行数です。

データ型: double

ファイル内のシート。シート名を含む文字ベクトル、文字ベクトルの cell 配列、string スカラーまたは string 配列、あるいはシートのインデックスの数値ベクトルとして指定します。空の文字ベクトル '' は、ファイル内のすべてのシートを含めることを示します。

例: {'sheet1','sheet7'}

例: [3 5 7]

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

行と列の範囲。シート内の矩形のデータ ブロックを定義する文字ベクトルまたは string スカラーとして指定します。空の文字ベクトル '' は、範囲がファイルの先頭からデータの最後までであることを示します。

例: 'B1:T7'

例: 'A:C'

データ型: char | string

データ ストアの最初のファイルの 1 行目を変数名として読み取るかどうかを示すインジケーター。true (1) または false (0) として指定します。

  • true の場合、最初のファイルの最初の非ヘッダー行がそのデータの変数名を決定します。

  • false の場合、最初のファイルの最初の非ヘッダー行にそのデータの 1 行目が含まれます。既定の変数名は Var1Var2 などのように割り当てられます。

データ型: logical | double

データ ストア内の変数名。文字ベクトル、文字ベクトルの cell 配列、string スカラーまたは string 配列として指定します。ファイルに表示される順序で変数名を指定します。変数名を指定しない場合は、データ ストアの最初のファイルの最初の非ヘッダー行から検出されます。VariableNames を文字ベクトルまたは string スカラーとして指定できますが、自動的に文字ベクトルの cell 配列または string 配列に変換されます。VariableNames プロパティを変更する場合、新しい変数名の数は、元の変数名の数と一致しなければなりません。

ReadVariableNamesfalse の場合、VariableNames は既定値の {'Var1','Var2', ...} になります。

例: {'Time','Date','Quantity'}

データ型: char | cell | string

変数の型。各変数のデータ読み取り時の型を示す 'double''char''string''categorical' または 'datetime' として指定します。

変数の型のリストは VariableNames 内の変数に対応します。doublechar および datetime の型はデータから自動的に検出されます。VariableTypes を文字ベクトルまたは string スカラーとして指定できますが、spreadsheetDatastore は自動的に文字ベクトルの cell 配列または string 配列に変換します。

例: {'char','categorical'}

データ型: char | cell | string

previewreadreadall テーブルのプロパティ

ファイルから読み取る変数。文字ベクトル、文字ベクトルの cell 配列、string スカラーまたは string 配列として指定します。各文字ベクトルまたは string には 1 つの変数の名前を含めます。変数名は任意の順序で指定できます。SelectedVariableNames を文字ベクトルまたは string スカラーとして指定できますが、spreadsheetDatastore は自動的に文字ベクトルの cell 配列または string 配列に変換します。

例: {'Var3','Var7','Var4'}

データ型: char | cell | string

選択した変数の型。選択した各変数のデータ読み取り時の型を示す 'double''char''string''categorical' または 'datetime' として指定します。変数の型のリストは SelectedVariableNames 内の変数に対応します。doublechar および datetime の型はデータから自動的に検出されます。SelectedVariableTypes を文字ベクトルまたは string スカラーとして指定できますが、自動的に文字ベクトルの cell 配列または string 配列に変換されます。

例: {'double','datetime'}

データ型: char | cell | string

関数 read の一度の呼び出しで読み取るデータの量。'file' または 'sheet'、あるいは正の整数スカラーとして指定します。

  • ReadSize'file' の場合、read の各呼び出しで一度に 1 ファイルのすべてのデータを読み取ります。

  • ReadSize'sheet' の場合、read の各呼び出しで一度に 1 シートのすべてのデータを読み取ります。

  • ReadSize が正の整数の場合、read の各呼び出しは ReadSize で指定される行数 (あるいはそれ未満の行数でデータの最後に到達するまで) を読み取ります。

ReadSize を整数スカラーから 'file' または 'sheet' に変更した場合、あるいはその逆を行った場合、データ ストアは関数 reset を使用してリセットされます。

データ型: char | string | double

オブジェクト関数

hasdataデータが読み取り可能かどうかを判別
numpartitionsデータ ストアの区画数
partitionデータ ストアを分割する
previewデータ ストア内のデータのサブセット
readデータ ストアのデータの読み取り
readallデータ ストアのすべてのデータの読み取り
resetデータ ストアの初期状態へのリセット
sheetnamesデータ ストアからシート名をクエリする

すべて折りたたむ

ssds = datastore('airlinesmall_subset.xlsx')
ssds = 

  SpreadsheetDatastore with properties:

                      Files: {
                             ' ...\matlab\toolbox\matlab\demos\airlinesmall_subset.xlsx'
                             }
                     Sheets: ''
                      Range: ''

  Sheet Format Properties:
             NumHeaderLines: 0
          ReadVariableNames: true
              VariableNames: {'Year', 'Month', 'DayofMonth' ... and 26 more}
              VariableTypes: {'double', 'double', 'double' ... and 26 more}

  Properties that control the table returned by preview, read, readall:
      SelectedVariableNames: {'Year', 'Month', 'DayofMonth' ... and 26 more}
      SelectedVariableTypes: {'double', 'double', 'double' ... and 26 more}
                   ReadSize: 'file'

ファイル airlinesmall_subset.xlsx を含む SpreadsheetDatastore オブジェクトを作成します。

ssds = spreadsheetDatastore('airlinesmall_subset.xlsx')
ssds = 

  SpreadsheetDatastore with properties:

                      Files: {
                             ' ...\matlab\toolbox\matlab\demos\airlinesmall_subset.xlsx'
                             }
                     Sheets: ''
                      Range: ''

  Sheet Format Properties:
             NumHeaderLines: 0
          ReadVariableNames: true
              VariableNames: {'Year', 'Month', 'DayofMonth' ... and 26 more}
              VariableTypes: {'double', 'double', 'double' ... and 26 more}

  Properties that control the table returned by preview, read, readall:
      SelectedVariableNames: {'Year', 'Month', 'DayofMonth' ... and 26 more}
      SelectedVariableTypes: {'double', 'double', 'double' ... and 26 more}
                   ReadSize: 'file'

ファイルのシート名を表示します。ファイルには、年ごとに 1 つのシートが含まれています。

sheetnames(ssds,1)
ans = 

  Columns 1 through 7

    '1996'    '1997'    '1998'    '1999'    '2000'    '2001'    '2002'

  Columns 8 through 13

    '2003'    '2004'    '2005'    '2006'    '2007'    '2008'

関心のあるデータとして 2 番目のシートの変数 FlightNum を指定し、最初から 8 行をプレビューします。

ssds.Sheets = 2;
ssds.SelectedVariableNames = 'FlightNum';
preview(ssds)
ans = 

    FlightNum
    _________

    1014     
    1201     
     702     
    1184     
    1310     
    1759     
    1242     
    1558     

最初のシートで、変数 DepTime および ArrTime の最初から 3 行のみを読み取ります。

ssds.ReadSize = 3;
ssds.Sheets = 1;
ssds.SelectedVariableNames = {'DepTime','ArrTime'};
read(ssds)
ans = 

    DepTime    ArrTime
    _______    _______

    2117       2305   
    1252       1511   
    1441       1708   

4、5、6 番目のシートからすべてを読み取ります。

ssds.Sheets = 4:6;
readall(ssds);

代替方法

関数 datastore を使用して、SpreadsheetDatastore オブジェクトを作成することもできます。たとえば、ds = datastore(location,'Type','spreadsheet') は、location で指定されたファイルの集合からデータ ストアを作成します。

R2016a で導入