sequencefiles_group_by_correlationコマンド マニュアル

(The documentation of sequencefiles_group_by_correlation command)
Last Update: 2024/1/16

◆機能・用途(Purpose)

複数の時系列データファイルを読み込んで波形相関によりグルーピングする。
Read time series data files and group them based on waveform correlations.

◆ソースコード(Source code)

$YMAEDA_OPENTOOL_DIR/sequence/src/sequencefiles_group_by_correlation.c


◆使用方法(Usage)

コマンドライン引数でパラメータを指定する。 パラメータの一覧を下表に示す。
Specify parameters by command-line arguments. The table below shows a list of parameters.

●「-」から始まらない引数 (Arguments not beginning with “-”)

このコマンドでは「-」から始まらない引数は存在しない。
This command does not have arguments not beginning with “-”.

●1つの「-」から始まる引数 (Arguments beginning with a single “-”)

このコマンドでは1つの「-」から始まる引数は存在しない。
This command does not have arguments beginning with a single “-”.

●「--パラメータ名=パラメータ値」の形式の引数 (Arguments of a form “--Parameter name=Parameter Value”)

「--パラメータ名=パラメータ値」の形式の引数は自由な順番で指定できる。 「-」から始まらない引数の間に挿入しても良い。 相反する指定がなされた場合には後の指定が優先される。 デフォルト値を持つパラメータは省略できる。
Arguments of a form “--Parameter name=Parameter Value” can be placed in an arbitrary order. They can even be inserted between arguments not beginning with “-”. In case of conflicting options being specified, the latter option has a higher priority. Parameters that have default values can be omitted.
パラメータ名
Parameter name 		意味
Meaning 		可能なパラメータ値
Allowed parameter values 		デフォルト値
Default value
datadir 使用する時系列データが格納されているディレクトリパス。
The path of the directory in which the time series data to be used are stored. 		ディレクトリパスを表す文字列。絶対パスでも相対パスでも良い。
A string that represents a directory path (either absolute or relative). 		.
timeSeriesData_listFile 使用する時系列データを列挙したテキストファイルの名前。
The name of a text file in which the time series data to be used are listed.
このファイル内には1行につき1つずつ、 使用する時系列データファイル名 (パラメータdatadirで指定したディレクトリからの相対パス) を記載する。 空行や各行の#から後の部分はコメントとして無視されるので 自由に挿入できる。
In this file, write a time series data file name (the relative path from the directory specified by parameter datadir) in each line. Empty lines and comments after # in each line can arbitrarily be inserted, as they are simply ignored.
なお、個々の時系列データファイルは ymaeda_opentoolsの時系列データファイル形式 (独自のファイル形式参照) でなければならない。 また、時系列データの定義域とサンプリングレートは 全てのファイルで共通でなければならない。
Each time series data file must have one of the formats of a time series data of ymaeda_opentools (see special file formats). The definition range and sampling rate must be common among all time series data.
 ファイル名を表す文字列。
A string that represents a file name. 		省略不可
Cannot be omitted
threshold 相関係数の閾値。 2つの時系列データの相関係数がこの値よりも大きければ 同じグループに分類する。
A threshold value for a correlation coefficient; if the correlation coefficient between two time series data is greater than this value, the two data are labeled as the same group. 		-1以上1以下の実数。
A real number greater than or equal to -1 and less than or equal to 1. 		0.8
outputfile 出力ファイル名。 グルーピングの結果が出力される。
The name of the output file in which the result of the grouping is written. 		ファイル名を表す文字列。
A string that represents a file name. 		省略不可
Cannot be omitted
baseline_slope 相関係数の計算時に時系列データから差し引く直線の傾き\(a\) (下記「アルゴリズム」参照)。
The slope, \(a\), of the straight line that is subtracted from the original time series data in the computation of the correlation coefficients. 		実数。
A real number. 		0.0
baseline_intercept 相関係数の計算時に時系列データから差し引く直線の時刻\(t=0\)での値\(b\) (下記「アルゴリズム」参照)。
The value, \(b\), at the time \(t=0\) of the straight line that is subtracted from the original time series data in the computation of the correlation coefficients. 		実数。
A real number. 		0.0


◆動作(Behaviour)

パラメータtimeSeriesData_listFileで指定したテキストファイルに列挙されている 時系列データを読み込み、 それらを相関係数に基づいてグルーピングし、 結果をパラメータoutputfileで指定したファイルに出力する。
Read the time series data listed in the text file specified by parameter timeSeriesData_listFile, group them based on correlation coefficients, and output the result into the file specified by parameter outputfile.
出力ファイルは2列から成り、 1列目が時系列データファイル名、 2列目がグループ番号(1から始まる連番)である。 列の区切りにはタブが用いられる。 先頭部のコメント行にグループ数と相関係数の閾値が出力される。
The output file is composed of two columns; the time series data file name is in the 1st column, and the group (a consecutive number starting from 1) is in the 2nd column. A tab is used to separate the columns. The number of groups and the threshold value of the correlation coefficient are written in the comment lines at the top.

◆使用例(Example)

sequencefiles_group_by_correlation --datadir=data --timeSeriesData_listFile=file_list.dat --outputfile=groups.dat
(file_list.dat)
a.seq2
b.seq2
c.seq2
d.seq2
e.seq2
f.seq2
g.seq2
h.seq2
i.seq2
j.seq2
k.seq2
l.seq2
m.seq2
n.seq2

この例ではディレクトリdataの中にある a.seq2からn.seq2までの14個の時系列データファイルを読み込み、 例えば以下のようなファイルが出力される。 ここで[TAB]はタブを表す。
In this example, 14 time series data files from a.seq2 to n.seq2 are read from the directory data. The output file is, for example, as follows, where [TAB] represents a tab.
(group.dat)
#Ngroups: 5
#threshold: 0.800000
data/a.seq2[TAB]2
data/b.seq2[TAB]1
data/c.seq2[TAB]3
data/d.seq2[TAB]1
data/e.seq2[TAB]2
data/f.seq2[TAB]1
data/g.seq2[TAB]1
data/h.seq2[TAB]1
data/i.seq2[TAB]2
data/j.seq2[TAB]3
data/k.seq2[TAB]1
data/l.seq2[TAB]4
data/m.seq2[TAB]5
data/n.seq2[TAB]1


◆アルゴリズム(The algorithm)

このプログラムでは相互相関関数ではなく 時刻をずらさない相関係数を使用する。 2つの時系列データを\(f(t)\), \(g(t)\)とし、 これらが時刻\(t=t_0+k\Delta t\), \(k=0,1,\cdots,N-1\)で定義されているとき、 相関係数は \[\begin{equation} C=\frac{\sum_{k=0}^{N-1} f(t_0+k\Delta t)g(t_0+k\Delta t)} {\sqrt{\sum_{k=0}^{N-1} f(t_0+k\Delta t)^2} \sqrt{\sum_{k=0}^{N-1} g(t_0+k\Delta t)^2}} \label{eq.correlation} \end{equation}\] により計算する。
This program does not use the cross correlation functions but uses the correlation coefficients with zero lag time. Let \(f(t)\) and \(g(t)\) be time series data sampled at times \(t=t_0+k\Delta t\), where \(k=0,1,\cdots,N-1\). The correlation coefficient between the two time series data is calculated by Eq. (\ref{eq.correlation}).
振動ではなく地殻変動などの単調増加(または単調減少)するシグナルを扱う場合、 形状の違いが相関係数に現れにくいという問題がある。 例えば区間\(t\in [0,1]\)で定義された3つの関数 \(f_1(t)=t\), \(f_2(t)=t^2\), \(f_3(t)=\sqrt{t}\)を考える。 \(f_1(t)\)は線形、\(f_2(t)\)は下に凸(加速型)、\(f_3(t)\)は上に凸(減速型) の関数であり、形状は明らかに異なる。 にも関わらず、 \(f_1(t)\)と\(f_2(t)\)の相関係数は \[\begin{eqnarray} C_{12} &=& \frac{\int_0^1 f_1(t)f_2(t)dt} {\sqrt{\int_0^1 f_1(t)^2 dt} \sqrt{\int_0^1 f_2(t)^2 dt}} \nonumber \\ &=& \frac{\int_0^1 t^3 dt} {\sqrt{\int_0^1 t^2 dt} \sqrt{\int_0^1 t^4 dt}} \nonumber \\ &=& \frac{\left[\frac{t^4}{4}\right]_0^1} {\sqrt{\left[\frac{t^3}{3}\right]_0^1} \sqrt{\left[\frac{t^5}{5}\right]_0^1}} \nonumber \\ &=& \frac{(1/4)}{\sqrt{1/3}\sqrt{1/5}} \nonumber \\ &=& \frac{\sqrt{15}}{4} \nonumber \\ &\sim& 0.9682 \label{eq.C12} \end{eqnarray}\] \(f_1(t)\)と\(f_3(t)\)の相関係数は \[\begin{eqnarray} C_{13} &=& \frac{\int_0^1 f_1(t)f_3(t)dt} {\sqrt{\int_0^1 f_1(t)^2 dt} \sqrt{\int_0^1 f_3(t)^2 dt}} \nonumber \\ &=& \frac{\int_0^1 t^{1.5} dt} {\sqrt{\int_0^1 t^2 dt} \sqrt{\int_0^1 t dt}} \nonumber \\ &=& \frac{\left[\frac{t^{2.5}}{2.5}\right]_0^1} {\sqrt{\left[\frac{t^3}{3}\right]_0^1} \sqrt{\left[\frac{t^2}{2}\right]_0^1}} \nonumber \\ &=& \frac{(1/2.5)}{\sqrt{1/3}\sqrt{1/2}} \nonumber \\ &=& \frac{2\sqrt{6}}{5} \nonumber \\ &\sim& 0.9798 \label{eq.C13} \end{eqnarray}\] \(f_2(t)\)と\(f_3(t)\)の相関係数は \[\begin{eqnarray} C_{23} &=& \frac{\int_0^1 f_2(t)f_3(t)dt} {\sqrt{\int_0^1 f_2(t)^2 dt} \sqrt{\int_0^1 f_3(t)^2 dt}} \nonumber \\ &=& \frac{\int_0^1 t^{2.5} dt} {\sqrt{\int_0^1 t^4 dt} \sqrt{\int_0^1 t dt}} \nonumber \\ &=& \frac{\left[\frac{t^{3.5}}{3.5}\right]_0^1} {\sqrt{\left[\frac{t^5}{5}\right]_0^1} \sqrt{\left[\frac{t^2}{2}\right]_0^1}} \nonumber \\ &=& \frac{(1/3.5)}{\sqrt{1/5}\sqrt{1/2}} \nonumber \\ &=& \frac{2\sqrt{10}}{7} \nonumber \\ &\sim& 0.9035 \label{eq.C23} \end{eqnarray}\] といずれも高い値を示す。 そのため、このような形状の違いを相関係数で区別するのは容易でない。 そこでこのプログラムでは\(f(t)\), \(g(t)\)の代わりに \(f(t)-at-b\), \(g(t)-at-b\)を用いるオプションを用意している。 ここで\(a\), \(b\)はパラメータ baseline_slope, baseline_interceptの値である。 これらのデフォルト値は0であるが、ノンゼロの\(a\), \(b\)を与えることで \(f(t)\), \(g(t)\)から\(at+b\)を差し引いたデータを用いて 相関係数を計算できる。
When signals to be treated monotonically increase or decrease, for example in case of crustal deformation rather than oscillating seismic signals, a difference in their shapes is difficult to quantify by correlation coefficients. For example, consider three functions (f_1(t)=t\), \(f_2(t)=t^2\), and \(f_3(t)=\sqrt{t}\) in a definition range of \(t\in [0,1]\). The function \(f_1(t)\) is linear, \(f_2(t)\) is bended downward (an acceleration type), and \(f_3(t)\) is bended upward (a deleceration type). Despite these differences in their shapes, the correlation coefficients among them are extremely high (Eqs. \ref{eq.C12}-\ref{eq.C13}), making it difficult to quantify the differences by correlation coefficients. To cope with this problem, this program can optionally use \(f(t)-at-b\) and \(g(t)-at-b\) instead of \(f(t)\) and \(g(t)\) in the calculation of correlation coefficients, where \(a\) and \(b\) are the values of parameters baseline_slope and baseline_intercept, respectively. The default values of them are zero, and using non-zero \(a\) and \(b\) values results in subtracting \(at+b\) from \(f(t)\) and \(g(t)\) before computing the correlation coefficients.
相関係数に基づくグルーピングの方法は基本的に Green and Neuberg (2006)と同様である。 まず、相関係数が閾値を超えるペアを最も多く有する時系列データをマスターとして選び、 その時系列データとの相関係数が閾値を超える時系列データをグループ1に分類する。 残りの時系列データに対して同様の処理を行ってグループ2を定義する。 以下同様にしてグループ3,4,5,…と順に定義する。
The grouping method is basically same as that used in Green and Neuberg (2006). First, select the time series data (a master time series data) that has the largest number of pairs that have correlation coefficients above the threshold value. All time series data that have correlation coefficients above the threshold value with this master time series data are labeled as group 1. Repeat the same procedure to the remaining time series data to define group 2. Groups 3, 4, 5, …, are sequentially defined in the same way.

◆引用文献(References)