Main Content

このページの翻訳は最新ではありません。ここをクリックして、英語の最新版を参照してください。

readtimetable

ファイルからの timetable の作成

説明

TT = readtimetable(filename) は、ファイルから列方向のデータを読み取ることにより timetable を作成します。

readtimetable は、ファイル拡張子からファイル形式を判定します。

  • 区切りテキスト ファイルの場合、.txt.dat または .csv

  • スプレッドシート ファイルの場合、.xls.xlsb.xlsm.xlsx.xltm, .xltx または .ods

  • 拡張マークアップ言語 (XML) の場合、.xml

テキスト ファイルおよびスプレッドシート ファイルの場合、readtimetable は、ファイルの列ごとに 1 つの変数を TT に作成し、ファイルの最初の行から変数名を読み取ります。XML ファイルの場合、readtimetable は、timetable 変数として検出された要素ノードまたは属性ノードごとに 1 つの変数を T に作成します。変数の名前は要素および属性の名前に対応します。

readtimetable は、表形式データの型が datetime または duration の最初の列を timetable の行時間に設定します。残りの列は timetable の変数になります。

TT = readtimetable(filename,opts) は、さらにインポート オプション opts を使用します。

TT = readtimetable(___,Name,Value) は、1 つ以上の名前と値のペアの引数で指定された追加のオプションを使用して、ファイルから timetable を作成します。名前と値のペアを指定する前に、前述の構文の入力引数のいずれかを使用してください。

データ特有のインポート オプションを設定するには、opts オブジェクトを使用するか、名前と値のペアを指定できます。opts に加えて名前と値のペアを指定する場合、readtimetable がサポートするのは次の名前と値のペアのみです。

  • テキストおよびスプレッドシートのパラメーター — ReadVariableNamesRowTimesSampleRateTimeStepStartTime

  • テキストのみのパラメーター — DateLocaleEncoding

  • スプレッドシートのみのパラメーター — SheetUseExcel

すべて折りたたむ

コンマ区切りのテキスト ファイルからテーブルを作成します。

TT = readtimetable('outages.csv');

テーブルの概要を表示します。timetable の作成時に行時間のパラメーターを設定しない場合、関数 readtimetable はデータ OutageTime 内の最初の datetime 変数または duration 変数を検出し、行時間の変数として指定します。残りの変数は timetable の変数になります。

summary(TT)
RowTimes:

    OutageTime: 1468x1 datetime
        Values:
            Min         2002-02-01 12:18 
            Median      2010-03-18 21:05 
            Max         2014-01-15 02:41 

Variables:

    Region: 1468x1 cell array of character vectors

    Loss: 1468x1 double

        Values:

            Min             0       
            Median          180.26  
            Max             23418   
            NumMissing      604     

    Customers: 1468x1 double

        Values:

            Min             0           
            Median          75765       
            Max             5.9689e+06  
            NumMissing      328         

    RestorationTime: 1468x1 datetime

        Values:

            Min             2002-02-07 16:50  
            Median          2010-03-31 10:54  
            Max             2042-09-18 23:31  
            NumMissing      29                

    Cause: 1468x1 cell array of character vectors

テキスト ファイルのインポート オプションを検出し、変数の型を指定して、データから timetable を作成します。

ファイルからインポート オプション オブジェクトを作成し、変数オプションを調べます。

opts = detectImportOptions('outages.csv');
opts.VariableOptions
ans = 
  1x6 heterogeneous VariableImportOptions (TextVariableImportOptions, DatetimeVariableImportOptions, NumericVariableImportOptions) array with properties:

    Name
    Type
    FillValue
    TreatAsMissing
    QuoteRule
    Prefixes
    Suffixes
    EmptyFieldRule

オプション オブジェクトを変更してデータ内の変数の目的のデータ型を指定します。変数 Region および Cause のデータ型を categorical に変更します。

opts = setvartype(opts,{'Region','Cause'},{'categorical','categorical'});

readtimetable をオプション オブジェクトと共に使用して、timetable をインポートします。次に、timetable の概要を表示します。

TT = readtimetable('outages.csv',opts);
summary(TT)
RowTimes:

    OutageTime: 1468x1 datetime
        Values:
            Min         2002-02-01 12:18 
            Median      2010-03-18 21:05 
            Max         2014-01-15 02:41 

Variables:

    Region: 1468x1 categorical

        Values:

            MidWest        142   
            NorthEast      557   
            SouthEast      389   
            SouthWest       26   
            West           354   

    Loss: 1468x1 double

        Values:

            Min             0       
            Median          180.26  
            Max             23418   
            NumMissing      604     

    Customers: 1468x1 double

        Values:

            Min             0           
            Median          75765       
            Max             5.9689e+06  
            NumMissing      328         

    RestorationTime: 1468x1 datetime

        Values:

            Min             2002-02-07 16:50  
            Median          2010-03-31 10:54  
            Max             2042-09-18 23:31  
            NumMissing      29                

    Cause: 1468x1 categorical

        Values:

            attack                294   
            earthquake              2   
            energy emergency      188   
            equipment fault       156   
            fire                   25   
            severe storm          338   
            thunder storm         201   
            unknown                24   
            wind                   95   
            winter storm          145   

コンマ区切りのテキスト ファイルから table を読み取り、任意の行時間変数である timetable を作成します。

インポート オプション オブジェクトを作成し、表形式データをプレビューします。

opts = detectImportOptions('outages.csv');
preview('outages.csv',opts)
ans=8×6 table
       Region           OutageTime        Loss     Customers     RestorationTime            Cause       
    _____________    ________________    ______    __________    ________________    ___________________

    {'SouthWest'}    2002-02-01 12:18    458.98    1.8202e+06    2002-02-07 16:50    {'winter storm'   }
    {'SouthEast'}    2003-01-23 00:49    530.14    2.1204e+05                 NaT    {'winter storm'   }
    {'SouthEast'}    2003-02-07 21:15     289.4    1.4294e+05    2003-02-17 08:14    {'winter storm'   }
    {'West'     }    2004-04-06 05:44    434.81    3.4037e+05    2004-04-06 06:10    {'equipment fault'}
    {'MidWest'  }    2002-03-16 06:18    186.44    2.1275e+05    2002-03-18 23:23    {'severe storm'   }
    {'West'     }    2003-06-18 02:49         0             0    2003-06-18 10:54    {'attack'         }
    {'West'     }    2004-06-20 14:39    231.29           NaN    2004-06-20 19:16    {'equipment fault'}
    {'West'     }    2002-06-06 19:28    311.86           NaN    2002-06-07 00:51    {'equipment fault'}

変数 RestorationTime を timetable の行時間変数に指定して、timetable を作成します。次に、timetable の概要を表示します。

TT = readtimetable('outages.csv','RowTimes','RestorationTime');
summary(TT)
RowTimes:

    RestorationTime: 1468x1 datetime
        Values:
            Min             2002-02-07 16:50 
            Median          2010-03-31 10:54 
            Max             2042-09-18 23:31 
            NumMissing      29               

Variables:

    Region: 1468x1 cell array of character vectors

    OutageTime: 1468x1 datetime

        Values:

            Min       2002-02-01 12:18
            Median    2010-03-18 21:05
            Max       2014-01-15 02:41

    Loss: 1468x1 double

        Values:

            Min             0       
            Median          180.26  
            Max             23418   
            NumMissing      604     

    Customers: 1468x1 double

        Values:

            Min             0           
            Median          75765       
            Max             5.9689e+06  
            NumMissing      328         

    Cause: 1468x1 cell array of character vectors

スプレッドシート ファイルから timetable を作成し、入力データを書式設定します。たとえば、ファイル quarterlyFinances1999To2019.csv から timetable を作成し、タイム スタンプの開始日と、各タイム スタンプ間の時間を指定し、データから "$" 記号を削除します。

ファイル quarterlyFinances1999To2019.csv のデータを timetable として読み取ります。連続する行時間の間の時間の長さを、1999 年 1 月 1 日から始まる 1 カレンダー四半期として指定します。'VariableNamingRule'preserve に設定し、変数名に含まれる空白をそのまま残します。'TrimNonNumeric'true に設定し、データの数値の前にある "$" 記号を削除します。

TT = readtimetable("quarterlyFinances1999To2019.csv","TimeStep", calquarters(1),"StartTime", datetime(1999, 1, 1),...
    "VariableNamingRule", "preserve", "TrimNonNumeric", true);

データの概要を表示します。

summary(TT)
RowTimes:

    Time: 80x1 datetime
        Values:
            Min         01-Jan-1999 
            Median      16-Nov-2008 
            Max         01-Oct-2018 

Variables:

    Net Sales: 80x1 double

        Values:

            Min            35066
            Median    1.0407e+05
            Max       1.7684e+05

    Cost of Sales: 80x1 double

        Values:

            Min        18106  
            Median     48624  
            Max        77742  

    Gross Margin: 80x1 double

        Values:

            Min        14563  
            Median     56719  
            Max        99097  

    Research and Development Expenses: 80x1 double

        Values:

            Min        4904.9 
            Median      24637 
            Max         45234 

    Administrative Expenses: 80x1 double

        Values:

            Min        1047.4 
            Median     2015.3 
            Max        2811.5 

    Total Operating Expenses: 80x1 double

        Values:

            Min        5992.5 
            Median      26518 
            Max         48045 

    Net Income: 80x1 double

        Values:

            Min        7634.3 
            Median      28586 
            Max         51051 

    Total Shares: 80x1 double

        Values:

            Min           822 
            Median     1820.5 
            Max          2710 

    Earnings per Share: 80x1 double

        Values:

            Min          6.52 
            Median     15.515 
            Max         24.62 

入力引数

すべて折りたたむ

読み取るファイルの名前。文字ベクトルまたは string スカラーとして指定します。

ファイルの場所によって、filename は次のいずれかの形式をとります。

場所

形式

現在のフォルダー、または MATLAB® パス上のフォルダー

ファイル名を filename で指定します。

例: 'myFile.txt'

フォルダー内のファイル

ファイルが現在のフォルダーまたは MATLAB パス上のフォルダーにない場合は、filename に絶対パス名または相対パス名を指定します。

例: 'C:\myFolder\myFile.xlsx'

例: 'dataDir\myFile.txt'

インターネット URL

ファイルをインターネットの Uniform Resource Locator (URL) として指定する場合、filename には 'http://' または 'https://' のプロトコル タイプが含まれていなければなりません。

例: 'http://hostname/path_to_file/my_data.csv'

リモートの場所

リモートの場所に保存されたファイルの場合、filename は次の形式で指定されたファイルの絶対パスを含まなければなりません。

scheme_name://path_to_file/my_file.ext

リモートの場所に基づいて、scheme_name には次の表の値のいずれかを指定できます。

リモートの場所scheme_name
Amazon S3™s3
Windows Azure® Blob Storagewasb, wasbs
HDFS™hdfs

詳細については、リモート データの操作を参照してください。

例: 's3://bucketname/path_to_file/my_file.csv'

  • filename にファイル拡張子が含まれる場合、インポート関数は拡張子からファイル形式を判別します。それ以外の場合は、名前と値のペアの引数 'FileType' を指定してファイルの種類を示さなければなりません。

  • Microsoft® Excel® ソフトウェアがインストールされている Windows® システムで、インポート関数は、使用している Excel のバージョンで認識されるすべての Excel スプレッドシート ファイル形式を読み取ります。

  • システムに Excel for Windows がない場合、または MATLAB Online™ を使用している場合、インポート関数は UseExcel プロパティが false に設定されている状態で動作し、.xls, .xlsx, .xlsm, .xltx, and .xltm ファイルのみを読み取ります。

  • 区切りテキスト ファイルの場合、インポート関数はファイル内の空のフィールドを、NaN (数値変数の場合) または空の文字ベクトル (テキスト変数の場合) のどちらかに変換します。テキスト ファイルのすべての行には同じ数の区切り記号がなければなりません。インポート関数はファイル内の意味のない空白を無視します。

データ型: char | string

ファイル インポート オプション。関数 detectImportOptions によって作成された SpreadsheetImportOptionsDelimitedTextImportOptionsFixedWidthImportOptions、または XMLImportOptions オブジェクトとして指定します。opts オブジェクトにはデータ インポートのプロセスを制御するプロパティが含まれています。各オブジェクトのプロパティの詳細については、該当するオブジェクトのページを参照してください。

ファイルの種類出力
スプレッドシート ファイルSpreadsheetImportOptions オブジェクト (SheetDataRange、および VariableNames プロパティにのみ使用可能)
テキスト ファイルDelimitedTextImportOptions オブジェクト
固定幅テキスト ファイルFixedWidthImportOptions オブジェクト
XML ファイルXMLImportOptions オブジェクト

名前と値の引数

引数のオプションのペアを Name1=Value1,...,NameN=ValueN として指定します。ここで Name は引数名で、Value は対応する値です。名前と値の引数は他の引数の後になければなりませんが、ペアの順序は重要ではありません。

R2021a より前では、コンマを使用してそれぞれの名前と値を区切り、Name を引用符で囲みます。

例: 'NumHeaderLines',5 は、表形式データの前の最初の 5 行がヘッダー行であることを示します。

サポートされるすべてのファイルの種類

すべて折りたたむ

HTTP または HTTPS 要求オプション。weboptions オブジェクトとして指定します。weboptions オブジェクトは、指定した filename がプロトコル タイプ "http://" または "https://" を含むインターネット URL である場合にデータをインポートする方式を決定します。

テキスト ファイルとスプレッドシート ファイル

すべて折りたたむ

ファイルの種類。'FileType''text' または 'spreadsheet' で構成されるコンマ区切りのペアとして指定します。

filename にファイル拡張子が含まれない場合、または次の拡張子以外の場合は、名前と値のペアの引数 'FileType' を指定します。

  • 区切りテキスト ファイルの場合、.txt.dat または .csv

  • スプレッドシート ファイルの場合、.xls.xlsb.xlsm.xlsx.xltm, .xltx または .ods

例: 'FileType','text'

データ型: char | string

ファイルのヘッダーの行数。'NumHeaderLines' と正の整数で構成されるコンマ区切りのペアとして指定します。指定しない場合、ファイル ヘッダーの行数はインポート関数により自動検出されます。

例: 'NumHeaderLines',7

データ型: single | double

必要な変数の数。'ExpectedNumVariables' と正の整数で構成されるコンマ区切りのペアとして指定します。指定しない場合、変数の数はインポート関数により自動検出されます。

データ型: single | double

テキストまたはスプレッドシート ファイルから読み取るデータの部分。'Range' と、次のいずれかの形式をとる文字ベクトル、string スカラー、または数値ベクトルで構成されるコンマ区切りのペアとして指定します。

Range の指定方法説明

開始セル

'Cell' または [row col]

文字ベクトル、string スカラー、または 2 要素数値ベクトルとして、データの開始セルを指定します。

  • Excel の A1 表記法を使用した列の文字および行番号を含む文字ベクトルまたは string スカラー。たとえば、A5 は列 A と行 5 が交わる場所にあるセルの識別子です。

  • 開始行と開始列を示す [row col] 形式の 2 要素数値ベクトル。

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

例: 'A5' または [5 1]

四角形の範囲

'Corner1:Corner2' または [r1 c1 r2 c2]

次の四角形の範囲フォームのいずれかを使用して、読み取る範囲を正確に指定します。

  • 'Corner1:Corner2' — 読み取る領域を定義する 2 つの対角 Corner1 および Corner2 (Excel の A1 表記法) を使用して範囲を指定します。たとえば、'C2:N15' のようになります。

  • [r1 c1 r2 c2] — 開始行、開始列、終了行および終了列を含む 4 要素数値ベクトルを使用して範囲を指定します。たとえば、[2 3 15 13] のようになります。

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

行範囲または列範囲

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

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

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

例: '5:500'

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

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

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

例: 'A:K'

開始行番号

n

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

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

例: 5

Excel の名前付き範囲

'NamedRange'

Excel では、スプレッドシート内の範囲を表す名前を作成できます。たとえば、スプレッドシートの四角形部分を選択して 'myTable' という名前を付けることができます。スプレッドシート内にそのような名前付き範囲が存在する場合、インポート関数はその名前を使用して範囲を読み取ることができます。

例: 'Range','myTable'

指定なしまたは空

''

指定しない場合、使用範囲はインポート関数により自動検出されます。

例: 'Range',''

メモ: "使用範囲" とは、スプレッドシート内で実際にデータが含まれている四角形部分を指します。インポート関数は、データを含まない先頭と末尾の行と列をすべてトリミングして、使用範囲を自動的に検出します。空白のみのテキストはデータと見なされ、使用範囲内に取得されます。

データ型: char | string | double

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

  • 'char' — テキスト データを文字ベクトルとして MATLAB にインポートします。

  • 'string' — テキスト データを string 配列として MATLAB にインポートします。

例: 'TextType','char'

インポートされる日付と時刻のデータの型。'DatetimeType' と、'datetime''text''exceldatenum' のいずれかの値で構成されるコンマ区切りのペアとして指定します。値 'exceldatenum' はスプレッドシート ファイルのみに適用され、テキスト ファイルに対しては有効ではありません。

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

MATLAB の datetime データ型

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

'text'

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

  • 'TextType''char' に設定されている場合、インポート関数は日付を文字ベクトルの cell 配列として返します。

  • 'TextType''string' に設定されている場合、インポート関数は日付を string の配列として返します。

'exceldatenum'

Excel のシリアル日付値

シリアル日付値は、指定された基準日からの日数に等しい単一の数値です。Excel のシリアル日付値では MATLAB のシリアル日付値とは異なる基準日が使用されています。Excel の日付の詳細については、https://support.microsoft.com/en-us/kb/214330 を参照してください。

データ型: char | string

欠損データとして解釈するテキスト。文字ベクトル、string スカラー、文字ベクトルの cell 配列、または string 配列として指定します。

例: 'TreatAsMissing',{'NA','TBD'} は、インポート関数に NA または TBD のすべての出現を欠損フィールドとして処理するように指示します。

データ型: char | string | cell

'ReadVariableNames' と、true または false のいずれかで構成されるコンマ区切りのペアとして指定される最初の行を変数名として読み取ります。指定しない場合、インポート関数は変数名の有無を自動的に検出します。

インジケーター

説明

true

読み取る領域の最初の行にテーブルの変数名が含まれている場合に使用します。インポート関数は、検出した変数名を使用して T の各列に変数を作成します。

false

読み取る領域の最初の行にテーブルのデータが含まれている場合に使用します。インポート関数は、形式 'Var1',...,'VarN' の既定の変数名を作成します。ここでは、N は変数の数です。

指定なし 指定しない場合、インポート関数は true または false を自動的に検出し、それに応じて続行します。

opts に加えて ReadVariableNames の名前と値のペアを指定する場合、インポート関数は次のように続行します。

  • ReadVariableNamestrue に設定されている場合、インポート関数は、インポート オプション オブジェクトの VariableNamesRange または VariableNamesLine プロパティを使用して、指定されたファイルから変数名を読み取ります。

  • ReadVariableNamesfalse に設定されている場合、インポート関数は、インポート オプション オブジェクトの VariableNames プロパティから変数名を読み取ります。

データ型: logical

行時間変数。'RowTimes' および変数名または時間ベクトルで構成されるコンマ区切りのペアとして指定します。

  • 変数名は、datetime または duration の値を含む入力 table 内の任意の変数名を含む文字ベクトルまたは string スカラーでなければなりません。変数名で指定される変数は、行の行時間のラベルを提供します。入力 table の残りの変数は、timetable の変数になります。

  • 時間ベクトルは datetime ベクトルまたは duration ベクトルでなければなりません。時間ベクトルの要素数は、入力テーブルの行数と等しくなければなりません。時間ベクトルの時間値は、一意であったり、並べ替えられていたり、規則的な値である必要はありません。入力 table のすべての変数は timetable の変数になります。

データ型: char | string | datetime | duration

行時間のサンプル レート。'SampleRate' と正の数値スカラーで構成されるコンマ区切りのペアとして指定します。サンプル レートは、出力 timetable の時間ベクトルの 1 秒あたりのサンプル数 (Hz) です。

'SampleRate' を使用して timetable の行時間ベクトルを指定する場合、既定の最初の行時間 (開始時間) はゼロ秒です。開始時間をゼロ以外に設定するには、'StartTime' の名前と値のペアを指定します。

データ型: double

行時間の間のタイム ステップ。'TimeStep' および duration スカラーまたは calendarDuration スカラーで構成されるコンマ区切りのペアとして指定します。'TimeStep' パラメーターの値は、連続する行時間の間の時間の長さを指定します。インポート関数は、タイム ステップ値を使用して等間隔の行時間を計算します。

'TimeStep' を使用して timetable の行時間ベクトルを指定する場合、既定の最初の行時間 (開始時間) はゼロ秒です。開始時間をゼロ以外に設定するには、'StartTime' の名前と値のペアを指定します。

'TimeStep' がカレンダー期間の値である場合、'StartTime' は datetime 値でなければなりません。

データ型: duration | calendarDuration

行時間の開始時間。StartTime と、datetime スカラーまたは duration スカラーで構成されるコンマ区切りのペアとして指定します。

timetable の時間ベクトルを定義するには、'StartTime''SampleRate' または 'TimeStep' の名前と値のペアの引数と共に使用します。

開始時間のデータ型により、行時間ベクトルのデータ型が決まります。

  • 開始時間が datetime 値の場合、timetable の行時間は datetime 値になる。

  • 開始時間が duration 値の場合、行時間は duration になる。

データ型: datetime | duration

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

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

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

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

データ型: char | string

テキスト ファイルのみ

すべて折りたたむ

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

例: 'Delimiter','|'

例: 'Delimiter',{';','*'}

データ型: char | string | cell

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

例: 'Whitespace',' _'

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

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

例: 'LineEnding','\n'

例: 'LineEnding','\r\n'

例: 'LineEnding',{'\b',':'}

データ型: char | string | cell

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

たとえば、パーセント記号に続く同じ行のテキストを無視するには、CommentStyle'%' に指定します。

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

データ型: char | string | cell

ファイルに関連付けられた文字エンコード スキーム。'Encoding''system' で構成されるコンマ区切りのペア、または標準の文字エンコード スキーム名として指定します。エンコードを指定しない場合、関数 readtimetable は自動文字セット検出を使用して、ファイルの読み取り時にエンコードを判断します。

インポート オプションに加えて引数 'Encoding' を指定した場合、関数 readtimetable'Encoding' で指定された値を使用して、インポート オプションで定義されたエンコードをオーバーライドします。

例: 'Encoding','UTF-8' は、UTF-8 をエンコードとして使用します。

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

データ型: 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

日付を読み取るロケール。'DateLocale' と、xx_YY の形式の文字ベクトルまたは string スカラーで構成されるコンマ区切りのペアとして指定します。ここで、次のようになります。

  • YY は国を表す大文字の ISO 3166-1 alpha-2 コード

  • xx は言語を表す小文字 2 文字の ISO 639-1 コード

次の表に一般的なロケールの値を示します。

ロケール 言語
'de_DE'ドイツ語ドイツ
'en_GB'英語英国
'en_US'英語米国
'es_ES'スペイン語スペイン
'fr_FR'フランス語フランス
'it_IT'イタリア語イタリア
'ja_JP'日本語日本
'ko_KR'韓国語韓国
'nl_NL'オランダ語オランダ
'zh_CN'簡体字中国語中国

%D 書式指定子を使用してテキストを datetime 値として読み取る場合、DateLocale を使用して、インポート関数が月と曜日の名前および略語を解釈するためのロケールを指定します。

インポート オプション opts に加えて引数 DateLocale を指定した場合、インポート関数は引数 DateLocale で指定された値を使用して、インポート オプションで定義されたロケールをオーバーライドします。

例: 'DateLocale','ja_JP'

数値変数内の小数点の区切りを示す文字。文字ベクトルまたは string スカラーとして指定します。インポート関数は、DecimalSeparator の名前と値のペアで指定される文字を使用して、数値の整数部分と小数部分を区別します。

整数データ型に変換すると、小数部分をもつ数値は最も近い整数に丸められます。

例: 名前と値のペアが 'DecimalSeparator',',' のように指定される場合、インポート関数はテキスト "3,14159" を数値 3.14159 としてインポートします。

データ型: char | string

数値変数内の 3 桁ごとの区切りを示す文字。文字ベクトルまたは string スカラーとして指定します。3 桁ごとの区切り文字は視覚的な区切りとして機能し、数値を 3 桁ごとにグループ化します。インポート関数は、ThousandsSeparator の名前と値のペアで指定される文字を使用して、インポートされる数値を解釈します。

例: 名前と値のペアが 'ThousandsSeparator',',' のように指定される場合、インポート関数はテキスト "1,234,000"1234000 としてインポートします。

データ型: char | string

非数値文字を数値変数から削除します。logical true または false として指定します。

例: 名前と値のペアが 'TrimNonNumeric',true のように指定される場合、インポート関数は '$500/-'500 として読み取ります。

データ型: logical

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

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

データ型: char | string

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

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

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

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

すべて折りたたむ

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

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

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

スプレッドシート データを読み取るときに、Microsoft Excel for Windows のインスタンスを起動するためのフラグ。'UseExcel' と、true または false のいずれかで構成されるコンマ区切りのペアとして指定します。

'UseExcel' パラメーターは、次の値のいずれかに設定できます。

  • true — インポート関数は、ファイルを読み取るときに Microsoft Excel のインスタンスを起動します。

  • false — インポート関数は、ファイルを読み取るときに Microsoft Excel のインスタンスを起動しません。このモードで動作しているインポート関数の機能では、サポートするファイル形式および式やマクロなどの対話型機能が異なります。

UseExcel

true

false

サポートされているファイル形式

.xls, .xlsx, .xlsm, .xltx, .xltm, .xlsb, .ods

.xls, .xlsx, .xlsm, .xltx, .xltm

式やマクロなどの対話型機能のサポート

あり

なし

Windows プラットフォームでスプレッドシート ファイルを読み取るときに Microsoft Excel のインスタンスを起動する場合は、'UseExcel' パラメーターを true に設定します。

XML ファイルのみ

すべて折りたたむ

属性接尾辞。'AttributeSuffix' と文字ベクトルまたは string スカラーのいずれかで構成されるコンマ区切りのペアとして指定します。この引数は、読み取り関数が入力 XML ファイルに含まれる属性に対応するすべての table 変数に付加する接尾辞を指定します。'AttributeSuffix' を指定しない場合、読み取り関数は既定で接尾辞 'Attribute' を入力 XML ファイルに含まれる属性に対応するすべての変数名に付加します。

例: 'AttributeSuffix','_att'

属性のインポート。'ImportAttributes' と、1 (true) または 0 (false) のいずれかで構成されるコンマ区切りのペアとして指定します。false を指定すると、読み取り関数は入力ファイル内の XML 属性を出力 table に変数としてインポートしません。

例: 'ImportAttributes',false

table 行の XML ノード名。'RowNodeName' と文字ベクトルまたは string スカラーのいずれかで構成されるコンマ区切りのペアとして指定します。この引数は、出力 table の行を区切る XML ノード名を指定します。

例: 'RowNodeName','XMLNodeName'

table 行の XPath 式。文字ベクトルまたは string スカラーとして指定します。読み取り関数は、これを使用して出力 table の個々の行を選択します。RowSelector には有効な XPath Version 1.0 の式を指定しなければなりません。

例: 'RowSelector','/RootNode/ChildNode'

table 変数の XML ノード名。'VariableNodeNames' と文字ベクトルの cell 配列または string 配列のいずれかで構成されるコンマ区切りのペアとして指定します。この引数は、読み取り関数が出力 table に変数として読み取る XML ノードを識別するために使用する XML ノード名を指定します。

例: 'VariableNodeNames',{'XMLNodeName1','XMLNodeName2'}

例: 'VariableNodeNames',"XMLNodeName"

例: 'VariableNodeNames',["XMLNodeName1","XMLNodeName2"]

table 変数の XPath 式。文字ベクトルの cell 配列または string 配列として指定します。読み取り関数は、これを使用して table 変数を選択します。VariableSelectors には有効な XPath Version 1.0 の式を指定しなければなりません。

例: 'VariableSelectors',{'/RootNode/ChildNode'}

例: 'VariableSelectors',"/RootNode/ChildNode"

例: 'VariableSelectors',["/RootNode/ChildNode1","/RootNode/ChildNode2"]

table の XML ノード名。'TableNodeName' と文字ベクトルまたは string スカラーのいずれかで構成されるコンマ区切りのペアとして指定します。この引数は、読み取り関数が table に読み取る入力構造体のノードを指定します。

例: 'TableNodeName','NodeName'

table データの XPath 式。文字ベクトルまたは string スカラーとして指定します。読み取り関数は、これを使用して出力 table のデータを選択します。TableSelector には有効な XPath Version 1.0 の式を指定しなければなりません。

例: 'TableSelector','/RootNode/ChildNode'

変数の単位の XPath。文字ベクトルまたは string スカラーとして指定します。読み取り関数は、これを使用して table 変数の単位を選択します。VariableUnitsSelector には有効な XPath Version 1.0 の式を指定しなければなりません。

例: 'VariableUnitsSelector','/RootNode/ChildNode'

変数の説明の XPath 式。文字ベクトルまたは string スカラーとして指定します。読み取り関数は、これを使用して table 変数の説明を選択します。VariableDescriptionsSelector には有効な XPath Version 1.0 の式を指定しなければなりません。

例: 'VariableDescriptionsSelector','/RootNode/ChildNode'

table の特定の行における繰り返し XML ノードの処理方法。'addcol''ignore'、または 'error' として指定します。

繰り返しノードの規則

動作

'addcol'

table の変数ヘッダーの下に繰り返しノード用の列を追加します。'RepeatedNodeRule' の値を 'addcol' と指定しても、table に繰り返しノードに対する別個の変数は作成されません。

'ignore'

繰り返しノードはスキップしてインポートします。

'error'エラー メッセージを表示し、インポート操作を中止します。

例: 'RepeatedNodeRule','ignore'

登録済みの XML 名前空間接頭辞のセット。RegisteredNamespaces と接頭辞の配列で構成されるコンマ区切りのペアとして指定します。読み取り関数は、XML ファイルの XPath 式を評価する際にこれらの接頭辞を使用します。名前空間接頭辞とそれに関連付けられた URL を N 行 2 列の string 配列として指定します。RegisteredNamespaces は、readstructStructSelectorreadtablereadtimetableVariableSelectors など、セレクターの名前と値の引数で指定された XPath 式も評価する場合に使用できます。

既定では、読み取り関数は XPath の評価に使用する名前空間接頭辞を自動的に検出して登録しますが、名前と値の引数 RegisteredNamespaces を使用して新しい名前空間接頭辞を登録することもできます。新しい名前空間接頭辞の登録は、名前空間 URL がある XML ノードについて、XML ファイルで名前空間接頭辞が宣言されていない場合などに便利です。

たとえば、名前空間接頭辞が含まれていない example.xml という名前の XML ファイルの XPath 式を評価するとします。'RegisteredNamespaces'["myprefix", "https://www.mathworks.com"] と指定して、接頭辞 myprefix を URL https://www.mathworks.com に割り当てます。

T = readtable("example.xml", "VariableSelector", "/myprefix:Data",...
 "RegisteredNamespaces", ["myprefix", "https://www.mathworks.com"])

例: 'RegisteredNamespaces',["myprefix", "https://www.mathworks.com"]

出力引数

すべて折りたたむ

出力 timetable。timetable には、説明、変数の単位、変数名、行時間などのメタデータを保存できます。詳細については、timetable プロパティの節を参照してください。

ヒント

  • インポートする XML 入力文書の要素を指定するには、XPath セレクターを使用します。たとえば、次の構造の XML ファイル myFile.xml をインポートするとします。

    <data>
        <table category="ones">
            <var>1</var>
            <var>2</var>
        </table>
        <table category="tens">
            <var>10</var>
            <var>20</var>
        </table>
    </data>
    
    次の表に、VariableSelectorsTableSelector などの XPath セレクターの名前と値の引数でサポートされる XPath 構文を示します。

    選択操作構文結果
    文書内の場所に関係なく、選択するノードに名前が一致するすべてのノードを選択する。名前の前にスラッシュを 2 つ (//) 付ける。
    data = readtable('myFile.xml', 'VariableSelectors', '//var')
    data =
    
      4×1 table
    
        var
        ___
    
         1 
         2 
        10 
        20 
    要素ノードに属する属性の値を読み取る。属性の前にアット マーク (@) を付ける。
    data = readtable('myFile.xml', 'VariableSelectors', '//table/@category')
    data =
    
      2×1 table
    
        categoryAttribute
        _________________
    
             "ones"      
             "tens"   
    一連のノードから特定のノードを選択する。選択するノードのインデックスを大かっこ ([]) で囲んで指定する。
    data = readtable('myFile.xml', 'TableSelector', '//table[1]')
    data =
    
      2×1 table
    
        var
        ___
    
         1 
         2 
    
    演算の優先順位を指定する。最初に評価する式を小かっこで囲む。
    data = readtable('myFile.xml', 'VariableSelectors', '//table/var[1]')
    data =
    
      2×1 table
    
        var
        ___
    
         1 
        10 
    data = readtable('myFile.xml', 'VariableSelectors', '(//table/var)[1]')
    data =
    
      table
    
        var
        ___
    
         1 

バージョン履歴

R2019a で導入