timetable の作成

ライブスクリプトを開く

timetable は table の一種で、各行に時刻が関連付けられています。table と同様に、timetable は、行数が同じである列方向のデータ変数を格納します。timetable は、行時間を datetime または duration 値のベクトルとして格納します。また、timetable では、1 つ以上の timetable でタイムスタンプ付きデータを整列させ、結合し、計算するための、時間に特化した関数がサポートされています。

MATLAB® では、いくつかの方法で timetable を作成し、その timetable にデータを代入できます。

関数 timetable を使用して、行時間のベクトルおよびデータ配列から timetable を作成する。
ドット表記を使用して既存の timetable に変数を追加する。
空の timetable に変数を代入する。
timetable を事前に割り当てて後でそのデータを入力する。
関数 array2timetable、table2timetable、および timeseries2timetable を使用して、変数を timetable に変換する。
関数 readtimetable を使用してファイルから timetable を読み取る。
"インポートツール" を使用してデータを table としてインポートする。次に、table2timetable を使用してそれを変換する。
Simulink® ユーザーの場合: 関数extractTimetable (Simulink)を使用して Simulink.SimulationData.Dataset オブジェクトから timetable を抽出する。

どの方法を選択するかは、データの特性とコードでの timetable の使用方法によって決まります。

入力配列からの timetable の作成

関数 timetable を使用して、行時間のベクトルおよびデータ配列から timetable を作成できます。たとえば、さまざまな時刻の気象条件を含む timetable を作成します。

まず、行時間のベクトルを作成します。このベクトルは、datetime または duration ベクトルにすることができます。次に、気温、気圧、降水量、荒天の持続時間の測定値を含むデータ配列を作成します。

MeasurementTime = datetime(["2023-12-18 08:03:05"; "2023-12-18 10:03:17"; "2023-12-18 12:03:13"]);
Temperature = [37.3; 39.1; 42.3];
Pressure = [29.4; 29.6; 30.0];
Precipitation = [0.1; 0.9; 0.0];
StormDuration = [hours(1); hours(2); NaN];

次に、timetable をデータのコンテナーとして作成します。関数 timetable は、入力引数の変数名を timetable 変数名として使用します。また、最初の入力引数は行時間のベクトルの名前を提供します。行時間のベクトルは timetable 変数ではありません。そうではなく、変数名が変数にラベルを付けるメタデータであるのと同様に、行時間は行にラベルを付けるメタデータです。したがって、結果として得られる timetable は 3 行 4 列の timetable になります。

weather = timetable(MeasurementTime,Temperature,Pressure,Precipitation,StormDuration)

weather=3×4 timetable
      MeasurementTime       Temperature    Pressure    Precipitation    StormDuration
    ____________________    ___________    ________    _____________    _____________

    18-Dec-2023 08:03:05       37.3          29.4           0.1              1 hr    
    18-Dec-2023 10:03:17       39.1          29.6           0.9              2 hr    
    18-Dec-2023 12:03:13       42.3            30             0            NaN hr

名前と値の引数 RowTimes を使用して行時間のベクトルを指定することもできます。この名前と値の引数を使用すると、timetable は行時間のベクトルの名前として Time を使用します。

weather = timetable(Temperature,Pressure,Precipitation,StormDuration,RowTimes=MeasurementTime)

weather=3×4 timetable
            Time            Temperature    Pressure    Precipitation    StormDuration
    ____________________    ___________    ________    _____________    _____________

    18-Dec-2023 08:03:05       37.3          29.4           0.1              1 hr    
    18-Dec-2023 10:03:17       39.1          29.6           0.9              2 hr    
    18-Dec-2023 12:03:13       42.3            30             0            NaN hr

ドット表記を使用した timetable への変数の追加

timetable を作成したら、"ドット表記" を使用していつでも新しい変数を追加できます。ドット表記は timetable 変数を名前 "T.varname" などで参照します。ここで、"T" は timetable で、"varname" は変数名です。

たとえば、風速の配列を weather に追加します。

w = [15; 27; 22.8];
weather.WindSpeed = w

weather=3×5 timetable
            Time            Temperature    Pressure    Precipitation    StormDuration    WindSpeed
    ____________________    ___________    ________    _____________    _____________    _________

    18-Dec-2023 08:03:05       37.3          29.4           0.1              1 hr            15   
    18-Dec-2023 10:03:17       39.1          29.6           0.9              2 hr            27   
    18-Dec-2023 12:03:13       42.3            30             0            NaN hr          22.8

空の timetable への変数の追加

timetable を作成するもう 1 つの方法として、行時間だけの空の timetable から始めて、それに変数を追加することができます。たとえば、気象条件の timetable の別のバージョンを作成します。ただし、今回はドット表記を使用して変数を追加します。

まず、行時間のベクトルのみを指定して timetable を呼び出し、空の timetable を作成します。変数がないため、結果は空の timetable になります。

weather2 = timetable(MeasurementTime)

weather2 =

  3x0 empty timetable

      MeasurementTime   
    ____________________

    18-Dec-2023 08:03:05
    18-Dec-2023 10:03:17
    18-Dec-2023 12:03:13

(引数をまったく指定せずに timetable を呼び出すこともできますが、結果は行時間もない空の timetable になります。結果として得られる 0 行 0 列の timetable は、ほとんど役に立ちません。これは、行時間を追加するのは、単に行時間のベクトルを含む空の timetable を作成するより効率が悪いからです。)

ドット表記を使用して空の timetable に変数を追加します。変数 WindSpeed への代入で示されているように、timetable 変数名はワークスペースの配列名に一致する必要はありません。

weather2.Temperature = Temperature;
weather2.Pressure = Pressure;
weather2.Precipitation = Precipitation;
weather2.StormDuration = StormDuration;
weather2.WindSpeed = w

weather2=3×5 timetable
      MeasurementTime       Temperature    Pressure    Precipitation    StormDuration    WindSpeed
    ____________________    ___________    ________    _____________    _____________    _________

    18-Dec-2023 08:03:05       37.3          29.4           0.1              1 hr            15   
    18-Dec-2023 10:03:17       39.1          29.6           0.9              2 hr            27   
    18-Dec-2023 12:03:13       42.3            30             0            NaN hr          22.8

timetable の事前割り当て

timetable に格納するデータのサイズとデータ型がわかっているが、後でデータを代入する場合は、timetable にスペースを "事前割り当て" してから、空の行に値を代入する方が効率が良いことがあります。

たとえば、さまざまな駅の時刻、気温、および風速の測定値を含む 4 行 3 列の timetable 用のスペースを事前に割り当てるには、関数 timetable を使用します。timetable に行時間で添字を作成できるように、行時間を指定する必要があります。ただし、入力データ配列を指定する代わりに、timetable 変数のサイズとデータ型を指定します。これらに名前を付けるには、名前と値の引数 VariableNames を指定します。事前割り当てにより、データ型に適した既定値が timetable 変数に代入されます。

d = datetime(2023,6,1:4)';
sz = [4 3];
varTypes = ["double","double","string"];
varNames = ["Temperature","WindSpeed","Station"];
TT = timetable(Size=sz, ...
               VariableTypes=varTypes, ...
               RowTimes=d, ...
               VariableNames=varNames)

TT=4×3 timetable
       Time        Temperature    WindSpeed     Station 
    ___________    ___________    _________    _________

    01-Jun-2023         0             0        <missing>
    02-Jun-2023         0             0        <missing>
    03-Jun-2023         0             0        <missing>
    04-Jun-2023         0             0        <missing>

一度に 1 行ずつデータを代入できます。データ値の行を cell 配列として指定します。

TT(datetime("2023-06-01"),:) = {48.2,13.33,"S1"}

TT=4×3 timetable
       Time        Temperature    WindSpeed     Station 
    ___________    ___________    _________    _________

    01-Jun-2023       48.2          13.33      "S1"     
    02-Jun-2023          0              0      <missing>
    03-Jun-2023          0              0      <missing>
    04-Jun-2023          0              0      <missing>

timetable を事前に割り当てるときにベクトルから行時間を指定する代わりに、必要な行時間を作成するためのサンプルレートまたはタイムステップを指定できます。既定では、そのような timetable の行時間は 0 秒から始まります。たとえば、名前と値の引数 TimeStep を使用して、行時間が 0.1 秒のタイムステップをもつ 3 行 2 列の timetable を事前に割り当てます。

TT = timetable(Size=[3 2], ...
               VariableTypes=["double","double"], ...
               TimeStep=seconds(0.1))

TT=3×2 timetable
     Time      Var1    Var2
    _______    ____    ____

    0 sec       0       0  
    0.1 sec     0       0  
    0.2 sec     0       0

最初の行の行時間が 0 秒ではない timetable を事前に割り当てるには、名前と値の引数 StartTime を指定します。StartTime の値には、datetime または duration のいずれかのスカラーを指定できます。StartTime を指定する場合は、SampleRate または TimeStep のいずれかを指定してサンプルレートまたはタイムステップを設定する必要もあります。たとえば、15 秒から始まる 1000 Hz のサンプルレートを使用して timetable を事前に割り当てます。

TT = timetable(Size=[3 3], ...
               VariableTypes=["uint64","double","double"], ...
               SampleRate=1000, ...
               StartTime=seconds(15))

TT=3×3 timetable
       Time       Var1    Var2    Var3
    __________    ____    ____    ____

    15 sec         0       0       0  
    15.001 sec     0       0       0  
    15.002 sec     0       0       0

変数から timetable への変換

timetable を作成するもう 1 つの方法として、配列または table を変換できます。

たとえば、関数 array2timetable を使用して配列を timetable に変換します。開始時間とサンプルレートを指定して行時間を追加します。

X = rand(5,3);
TT = array2timetable(X,StartTime=seconds(10),SampleRate=500)

TT=5×3 timetable
       Time         X1         X2         X3   
    __________    _______    _______    _______

    10 sec        0.81472    0.09754    0.15761
    10.002 sec    0.90579     0.2785    0.97059
    10.004 sec    0.12699    0.54688    0.95717
    10.006 sec    0.91338    0.95751    0.48538
    10.008 sec    0.63236    0.96489    0.80028

array2timetable を使用すると、開始時間の有無にかかわらず、サンプルレートまたはタイムステップを指定できます。あるいは、行時間のベクトルを指定できます。

同様に、関数 table2timetable を使用して table を timetable に変換できます。たとえば、table を作成し、それに行時間を追加します。

Reading1 = [98; 97.5; 97.9; 98.1; 97.9];
Reading2 = [120; 111; 119; 117; 116];
T = table(Reading1,Reading2)

T=5×2 table
    Reading1    Reading2
    ________    ________

        98        120   
      97.5        111   
      97.9        119   
      98.1        117   
      97.9        116

Time = seconds(1:1:5);
TT = table2timetable(T,RowTimes=Time)

TT=5×2 timetable
    Time     Reading1    Reading2
    _____    ________    ________

    1 sec        98        120   
    2 sec      97.5        111   
    3 sec      97.9        119   
    4 sec      98.1        117   
    5 sec      97.9        116

table2timetable では、行時間のベクトルを指定することも、開始時間の有無にかかわらずサンプルレートまたはタイムステップを指定することもできます。

ただし、table に既に日付と時刻が含まれている場合は、他の引数を指定せずに table2timetable を呼び出すことができます。この関数は、table 内の最初の datetime または duration 変数を、出力 timetable の行時間のベクトルに変換します。

たとえば、datetime 変数を含む table を作成します。次にそれを timetable に変換します。T は 3 行 4 列の table ですが、MeasurementTime が TT の行時間のベクトルになるため、TT は 3 行 3 列の timetable になります。

T = table(Temperature,Pressure,MeasurementTime,StormDuration)

T=3×4 table
    Temperature    Pressure      MeasurementTime       StormDuration
    ___________    ________    ____________________    _____________

       37.3          29.4      18-Dec-2023 08:03:05         1 hr    
       39.1          29.6      18-Dec-2023 10:03:17         2 hr    
       42.3            30      18-Dec-2023 12:03:13       NaN hr

TT = table2timetable(T)

TT=3×3 timetable
      MeasurementTime       Temperature    Pressure    StormDuration
    ____________________    ___________    ________    _____________

    18-Dec-2023 08:03:05       37.3          29.4           1 hr    
    18-Dec-2023 10:03:17       39.1          29.6           2 hr    
    18-Dec-2023 12:03:13       42.3            30         NaN hr

`timeseries` 配列から Timetable への変換

timeseries データ型は、MATLAB で時系列データを扱うためのもう 1 つのデータ型です。timetable データ型は、時系列データを扱う場合に推奨されるデータ型です。timeseries 配列を timetable に変換するには、関数 timeseries2timetable を使用します。

入力が timeseries オブジェクトの場合、出力は 1 つの変数をもつ timetable です。
入力が timeseries オブジェクトの配列の場合、出力は複数の変数をもつ timetable です。

たとえば、timeseries オブジェクトの配列を作成します。それを timetable に変換します。

ts1 = timeseries(rand(5,1),[0 10 20 30 40],Name="Series_1");
ts2 = timeseries(rand(5,1),[0 10 20 30 40],Name="Series_2");
ts3 = timeseries(rand(5,1),[0 10 20 30 40],Name="Series_3");
ts = [ts1 ts2 ts3]

  1x3 timeseries array with properties:

    Events
    Name
    UserData
    Data
    DataInfo
    Time
    TimeInfo
    Quality
    QualityInfo
    IsTimeFirst
    TreatNaNasMissing
    Length

TT = timeseries2timetable(ts)

TT=5×3 timetable
     Time     Series_1    Series_2    Series_3
    ______    ________    ________    ________

    0 sec     0.14189      0.65574    0.75774 
    10 sec    0.42176     0.035712    0.74313 
    20 sec    0.91574      0.84913    0.39223 
    30 sec    0.79221      0.93399    0.65548 
    40 sec    0.95949      0.67874    0.17119

ファイルからの timetable の読み取り

CSV (コンマ区切り値) ファイルまたは Excel® スプレッドシートなどの表形式データを timetable に読み取るには、関数 readtimetable を使用します。

たとえば、サンプルファイル outages.csv には一連の停電のデータが含まれています。outages.csv の最初の行は列名です。ファイルの残りは、停電ごとのコンマ区切りのデータ値です。最初の数行を以下に示します。

Region,OutageTime,Loss,Customers,RestorationTime,Cause
SouthWest,2002-02-01 12:18,458.9772218,1820159.482,2002-02-07 16:50,winter storm
SouthEast,2003-01-23 00:49,530.1399497,212035.3001,,winter storm
SouthEast,2003-02-07 21:15,289.4035493,142938.6282,2003-02-17 08:14,winter storm
West,2004-04-06 05:44,434.8053524,340371.0338,2004-04-06 06:10,equipment fault
MidWest,2002-03-16 06:18,186.4367788,212754.055,2002-03-18 23:23,severe storm
...

outages.csv からデータを timetable にインポートするには、readtimetable を使用します。これにより、数値、日付と時刻、および string が適切なデータ型をもつ変数に読み取られます。ここで、Loss と Customers は数値配列です。入力ファイルの OutageTime 列および RestorationTime 列は datetime 配列としてインポートされます。これは、readtimetable がこれらの列内にあるテキストの日付と時刻の形式を認識するためです。OutageTime は、値に日付と時刻が含まれている入力ファイルの最初の列であるため、readtimetable はそれを出力 timetable の行時間のベクトルに変換することに注意してください。outages.csv ファイルには 6 列ありますが、readtimetable はそれを行時間の 1 つのベクトルと 5 つの変数をもつ timetable に変換します。

outages = readtimetable("outages.csv",TextType="string")

outages=1468×5 timetable
       OutageTime         Region        Loss     Customers     RestorationTime           Cause      
    ________________    ___________    ______    __________    ________________    _________________

    2002-02-01 12:18    "SouthWest"    458.98    1.8202e+06    2002-02-07 16:50    "winter storm"   
    2003-01-23 00:49    "SouthEast"    530.14    2.1204e+05                 NaT    "winter storm"   
    2003-02-07 21:15    "SouthEast"     289.4    1.4294e+05    2003-02-17 08:14    "winter storm"   
    2004-04-06 05:44    "West"         434.81    3.4037e+05    2004-04-06 06:10    "equipment fault"
    2002-03-16 06:18    "MidWest"      186.44    2.1275e+05    2002-03-18 23:23    "severe storm"   
    2003-06-18 02:49    "West"              0             0    2003-06-18 10:54    "attack"         
    2004-06-20 14:39    "West"         231.29           NaN    2004-06-20 19:16    "equipment fault"
    2002-06-06 19:28    "West"         311.86           NaN    2002-06-07 00:51    "equipment fault"
    2003-07-16 16:23    "NorthEast"    239.93         49434    2003-07-17 01:12    "fire"           
    2004-09-27 11:09    "MidWest"      286.72         66104    2004-09-27 16:37    "equipment fault"
    2004-09-05 17:48    "SouthEast"    73.387         36073    2004-09-05 20:46    "equipment fault"
    2004-05-21 21:45    "West"         159.99           NaN    2004-05-22 04:23    "equipment fault"
    2002-09-01 18:22    "SouthEast"    95.917         36759    2002-09-01 19:12    "severe storm"   
    2003-09-27 07:32    "SouthEast"       NaN    3.5517e+05    2003-10-04 07:02    "severe storm"   
    2003-11-12 06:12    "West"         254.09    9.2429e+05    2003-11-17 02:04    "winter storm"   
    2004-09-18 05:54    "NorthEast"         0             0                 NaT    "equipment fault"
      ⋮

インポートツールの使用

最後に、"インポートツール" を使用して、スプレッドシート、区切りテキストファイル、および固定幅のテキストファイルのデータを対話的にプレビューしたり、インポートしたりできます。ただし、"インポートツール" はデータを table としてインポートできますが、データを timetable として直接インポートすることはできません。

"インポートツール" を使用する場合は、次の手順に従って timetable を作成します。