movvar

移動分散値

構文

M = movvar(A,k)

M = movvar(A,[kb kf])

M = movvar(___,w)

M = movvar(___,w,dim)

M = movvar(___,nanflag)

M = movvar(___,Name,Value)

説明

M = movvar(A,k) は局所 k 点における分散値を返します。各分散値は、長さ k のスライディング ウィンドウにわたる A の隣接要素から計算されます。k が奇数である場合、ウィンドウは現在位置にある要素を中心にして配置されます。k が偶数である場合、ウィンドウは現在の要素および直前の要素を中心にして配置されます。ウィンドウを埋めるのに十分な数の要素がない場合、ウィンドウ サイズは自動的に端点で打ち切られます。ウィンドウが打ち切られた場合、分散値はウィンドウを埋めている要素のみから取得されます。M は A と同じサイズです。

• A がベクトルである場合、movvar はベクトル A の長さに沿って演算します。

• A が多次元配列の場合、movvar は、サイズが 1 に等しくない A の最初の次元に沿って演算します。

• A が table または timetable の場合、movvar は A の変数に沿って演算します。 (R2025a 以降)

M = movvar(A,[kb kf]) は長さが kb+kf+1 のウィンドウにおける分散値を計算します。このウィンドウには現在位置の要素、kb 個前までの要素、kf 個後までの要素が含まれます。

M = movvar(___,w) は、前述の任意の構文について正規化係数を指定します。w = 0 (既定値) の場合、M はウィンドウの長さが k のときに k-1 で正規化されます。w = 1 の場合、M は k で正規化されます。

M = movvar(___,w,dim) は、前述の任意の構文について、演算の対象とする A の次元を指定します。dim を指定する場合は、常に前述の構文の重み w を指定します。たとえば、A が行列である場合、movvar(A,k,0,2) は A の列に沿って動作し、各行の k 個の要素の移動分散値を計算します。正規化係数は既定値 k-1 です。

M = movvar(___,nanflag) は、A の NaN 値を含めるか省略するかを指定します。たとえば、movvar(A,k,"omitnan") は各分散値の計算時に NaN 値を無視します。既定では、movvar は NaN 値を含めます。

M = movvar(___,Name,Value) は、名前と値のペアの引数を 1 つ以上使用して分散値に追加のパラメーターを指定します。たとえば、x が時間値のベクトルである場合、movvar(A,k,"SamplePoints",x) は x の時間を基準とする移動分散値を計算します。

例

ベクトルの中心移動分散値

行ベクトルの 3 点の中心移動分散値を計算します。端点でウィンドウ内の要素数が 3 より少ない場合、使用可能な要素の分散値を取得します。

A = [4 8 6 -1 -2 -3 -1 3 4 5];
M = movvar(A,3)

M = 1×10

    8.0000    4.0000   22.3333   19.0000    1.0000    1.0000    9.3333    7.0000    1.0000    0.5000

ベクトルの末尾移動分散値

行ベクトルの 3 点の末尾移動分散値を計算します。端点でウィンドウ内の要素数が 3 より少ない場合、使用可能な要素の分散値を取得します。

A = [4 8 6 -1 -2 -3 -1 3 4 5];
M = movvar(A,[2 0])

M = 1×10

         0    8.0000    4.0000   22.3333   19.0000    1.0000    1.0000    9.3333    7.0000    1.0000

移動分散値の正規化を指定

行ベクトルの 3 点の中心移動分散値を計算し、個々の分散値をウィンドウ内の要素数で正規化します。

A = [4 8 6 -1 -2 -3 -1 3 4 5];
M = movvar(A,3,1)

M = 1×10

    4.0000    2.6667   14.8889   12.6667    0.6667    0.6667    6.2222    4.6667    0.6667    0.2500

行列の移動分散値

行列の各行に対して 3 点の中心移動分散値を計算します。ウィンドウは最初の行で始まり、行の終わりまで横方向にスライドし、それから 2 行目に移動して同様に繰り返します。次元引数は 2 であるため、ウィンドウは A の列を横断する方向にスライドします。次元を指定する場合は常に正規化係数を指定します。

A = [4 8 6; -1 -2 -3; -1 3 4];
M = movvar(A,3,0,2)

M = 3×3

    8.0000    4.0000    2.0000
    0.5000    1.0000    0.5000
    8.0000    7.0000    0.5000

欠損値を除外した移動分散値

NaN 値が含まれた行ベクトルを作成します。

A = [4 8 NaN -1 -2 -3 NaN 3 4 5];

NaN 値を除外して、ベクトルの 3 点の中心移動分散値を計算します。NaN 値が含まれているウィンドウでは、movvar は NaN 以外の要素で計算します。

M = movvar(A,3,"omitnan")

M = 1×10

    8.0000    8.0000   40.5000    0.5000    1.0000    0.5000   18.0000    0.5000    1.0000    0.5000

移動分散値のサンプル点

時間ベクトル t に従って、A のデータの 3 時間中心移動分散値を計算します。

A = [4 8 6 -1 -2 -3];
k = hours(3);
t = datetime(2016,1,1,0,0,0) + hours(0:5)

t = 1×6 datetime
   01-Jan-2016 00:00:00   01-Jan-2016 01:00:00   01-Jan-2016 02:00:00   01-Jan-2016 03:00:00   01-Jan-2016 04:00:00   01-Jan-2016 05:00:00

M = movvar(A,k,"SamplePoints",t)

M = 1×6

    8.0000    4.0000   22.3333   19.0000    1.0000    0.5000

フルウィンドウの分散値のみを返す

行ベクトルの 3 点の中心移動分散値を計算しますが、使用する要素が 3 点より少ない計算を出力から破棄します。言い換えれば、3 要素をすべて含むウィンドウから計算された分散値のみを返し、端点での計算を破棄します。

A = [4 8 6 -1 -2 -3 -1 3 4 5];
M = movvar(A,3,"Endpoints","discard")

M = 1×8

    4.0000   22.3333   19.0000    1.0000    1.0000    9.3333    7.0000    1.0000

table の移動分散値

魔方陣の列から table を作成します。

A = magic(3);
T = array2table(A)

T=3×3 table
    A1    A2    A3
    __    __    __

    8     1     6 
    3     5     7 
    4     9     2 

movvar を使用して table 変数の移動分散値を計算します。

M = movvar(T,3)

M=3×3 table
     A1     A2     A3 
    ____    __    ____

    12.5     8     0.5
       7    16       7
     0.5     8    12.5

指定した変数についてのみ移動分散値を計算するには、名前と値の引数 DataVariables を指定します。

M2 = movvar(T,3,DataVariables=["A2" "A3"])

M2=3×3 table
    A1    A2     A3 
    __    __    ____

    8      8     0.5
    3     16       7
    4      8    12.5

値を置き換える代わりに table に移動分散値を追加するには、ReplaceValues を false として指定します。

M3 = movvar(T,3,ReplaceValues=false)

M3=3×6 table
    A1    A2    A3    A1_movvar    A2_movvar    A3_movvar
    __    __    __    _________    _________    _________

    8     1     6       12.5           8           0.5   
    3     5     7          7          16             7   
    4     9     2        0.5           8          12.5   

入力引数

A — 入力データ

ベクトル | 行列 | 多次元配列 | table | timetable

入力データ。ベクトル、行列、多次元配列、table または timetable として指定します。

データ型: single | double | logical | table | timetable

k — ウィンドウの長さ

数値または duration スカラー

ウィンドウの長さ。数値または duration スカラーとして指定します。k が正の整数値スカラーである場合、中心分散値には現在位置の要素とその周囲の要素が含まれます。

たとえば、movvar(A,3) は局所 3 点における分散値の配列を計算します。

[kb kf] — 方向指定ウィンドウの長さ

2 つの要素を含む数値または duration 行ベクトル

方向指定ウィンドウの長さ。2 つの要素を含む数値または duration 行ベクトルとして指定します。kb と kf が正の整数値スカラーの場合、計算は kb+kf+1 個の要素に対して行われます。この計算には、現在位置にある要素、その前にある kb 個の要素、その後にある kf 個の要素が含まれます。

たとえば、movvar(A,[2 1]) は局所 4 点における分散値の配列を計算します。

w — 重み

0 (既定値) | 1

重み。次のいずれかの値に指定します。

• 0 — k-1 で正規化されます (k はウィンドウの長さ)。k=1 の場合、重みは k です。

• 1 — k で正規化されます。

データ型: single | double

dim — 演算の対象の次元

正の整数スカラー

演算の対象の次元。正の整数のスカラーとして指定します。次元を指定しない場合、既定値はサイズが 1 でない最初の配列次元です。

次元 dim は movvar が沿って動作する次元、つまり指定されたウィンドウがスライドする方向を示します。

m 行 n 列の入力行列 A を考えます。

• movvar(A,k,0,1) は、A の各列について k 要素の移動分散値を計算し、m 行 n 列の行列を返します。

  

• movvar(A,k,0,2) は、A の各行について k 要素の移動分散値を計算し、m 行 n 列の行列を返します。

  

A が table または timetable の場合、dim を指定することはできません。movvar 関数は、常に table および timetable の変数に沿って演算を行います。 (R2025a 以降)

nanflag — 欠損値の条件

"includemissing" (既定値) | "includenan" | "omitmissing" | "omitnan"

欠損値の条件。次の値のいずれかとして指定します。

• "includemissing" または "includenan" — 各分散値の計算時に A の NaN 値を含めます。ウィンドウ内のいずれかの要素が NaN の場合、M の対応する要素は NaN です。"includemissing" と "includenan" の動作は同じです。

• "omitmissing" または "omitnan" — A の NaN 値を無視し、点の数を減らして各分散値を計算します。ウィンドウ内のすべての要素が NaN の場合、M の対応する要素は NaN です。"omitmissing" と "omitnan" の動作は同じです。

名前と値の引数

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

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

例: M = movvar(A,k,"Endpoints","fill")

Endpoints — 端点付近のウィンドウの処理方法

"shrink" (既定値) | "discard" | "fill" | 数値または logical スカラー

端点付近のウィンドウの処理方法。次のオプションのいずれかとして指定します。

値	説明
"shrink"	入力の端点付近のウィンドウのサイズを縮小し、既存の要素のみを含めます。
"discard"	既存の要素とウィンドウが完全にオーバーラップしない場合、分散値を出力しません。 A が table または timetable の場合、Endpoints を "discard" として指定することはできません。
"fill"	存在しない要素を NaN に置き換えます。
数値または logical スカラー	存在しない要素を指定した数値または論理値に置き換えます。

SamplePoints — 分散値を計算するためのサンプル点

ベクトル

分散値を計算するためのサンプル点。ベクトルとして指定します。サンプル点は A のデータの位置を表します。サンプル点は等間隔でサンプリングされている必要はありません。既定では、サンプル点ベクトルは [1 2 3 ... ] です。

移動ウィンドウはサンプル点を基準として定義されます。サンプル点は並べ替えられていなければならず、また一意の要素を含んでいなければなりません。たとえば、t が入力データに対応する時間のベクトルである場合、movvar(rand(1,10),3,"SamplePoints",t) には t(i)-1.5 から t(i)+1.5 までの時間間隔を表すウィンドウがあります。

サンプル点ベクトルのデータ型が datetime または duration である場合、移動ウィンドウの長さの型は duration でなければなりません。

サンプル点の間隔が不均一で、Endpoints を指定する場合、その値は "shrink" でなければなりません。

DataVariables — 演算の対象とする table または timetable 変数

table または timetable の変数の名前 | スカラー | ベクトル | cell 配列 | パターン | 関数ハンドル | table vartype 添字

R2025a 以降

演算の対象とする table または timetable 変数。次の表のオプションのいずれかとして指定します。

• DataVariables を指定しない場合、movvar はすべての変数について演算を行います。この動作は既定の動作です。

• DataVariables を指定した場合、movvar は指定された変数のみについて演算を行います。DataVariables で指定されていないその他の変数は、変更されずに出力に渡されます。

インデックス方式	指定する値	例
変数名	string スカラーまたは文字ベクトル string 配列または文字ベクトルの cell 配列 pattern オブジェクト	"A" または 'A' — A という名前の変数 ["A" "B"] または {'A','B'} — A および B という名前の 2 つの変数 "Var"+digitsPattern(1) — "Var" の後に数字 1 桁が続く名前の変数
変数インデックス	table 内の変数の位置を参照するインデックス番号 数値のベクトル logical ベクトル。通常、このベクトルの長さは変数の数と同じですが、末尾の 0 (false) 値は省略できます。	3 — table の 3 番目の変数 [2 3] — table の 2 番目と 3 番目の変数 [false false true] — 3 番目の変数
関数ハンドル	入力として table 変数を取り、logical スカラーを返す関数ハンドル	@isnumeric — 数値を含んでいるすべての変数
変数の型	指定した型の変数を選択する vartype 添字	vartype("numeric") — 数値を含んでいるすべての変数

ReplaceValues — 値置換インジケーター

true または 1 (既定値) | false または 0

R2025a 以降

値置換インジケーター。A が table または timetable の場合に、次の値のいずれかとして指定します。

• true または 1 — 出力 table または出力 timetable で、入力 table または入力 timetable の変数を movvar からの出力値を含む変数に置き換えます。

• false または 0 — 出力 table または出力 timetable に movvar からの出力値を含む変数を追加します。

入力データがベクトル、行列、または多次元配列の場合、ReplaceValues はサポートされません。

詳細

分散

N 個のスカラー観測値からなる有限長ベクトル A の分散は、次のように定義されます。

$$V=\frac{1}{N-1}{\displaystyle \sum _{i=1}^N|A_i-\mu {|}^2}$$

ここで、μ は A の平均です。

$$\mu =\frac{1}{N}{\displaystyle \sum _{i=1}^N{A}_i}.$$

一部の分散の定義では、正規化係数として N-1 ではなく N を使用しています。w を 1 に設定することで N の係数を指定できます。いずれの場合でも、平均には通常の正規化係数 N を使用します。

拡張機能

tall 配列

メモリの許容量を超えるような多数の行を含む配列を計算します。

この関数は tall 配列を制限付きでサポートしています。

• • 名前と値の引数 SamplePoints、DataVariables、および ReplaceValues はサポートされません。

  • table および timetable の入力はサポートされていません。

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

C/C++ コード生成

MATLAB® Coder™ を使用して C および C++ コードを生成します。

使用上の注意および制限:

• コード生成では、この関数のスパース行列入力はサポートされません。

• 名前と値の引数 DataVariables および ReplaceValues はサポートされません。

• table および timetable の入力はサポートされていません。

スレッドベースの環境

MATLAB® の backgroundPool を使用してバックグラウンドでコードを実行するか、Parallel Computing Toolbox™ の ThreadPool を使用してコードを高速化します。

この関数はスレッドベースの環境を完全にサポートしています。詳細については、スレッドベースの環境での MATLAB 関数の実行を参照してください。

GPU 配列

Parallel Computing Toolbox™ を使用してグラフィックス処理装置 (GPU) 上で実行することにより、コードを高速化します。

movvar 関数は GPU 配列入力をサポートしますが、次の使用上の注意および制限があります。

• 名前と値の引数 SamplePoints、DataVariables、および ReplaceValues はサポートされません。

• table および timetable の入力はサポートされていません。

詳細については、GPU での MATLAB 関数の実行 (Parallel Computing Toolbox)を参照してください。

分散配列

Parallel Computing Toolbox™ を使用して、クラスターの結合メモリ上で大きなアレイを分割します。

使用上の注意および制限:

• 名前と値の引数 DataVariables および ReplaceValues はサポートされません。

• table および timetable の入力はサポートされていません。

詳細については、分散配列を使用した MATLAB 関数の実行 (Parallel Computing Toolbox)を参照してください。

バージョン履歴

R2016a で導入

R2025a: table および timetable のデータの移動統計を計算

演算対象の数値データを含む table および timetable を入力として指定できます。既定では、movvar は table または timetable のすべての変数について演算を行います。ただし、どの変数を演算の対象とするかを指定できます。出力 table または出力 timetable に movvar からの出力値を新しい変数として追加することもできます。

R2023a: 欠損値の条件の指定

"includemissing" オプションまたは "omitmissing" オプションを使用して、各分散値の計算時に入力配列の欠損値を含めるか省略します。これらのオプションの動作はそれぞれ、"includenan" オプションおよび "omitnan" オプションと同じです。

R2023a: サンプル点をもつ行列に対する計算時のパフォーマンスが向上

関数 movvar で、サンプル点がある場合に行列に対して計算する際のパフォーマンスが向上しています。

たとえば、以下のコードでは、対応するサンプル点をもつ 300 行 300 列の行列の移動分散値を計算しています。このコードは、以前のリリースよりパフォーマンスが約 2.2 倍高速化しました。

function timingMovvar
A = randn(300);
t = sort(rand(300,1));
tic
for k = 1:2000
    movvar(A,0.1,"SamplePoints",t);
end
toc
end

おおよその実行時間は以下のとおりです。

R2022b: 1.24 秒

R2023a: 0.56

このコードの時間測定では、Windows^® 10、Intel^® Xeon^® CPU E5-1650 v4 (3.60 GHz) を使用するテスト システムで、関数 timingMovvar を呼び出しました。

参考

関数

• movstd | movmean | movmedian | movmad | var