ドキュメンテーション

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

tabularTextDatastore

表形式テキスト ファイルのデータ ストア

説明

列方向のデータや表形式データを含むテキスト ファイルの大規模な集合 (必ずしもメモリに収まるとは限らない) を管理するには、TabularTextDatastore オブジェクトを使用します。表形式データとは、各行に同数のエントリをもつ四角形の表として配置されたデータです。関数 tabularTextDatastore を使用して TabularTextDatastore オブジェクトを作成し、そのプロパティを指定すると、オブジェクト関数を使用してデータのインポートおよび処理ができます。

作成

構文

ttds = tabularTextDatastore(location)
ttds = tabularTextDatastore(location,Name,Value)

説明

ttds = tabularTextDatastore(location) は、location で指定されたデータの集合からデータ ストアを作成します。

ttds = tabularTextDatastore(location,Name,Value) は、1 つ以上の名前と値のペアの引数を使用して、ttds の追加パラメーターとプロパティを指定します。たとえば、tabularTextDatastore(location,'FileExtensions',{'.txt','.csv'}) は、拡張子が .txt.csv である location 内のファイルのみからデータ ストアを作成します。

入力引数

すべて展開する

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

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

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

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

location がフォルダーを表す場合、データ ストアにはサポートされているテキスト ファイル形式のみが含まれ、その他の形式は無視されます。サポートされるファイル形式の拡張子は、.txt.csv.dat.dlm.asc.text または拡張子なしです。

例: 'file1.csv'

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

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

例: 'C:\dir\data\*.text'

データ型: char | cell | string

名前と値のペアの引数

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

例: ttds = tabularTextDatastore('C:\dir\textdata','FileExtensions',{'.csv','.txt'})

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

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

例: 'IncludeSubfolders',true

データ型: logical | double

テキスト ファイルの拡張子。'FileExtensions' と、文字ベクトル、文字ベクトルの cell 配列、string スカラーまたは string 配列で構成されるコンマ区切りのペアとして指定します。指定する拡張子は、サポートされる形式でなくても構いません。サポートされていない拡張子を含める場合は、すべての拡張子を指定してください。空の引用符 '' を使用して、拡張子なしでファイルを表すことができます。

例: 'FileExtensions','.txt'

例: 'FileExtensions',{'.text','.csv'}

データ型: 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 の出力 table にテキスト変数が含まれる場合、'TextType'TabularTextDatastore でのそれらの変数のデータ型を指定します。'TextType''char' の場合、出力は文字ベクトルの cell 配列です。'TextType''string' の場合、出力の型は string です。

データ型: char | string

インポートされる日付と時刻のデータの型。'DatetimeType' と、'datetime' または 'text' のいずれかの値で構成されるコンマ区切りのペアとして指定します。

インポートされる日付と時刻のデータの型
'datetime'

MATLAB の datetime データ型

詳細については、datetime を参照してください。

'text'

'DatetimeType''text' として指定した場合、インポートされる日付と時刻のデータの型は 'TextType' プロパティで指定された値によって決まります。

  • 'TextType''char' の場合、tabularTextdatastore は、文字ベクトルの cell 配列として日付をインポートします。

  • 'TextType''string' の場合、tabularTextdatastore は、string の配列として日付をインポートします。

指定した TextscanFormats プロパティに %D が含まれる場合、tabularTextdatastoreDatetimeType で指定された値を無視します。

例: 'DatetimeType','datetime'

データ型: char | string

duration データの出力データ型。'DurationType''duration' または 'text' のいずれかで構成されるコンマ区切りのペアとして指定します。

インポートされる duration データの型
'duration'

MATLAB の duration データ型

詳細については、duration を参照してください。

'text'

'DurationType''text' として指定した場合、インポートされる duration データの型は 'TextType' パラメーターで指定された値によって決まります。

  • 'TextType''char' の場合、インポート関数は duration データを文字ベクトルの cell 配列として返します。

  • 'TextType''string' の場合、インポート関数は duration データを string の配列として返します。

データ型: char | string

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

DatetimeLocale を指定する場合、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'簡体字中国語中国

メモ

Locale 値により、入力値の解釈方法が決まります。表示形式と言語は、[設定] パネルの [日付と時刻の形式] セクションの [ロケール] オプションによって指定されます。既定の日付と時刻のロケールを変更する方法については、コマンド ウィンドウの設定を参照してください。

データ型: char | string

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

プロパティ

すべて展開する

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

ds = datastore('airlinesmall.csv');
ds.TreatAsMissing = 'NA';
ds.MissingValue = 0;

ファイル プロパティ

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

Files プロパティで最初に指定するファイルは、データ ストアのすべてのファイルに対する変数名と形式の情報を決定します。

このプロパティ値を変更すると、データ ストア関数は TabularTextDatastore のプロパティ値を再評価します。

例: {'C:\dir\data\mydata1.csv';'C:\dir\data\mydata2.csv'}

データ型: cell | string

ファイルのエンコード。次の値のいずれかのような文字ベクトルまたは string スカラーとして指定します。

'IBM866'

'ISO-8859-1'

'windows-847'

'KOI8-R'

'ISO-8859-2'

'windows-1250'

'KOI8-U'

'ISO-8859-3'

'windows-1251'

'Macintosh'

'ISO-8859-4'

'windows-1252'

'US-ASCII'

'ISO-8859-5'

'windows-1253'

'UTF-8'

'ISO-8859-6'

'windows-1254'

 

'ISO-8859-7'

'windows-1255'

 

'ISO-8859-8'

'windows-1256'

 

'ISO-8859-9'

'windows-1257'

 

'ISO-8859-11'

'windows-1258'

 

'ISO-8859-13'

 
 

'ISO-8859-15'

 

データ ストア内の各ファイルがメモリに収まる場合、FileEncoding は次の値のいずれかにすることもできます。

'Big5'

'EUC-KR'

'GB18030'

'Shift_JIS'

'Big5-HKSCS'

'EUC-JP'

'GB2312'

'windows-949'

'CP949'

'EUC-TW'

'GBK'

 

このプロパティ値を変更すると、データ ストア関数は TabularTextDatastore のプロパティ値を再評価します。

データ型: char | string

変数名の読み取り。logical true または logical false として指定します。

  • 指定しない場合、関数 tabularTextDatastore は変数名の有無を自動的に検出します。

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

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

このプロパティ値を変更すると、データ ストア関数は TabularTextDatastore のプロパティ値を再評価します。

データ型: logical

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

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

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

データ型: cell | string

テキスト形式のプロパティ

ファイルの先頭からスキップする行数。非負の整数として指定します。指定しない場合、関数 tabularTextDatastore はスキップする行数を自動的に検出します。

関数 tabularTextDatastore は、指定したヘッダーの行数を無視してから、変数名またはデータを読み取ります。

このプロパティ値を変更すると、データ ストア関数は TabularTextDatastore のプロパティ値を再評価します。

データ型: double

フィールドの区切り記号。文字ベクトル、文字ベクトルの cell 配列、string スカラーまたは string 配列として指定します。複数の区切り記号は、文字ベクトルの cell 配列または string 配列で指定します。指定しない場合、関数 tabularTextDatastore は区切り記号を自動的に検出します。

例: '|'

例: {';','*'}

ファイル内で連続する区切り文字を、それらの間に空のフィールドをもつ個別の区切り記号として解釈します。指定しない場合、既定で読み取り関数が自動的に区切り記号を検出します。

次のエスケープ シーケンスの 1 つを区切り記号として指定した場合、そのシーケンスを対応する制御文字に変換します。

\bバックスペース
\n改行
\rキャリッジ リターン
\tタブ
\\バックスラッシュ (\)

このプロパティ値を変更すると、データ ストア関数は TabularTextDatastore のプロパティ値を再評価します。

データ型: char | cell | string

行区切り記号文字。文字ベクトルまたは string スカラーとして指定します。これは単一の文字か、'\r''\n' または '\r\n' のいずれかでなければなりません。

このプロパティ値を変更すると、データ ストア関数は TabularTextDatastore のプロパティ値を再評価します。

例: ':'

データ型: char | string

欠損値として処理する数値。単一の文字ベクトル、文字ベクトルの cell 配列、string スカラーまたは string 配列として指定します。TreatAsMissing として指定された値には、MissingValue プロパティで定義された値が代入されます。たとえば、MissingValueNaN として定義され、TreatAsMissing'NA' として定義されたとします。その場合、インポートされたデータ内にあるすべての 'NA'NaN に置き換えられます。

このオプションは数値フィールドのみに適用されます。また、このプロパティは、関数 textscan の名前と値のペア引数 TreatAsEmpty と等価です。

このプロパティ値を変更すると、データ ストア関数は TabularTextDatastore のプロパティ値を再評価します。

例: 'NA'

例: '-99'

例: {'-',''}

データ型: char | cell | string

区切りテキスト ファイル内の欠損値フィールドの値。スカラーとして指定します。このプロパティは、関数 textscan の名前と値のペア引数 EmptyValue と等価です。

データ型: double

高度なテキスト形式のプロパティ

データ フィールドの形式。文字ベクトルの cell 配列または string 配列として指定します。各文字ベクトルまたは string は 1 つの変換指定子を含みます。

TextscanFormats プロパティを指定または変更する場合、関数 textscanformatSpec 引数に対して受け入れるものと同じ変換指定子を使用できます。TextscanFormats の有効値には、アスタリスク (*) 文字を使用してフィールドをスキップする変換指定子と、リテラル テキストをスキップする変換指定子が含まれます。変換指定子の数は、VariableNames プロパティ内の変数の数と一致しなければなりません。

  • TextscanFormats の値にアスタリスク文字 (*) を使用してフィールドをスキップする変換指定子が含まれる場合、SelectedVariableNames プロパティの値は自動的に更新されます。MATLAB は %*q 変換指定子を使用して SelectedVariableNames プロパティで省略されたフィールドをスキップし、フィールドの内容をリテラル文字ベクトルとして処理します。固定幅のファイルについては、適切な変換指定子をフィールド幅と共に使用してスキップするフィールドを指定します。たとえば、%*52c は 52 文字を含むフィールドをスキップします。

  • TextscanFormats に値を指定しない場合、datastore は、データ ストアにある最初のファイルの最初の非ヘッダー行からテキストをスキャンすることにより、データ フィールドの形式を決定します。

例: {'%s','%s','%f'}

データ型: cell | string

指数文字。文字ベクトルまたは string スカラーとして指定します。既定の指数文字は eEd および D です。

データ型: char | string

ファイル内のコメントのスタイル。文字ベクトル、文字ベクトルの cell 配列、string スカラーまたは string 配列として指定します。

たとえば、テキストと同じ行にある後続の文字を無視するには、'%' を指定します。テキストの間にある文字を無視するには {'/*','*/'} を指定します。

TabularTextDatastore から読み取る場合、関数 read は、各フィールドの先頭のみコメントをチェックします (フィールド内はコメント チェック対象外です)。

このプロパティ値を変更すると、データ ストア関数は TabularTextDatastore のプロパティ値を再評価します。

例: 'CommentStyle',{'/*', '*/'}

データ型: char | cell | string

空白文字。1 文字以上の文字ベクトルまたは string スカラーとして指定します。

次のエスケープ シーケンスの 1 つを空白文字として指定した場合、関数 datastore は、シーケンスを対応する制御文字に変換します。

\bバックスペース
\n改行
\rキャリッジ リターン
\tタブ
\\バックスラッシュ (\)

このプロパティ値を変更すると、データ ストア関数は TabularTextDatastore のプロパティ値を再評価します。

例: ' \b\t'

データ型: char | string

複数の区切り記号の取り扱い。true または false のいずれかとして指定します。true の場合、datastore は連続した区切り記号を 1 つの区切り記号として扱います。区切り記号が空白で分けられて繰り返された場合も、1 つの区切り記号として扱われます。

このプロパティ値を変更すると、データ ストア関数は TabularTextDatastore のプロパティ値を再評価します。

previewreadreadall によって返される table を制御するプロパティ

ファイルから読み取る変数。文字ベクトルの cell 配列または string 配列として指定します。各文字ベクトルまたは string は 1 つの変数の名前を含みます。変数名は任意の順序で指定できます。

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

データ型: cell | string

選択した読み取り対象の変数の形式。文字ベクトルの cell 配列または string 配列として指定します。各文字ベクトルまたは string は 1 つの変換指定子を含みます。読み取り対象の変数は、SelectedVariableNames プロパティで指定されます。SelectedFormats 内の文字ベクトルまたは string の数は、読み取り対象の変数の数と一致しなければなりません。

関数 textscan が受け入れた変換指定子と同じ指定子を使用できます。これにはリテラル テキストをスキップする指定子が含まれます。ただし、フィールドをスキップする変換指定子は使用できません。つまり、変換指定子にアスタリスク文字 (*) を含めることはできません。

例: {'%d','%d'}

データ型: cell | string

関数 read の 1 回の呼び出しで読み取るデータの量。正のスカラーまたは 'file' として指定します。

  • ReadSize が正の整数の場合、read へのそれぞれの呼び出しは最大で ReadSize の行数を読み取ります。

  • ReadSize'file' の場合、read を呼び出すたびに、1 つのファイルにあるすべてのデータが読み取られます。

ReadSize を数値スカラーから 'file' に変更したり、その逆の変更を行うと、MATLAB はデータ ストアをデータの読み取り前の状態にリセットします。

データ型: double | char | string

テキスト変数の出力データ型。'char' または 'string' として指定します。TextType は、%s%q または [...] で書式設定されたテキスト変数のデータ型を指定します。

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

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

データ型: char | string

オブジェクト関数

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

すべて折りたたむ

テキスト ファイル airlinesmall.csv を含む TabularTextDatastore オブジェクトを作成します。

ttds = tabularTextDatastore('airlinesmall.csv')
ttds = 

  TabularTextDatastore with properties:

                      Files: {
                             ' ...\matlab\toolbox\matlab\demos\airlinesmall.csv'
                             }
               FileEncoding: 'UTF-8'
          ReadVariableNames: true
              VariableNames: {'Year', 'Month', 'DayofMonth' ... and 26 more}

  Text Format Properties:
             NumHeaderLines: 0
                  Delimiter: ','
               RowDelimiter: '\r\n'
             TreatAsMissing: ''
               MissingValue: NaN

  Advanced Text Format Properties:
            TextscanFormats: {'%f', '%f', '%f' ... and 26 more}
         ExponentCharacters: 'eEdD'
               CommentStyle: ''
                 Whitespace: ' \b\t'
    MultipleDelimitersAsOne: false

  Properties that control the table returned by preview, read, readall:
      SelectedVariableNames: {'Year', 'Month', 'DayofMonth' ... and 26 more}
            SelectedFormats: {'%f', '%f', '%f' ... and 26 more}
                   ReadSize: 20000 rows

表形式データが格納されたサンプル ファイル airlinesmall.csv からデータ ストアを作成します。

ds = tabularTextDatastore('airlinesmall.csv','TreatAsMissing','NA');

データ ストア内の変数を表示します。

ds.VariableNames
ans = 1x29 cell array
  Columns 1 through 5

    {'Year'}    {'Month'}    {'DayofMonth'}    {'DayOfWeek'}    {'DepTime'}

  Columns 6 through 9

    {'CRSDepTime'}    {'ArrTime'}    {'CRSArrTime'}    {'UniqueCarrier'}

  Columns 10 through 13

    {'FlightNum'}    {'TailNum'}    {'ActualElapsedTime'}    {'CRSElapsedTime'}

  Columns 14 through 18

    {'AirTime'}    {'ArrDelay'}    {'DepDelay'}    {'Origin'}    {'Dest'}

  Columns 19 through 22

    {'Distance'}    {'TaxiIn'}    {'TaxiOut'}    {'Cancelled'}

  Columns 23 through 25

    {'CancellationCode'}    {'Diverted'}    {'CarrierDelay'}

  Columns 26 through 28

    {'WeatherDelay'}    {'NASDelay'}    {'SecurityDelay'}

  Column 29

    {'LateAircraftDelay'}

SelectedVariableNames プロパティを変更して対象の変数を指定します。

ds.SelectedVariableNames = {'Year','Month','Cancelled'};

対象の変数はデータ ストアの作成時に指定することもできます。

ds = tabularTextDatastore('airlinesmall.csv','TreatAsMissing','NA','SelectedVariableNames',{'Year','Month','Cancelled'});

表形式データが格納されたサンプル ファイル airlinesmall.csv からデータ ストアを作成します。

ds = tabularTextDatastore('airlinesmall.csv','TreatAsMissing','NA');

対象の変数を指定します。

ds.SelectedVariableNames = {'Year','Month','UniqueCarrier'};

SelectedFormats プロパティを表示します。

ds.SelectedFormats
ans = 1x3 cell array
    {'%f'}    {'%f'}    {'%q'}

SelectedFormats プロパティは、変数 Year および Month を浮動小数点値の列として解釈し、変数 UniqueCarrier をテキストの列として解釈することを示しています。

SelectedFormats プロパティを変更して、最初の 2 つの変数を符号付き整数として読み取り、3 番目の変数をカテゴリカル値として読み取るように設定します。

ds.SelectedFormats = {'%d','%d','%C'};

データをプレビューします。

T = preview(ds)
T=8×3 table
    Year    Month    UniqueCarrier
    ____    _____    _____________

    1987     10           PS      
    1987     10           PS      
    1987     10           PS      
    1987     10           PS      
    1987     10           PS      
    1987     10           PS      
    1987     10           PS      
    1987     10           PS      

代替方法

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

R2014b で導入