matlab.tall.blockMovingWindow

移動ウィンドウ関数およびブロック削減をパディングされたデータ ブロックに適用

構文

tA = matlab.tall.blockMovingWindow(windowfcn,blockfcn,window,tX)

[tA,tB,...] = matlab.tall.blockMovingWindow(windowfcn,blockfcn,window,tX,tY,...)

[___] = matlab.tall.blockMovingWindow(___,Name,Value)

説明

tA = matlab.tall.blockMovingWindow(windowfcn,blockfcn,window,tX) は、完全なデータ ウィンドウに対して blockfcn を適用し、エッジ付近の不完全なデータ ウィンドウに対して windowfcn を適用します。window は、スライディング ウィンドウのサイズを指定します。結果には、これらのデータ ウィンドウに対して blockfcn および windowfcn が適用されたものの垂直結合が含まれます。

[tA,tB,...] = matlab.tall.blockMovingWindow(windowfcn,blockfcn,window,tX,tY,...) (ここで、windowfcn と blockfcn は複数の出力を返す関数ハンドル) は、それぞれが windowfcn と blockfcn の出力引数のいずれかに対応する配列 tA, tB, ... を返します。windowfcn および blockfcn の入力は、引数 tX, tY, ... のデータです。この構文には以下の要件があります。

• windowfcn および blockfcn は matlab.tall.blockMovingWindow から要求された出力と同じ数の出力を返さなければならない。

• windowfcn および blockfcn の各出力は、最初のデータ入力 tX と同じ型でなければならない。

• すべての出力 tA,tB,... は同じ高さでなければならない。

[___] = matlab.tall.blockMovingWindow(___,Name,Value) は、前述の任意の構文を使用して、1 つ以上の名前と値のペアの引数による追加オプションを指定します。たとえば、ウィンドウ間のステップ サイズを調整するには、'Stride' およびスカラーを指定できます。あるいは、ウィンドウの要素数が足りない場合の端点の処理を変更するには、'EndPoints' および有効なオプション ('shrink'、'discard'、または数値のパディング値) を指定できます。

例

tall 配列を使用した移動ウィンドウの計算

matlab.tall.blockMovingWindow を使用して、航空機の到着遅延および出発遅延の移動平均値を計算します。

airlinesmall.csv データ セットのデータストアを作成し、それを tall 配列に変換します。このデータには米国のフライトの到着時刻と出発時刻に関する情報が含まれています。フライト遅延のベクトルである、変数 ArrDelay および DepDelay を抽出し、各遅延が個々の列に含まれる tall 配列を作成します。

varnames = {'ArrDelay', 'DepDelay'};
ds = tabularTextDatastore('airlinesmall.csv', 'TreatAsMissing', 'NA', ...
    'SelectedVariableNames', varnames);
tt = tall(ds);
tX = [tt.ArrDelay tt.DepDelay]

tX =

  Mx2 tall double matrix

     8    12
     8     1
    21    20
    13    12
     4    -1
    59    63
     3    -2
    11    -1
    :     :
    :     :

matlab.tall.blockMovingWindow を使用して、ウィンドウ サイズが 10 の最初の次元のデータの移動平均値を計算します。windowfcn は単一のデータ ウィンドウに対してのみ適用されるため、関数 mean を使用して、1 行の行列にデータ ウィンドウを削減できます。blockfcn はデータ ブロック全体に適用されるため、関数 movmean を使用して、ブロック内のそれぞれの完全なデータ ウィンドウの平均値を計算します。

windowfcn = @(info,x) mean(x,1,'omitnan');
blockfcn = @(info,x) movmean(x,info.Window,1,'omitnan','EndPoints','discard');
A = matlab.tall.blockMovingWindow(windowfcn, blockfcn, 10, tX)

A =

  MxNx... tall double array

    ?    ?    ?    ...
    ?    ?    ?    ...
    ?    ?    ?    ...
    :    :    :
    :    :    :

結果の一部をメモリに収集します。

gather(A(1:10,:))

Evaluating tall expression using the Local MATLAB Session:
- Pass 1 of 2: Completed in 0.87 sec
- Pass 2 of 2: Completed in 5.4 sec
Evaluation completed in 6.9 sec

ans = 10×2

   10.8000    8.8000
   18.8333   17.8333
   16.5714   15.0000
   15.8750   13.0000
   14.4444   11.8889
   13.2000   10.8000
   14.0000   11.1000
   13.5000   11.9000
   15.3000   11.4000
   19.7000   13.4000

table の移動統計

table の変数の移動統計を計算します。

outages.csv データ セットを tall table として読み込みます。データには停電に関する情報が含まれています。

T = tall(readtable('outages.csv'))

T =

  1,468x6 tall table

       Region             OutageTime          Loss     Customers       RestorationTime              Cause       
    _____________    ____________________    ______    __________    ____________________    ___________________

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

matlab.tall.blockMovingWindow を使用して、tall table のブロックに対して移動ウィンドウ関数を適用します。以下のオプションを指定します。

• 完全なデータ ブロックに対して実行されるブロック関数として blkstats (この関数は、ローカル関数として例の最後に含まれています)。

• ウィンドウ サイズを 50、ストライドを 5 とする。

• 不完全なデータ ウィンドウを無視するために、EndPoints を 'discard' とする。この値を使用すると、完全なデータ ウィンドウに対してのみ実行されるため、windowfcn の入力に対して空の [] を指定できます。

• 入力 table には 6 つの変数があるが、2 つの出力は倍精度のベクトルとする。スカラーの double を OutputsLike の値として指定することで、関数において、データ型およびサイズを変更できるようになります。

[A, B] = matlab.tall.blockMovingWindow([], @blkstats, 50, T, 'Stride', 5, ...
    'EndPoints', 'discard', 'OutputsLike', {1, 1});

結果の数行をプレビューします。

[A,B] = gather(head(A),head(B))

Evaluating tall expression using the Local MATLAB Session:
- Pass 1 of 2: Completed in 0.6 sec
- Pass 2 of 2: Completed in 0.85 sec
Evaluation completed in 2.2 sec

A = 8×1

  254.0861
  254.0861
  340.3499
  452.0191
  464.8524
  471.9737
  464.8524
  464.8524

B = 8×1
105 ×

    1.3447
    1.0779
    1.4227
    1.4509
    1.2888
    1.2888
    1.2308
    1.3722

関数 blkstats は、指定されたウィンドウ サイズを使用して、最初の次元の Loss および Customers table 変数の移動中央値を計算します。関数は出力サイズを削減するために Stride 値を適用し、結果として 2 つのベクトルを返します。

function [out1, out2] = blkstats(info, t)
    a = movmedian([t.Loss t.Customers], info.Window, 1, 'omitnan', 'EndPoints', 'discard');
    a = a(1:info.Stride:end, :);
    out1 = a(:,1);
    out2 = a(:,2);
end

入力引数

windowfcn — 不完全なデータ ウィンドウに適用される関数

関数ハンドル | 無名関数 | []

不完全なデータ ウィンドウに適用される関数。関数ハンドル、無名関数、または [] として指定します。windowfcn は、tall 次元のデータに沿って計算が移動する間、不完全なウィンドウごとに 1 度呼び出されます。matlab.tall.blockMovingWindow は、'EndPoints' が既定値 'shrink' である場合にのみ windowfcn を適用します。'EndPoints' に異なる値を指定した場合は、windowfcn を [] に設定します。

windowfcn の各出力は最初のデータ入力 tX と同じ型でなければなりません。'OutputsLike' オプションを使用してさまざまなデータ型の出力を返すことができます。

windowfcn の一般的な関数シグネチャは、次のとおりです。

[a, b, c, ...] = windowfcn(info, x, y, ...)

入力 info は、matlab.tall.blockMovingWindow によって提供される構造体で、以下のフィールドを含みます。

• Stride — ウィンドウ間の指定ステップ サイズ (既定の設定: 1)。この値は名前と値のペア 'Stride' で設定します。

• Window — 指定のウィンドウ サイズ。この値は window 入力引数で設定します。

windowfcn は以下の要件を満たさなければなりません。

1. 入力引数 — 入力 [x, y, z, ...] は、メモリに収まるデータのブロックです。ブロックは、tall 配列の入力 [tX, tY, tZ, ...] それぞれからデータを抽出することによって生成されます。入力 [x, y, z, ...] は次の特性を満たします。

   • すべての入力 [x, y, z, ...] は最初の次元が同じサイズとなる。

   • [x, y, z, ...] のデータ ブロックは、tall 配列の tall 次元が 1 ではないと仮定した場合、tall 次元の同じインデックスから得られる。たとえば、tX と tY の tall 次元が 1 ではない場合、ブロックの最初のセットは x = tX(1:20000,:) および y = tY(1:20000,:) になる可能性があります。

   • [tX, tY, tZ, ...] のいずれかの最初の次元がサイズ 1 である場合、対応するブロック [x, y, z, ...] は、その tall 配列内のすべてのデータで構成される。

   • windowfcn を適用した結果、入力データはスカラーまたは高さ 1 の配列のスライスに削減されなければならない。

     入力が行列、N 次元配列、table、または timetable である場合、windowfcn を適用することで、その各列または各変数における入力データが削減されなければなりません。

2. 出力引数 — 出力 [a, b, c, ...] はメモリに収まるブロックで、それぞれの出力 [tA, tB, tC, ...] に送信されます。出力 [a, b, c, ...] は以下の特性を満たします。

   • 出力 [a, b, c, ...] はすべて、最初の次元が同じサイズでなければならない。

   • 出力 [a, b, c, ...] はすべて、windowfcn の以前の呼び出しの結果とそれぞれ垂直方向に連結される。

   • 出力 [a, b, c, ...] はすべて、それぞれの出力先で、出力配列の最初の次元にある同じインデックスに送信される。

3. 関数ルール — windowfcn は以下の関数ルールを満たしていなければなりません。

   • F([inputs1; inputs2]) == [F(inputs1); F(inputs2)]:入力の連結に関数を適用することは、入力に関数を個別に適用してから結果を連結する場合と同じでなければならない。

例: A = matlab.tall.blockMovingWindow(@windowfcn, @blockfcn, 10, tX)

例: A = matlab.tall.blockMovingWindow([], @blockfcn, 10, tX, 'EndPoints', 'discard')

データ型: function_handle

blockfcn — データ ブロックに適用される関数

関数ハンドル | 無名関数

データ ブロックに適用される関数。関数ハンドルまたは無名関数として指定します。blockfcn は、完全なデータ ウィンドウを含むデータ ブロックに適用されます。したがって、blockfcn は、データ ブロック全体に対してベクトル化された方法で実行され、指定されたウィンドウ サイズおよびストライドに対して適切なサイズの出力を返さなければなりません。

blockfcn の各出力は最初のデータ入力 tX と同じ型でなければなりません。'OutputsLike' オプションを使用してさまざまなデータ型の出力を返すことができます。

matlab.tall.blockMovingWindow は、ブロックに完全なウィンドウのみが含まれる場合は常にデータ ブロックに対して blockfcn を適用します。

• 'EndPoints' が 'shrink' に設定されている場合、中央のブロック (既定の動作)。この場合、両端の不完全なデータ ウィンドウに対しては windowfcn が実行されます。

• 'EndPoints' が 'discard' またはパディング値に設定されている場合、すべてのブロック。

blockfcn の一般的な関数シグネチャは、次のとおりです。

[a, b, c, ...] = blockfcn(info, bX, bY, bZ, ...)

入力 info は、matlab.tall.blockMovingWindow によって提供される構造体で、以下のフィールドを含みます。

• Stride — ウィンドウ間の指定ステップ サイズ (既定の設定: 1)。この値は名前と値のペア 'Stride' で設定します。

• Window — 指定のウィンドウ サイズ。この値は window 入力引数で設定します。

matlab.tall.blockMovingWindow が blockfcn に提供するデータ ブロック bX, bY, bZ, ... には次の特性があります。

• ブロックにはフルサイズのウィンドウのみが含まれる。blockfcn は不完全なデータ ウィンドウに対する動作を定義する必要はありません。

• 最初のデータ ウィンドウは、ブロックの最初の要素から開始する。最後のウィンドウの最後の要素は、ブロックの最後の要素です。

blockfcn は以下の要件を満たさなければなりません。

1. 入力引数 — 入力 [bX, bY, bZ, ...] は、メモリに収まるデータのブロックです。ブロックは、tall 配列の入力 [tX, tY, tZ, ...] それぞれからデータを抽出することによって生成されます。入力 [bX, bY, bZ, ...] は次の特性を満たします。

   • 入力 [bX, bY, bZ, ...] はすべて、任意の可能な拡張後の最初の次元が同じサイズをもつ。

   • [bX, bY, bZ, ...] のデータ ブロックは、tall 配列の tall 次元が 1 ではないと仮定した場合、tall 次元の同じインデックスから得られる。たとえば、tX と tY の tall 次元が 1 ではない場合、ブロックの最初のセットは bX = tX(1:20000,:) および bY = tY(1:20000,:) になる可能性があります。

   • データ入力 [tX, tY, tZ, ...] のいずれかの最初の次元がサイズ 1 である場合、対応するブロック [bX, bY, bZ, ...] は、その tall 配列内のすべてのデータで構成される。

   • blockfcn を適用した結果、入力データがブロック内のウィンドウの数と等しい高さになるよう削減されなければならない。ブロック内のウィンドウの数を特定するには info.Window と info.Stride を使用できます。

     入力が行列、N 次元配列、table、または timetable である場合、blockfcn を適用した結果、入力データはその各列または各変数において削減されなければなりません。

2. 出力引数 — 出力 [a, b, c, ...] はメモリに収まるブロックで、それぞれの出力 [tA, tB, tC, ...] に送信されます。出力 [a, b, c, ...] は以下の特性を満たします。

   • 出力 [a, b, c, ...] はすべて、最初の次元が同じサイズでなければならない。

   • 出力 [a, b, c, ...] はすべて、blockfcn の以前の呼び出しの結果とそれぞれ垂直方向に連結される。

   • 出力 [a, b, c, ...] はすべて、それぞれの出力先で、出力配列の最初の次元にある同じインデックスに送信される。

3. 関数ルール — blockfcn は以下の関数ルールを満たしていなければなりません。

   • F([inputs1; inputs2]) == [F(inputs1); F(inputs2)]:入力の連結に関数を適用することは、入力に関数を個別に適用してから結果を連結する場合と同じでなければならない。

例: A = matlab.tall.blockMovingWindow(@windowfcn, @blockfcn, 10, tX)

例: A = matlab.tall.blockMovingWindow([], @blockfcn, 10, tX, 'EndPoints', 'discard')

データ型: function_handle

window — ウィンドウ サイズ

正の整数スカラー | 2 要素の行ベクトル

ウィンドウ サイズ。正の整数スカラーまたは 2 要素の行ベクトル [NB NF] として指定します。

• window がスカラーの場合、次のようになります。

  • ウィンドウ サイズが奇数である場合、各ウィンドウはデータ内の対応する要素を中心にして配置されます。

    

  • ウィンドウ サイズが偶数である場合、各ウィンドウは現在の要素および直前の要素を中心にして配置されます。

    

• window がベクトル [NB NF] である場合、ウィンドウには入力の直前の NB の要素、現在の要素、および次の NF の要素が含まれます。

  

既定では、ウィンドウを埋めるのに十分な数の要素がない場合、ウィンドウ サイズは自動的に端点で打ち切られます。ウィンドウがこのように打ち切られる場合、関数はウィンドウを埋めている要素に対してのみ演算を実行します。EndPoints の名前と値のペアを使用してこの動作を変更できます。

データ型: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

tX, tY — 入力配列 (個別の引数として)

スカラー | ベクトル | 行列 | 多次元配列 | table | timetable

入力配列。スカラー、ベクトル、行列、多次元配列、table、または timetable の個別の引数として指定します。入力配列は、tall 配列またはインメモリ配列にできます。入力配列は変換関数 fcn の入力として使用されます。各入力配列 tX,tY,... は同じ高さでなければなりません。

名前と値の引数

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

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

例: tA = matlab.tall.blockMovingWindow(@windowfcn, blockfcn, window, tX, 'Stride', 2)

Stride — ウィンドウ間のステップ サイズ

1 (既定値) | 正の整数スカラー

ウィンドウ間のステップ サイズ。'Stride' と正の整数スカラーで構成されるコンマ区切りのペアとして指定します。データ ウィンドウに対して fcn の演算を実行した後、次のウィンドウの演算を実行する前に、'Stride' 値の分だけ計算が進められます。'Stride' の値を既定値の 1 から増やすと、要素を 1 つおき、3 つおき、などのように取り出して出力サイズを削減することと同じになります。

既定では、'Stride' の値は 1 であるため、各ウィンドウは入力の各要素を中心にして配置されます。たとえば、ベクトル [1 2 3 4 5 6]' に対して実行したウィンドウ サイズが 3 の移動合計の計算を次に示します。

'Stride' の値が 2 の場合、計算が変わり、各ウィンドウは、入力の 2 つ目ごとの要素 (1、3、5) を中心として配置されます。この場合、移動合計は 6 個ではなく 3 個の部分和を返します。

データ型: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

EndPoints — 先頭および末尾のウィンドウを処理する方法

'shrink' (既定値) | 'discard' | パディング値

先頭および末尾のウィンドウを処理する方法。'EndPoints' と次の表のいずれかの値で構成されるコンマ区切りのペアとして指定します。

ウィンドウ計算の開始時および終了時において、演算される要素のウィンドウは不完全となります。'EndPoints' オプションは、これらの不完全なウィンドウの処理方法を指定します。

'EndPoints' 値	説明	例: 移動合計値
'shrink'	入力の端点付近のウィンドウのサイズを縮小し、既存の要素のみを含めます。
'discard'	既存の要素とウィンドウが完全にオーバーラップしない場合、結果を出力しません。
数値または logical のパディング値	存在しない要素を指定した数値または論理値に置き換えます。 パディング値は tX と同じ型でなければならない。 最初の次元のパディング値のサイズは 1 と等しく、他の次元のサイズは tX と一致しなければならない。

データ型: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | logical | char | string

OutputsLike — 出力配列のプロトタイプ

cell 配列

出力配列のプロトタイプ。'OutputsLike' およびプロトタイプ配列を含む cell 配列で構成されるコンマ区切りのペアとして指定します。'OutputsLike' を指定する場合、matlab.tall.blockMovingWindow で返される出力配列 tA,tB,... は、指定したプロトタイプ配列 {PA,PB,...} と同じデータ型と属性をもちます。出力配列のデータ型が入力配列のデータ型と異なる場合は常に 'OutputsLike' を指定しなければなりません。'OutputsLike' を指定した場合は、各出力のプロトタイプ配列を指定しなければなりません。

例: tA = matlab.tall.blockMovingWindow(..., tX, 'OutputsLike', {int8(1)}); の場合、tX は倍精度 tall 配列であり、tA を double ではなく int8 として返します。

データ型: cell

出力引数

tA, tB — 出力配列

スカラー | ベクトル | 行列 | 多次元配列

出力配列。スカラー、ベクトル、行列、または多次元配列として返されます。matlab.tall.blockMovingWindow へのいずれかの入力が tall の場合、すべての出力引数も tall となります。それ以外の場合、すべての出力引数はインメモリ配列になります。

• 出力配列のサイズとデータ型は指定したウィンドウ関数 windowfcn と blockfcn によって異なります。

• 出力配列 tA,tB,... の高さはすべて同じになります。高さは 'Stride' および 'EndPoints' の値によって異なります。既定では、出力配列は入力配列と同じサイズです。

• 一般的に、出力 tA,tB,... はすべて、最初のデータ入力 tX と同じデータ型をもたなければなりません。ただし、'OutputsLike' を指定して異なるデータ型を返すことができます。入力配列 tX, tY, ... が空の場合、または 'EndPoints' が 'discard' で、フルサイズのウィンドウを埋める十分な要素がない場合、matlab.tall.blockMovingWindow は空の出力を返します。空の出力のサイズは、入力配列 tX、または 'OutputsLike' に指定されるプロトタイプ配列 (指定されている場合) のサイズに基づきます。

ヒント

• 単純なスライディング ウィンドウの計算では matlab.tall.movingWindow を使用します。matlab.tall.blockMovingWindow は、tall 配列に対して、より柔軟にスライディング ウィンドウの計算を実行するように設計された高度な API です。したがって、関数は、完全なウィンドウを多数含むデータ ブロックを正確に処理しなければならないため、使用が複雑になります。ただし、適切にベクトル化された計算では、必要な関数呼び出しの数を減らし、パフォーマンスを向上できます。

バージョン履歴

R2019a で導入

参考

tall | matlab.tall.movingWindow

トピック

• カスタム tall 配列アルゴリズムの開発