sacfile_get_signal_ratioコマンドマニュアル

(The documentation of sacfile_get_signal_ratio command)

Last Update: 2022/07/20

◆機能・用途(Purpose)

Seismic Analysis Code (SAC)形式の時系列データファイルから、 Maeda et al. (2020)の手法に基づいて振幅がバックグラウンドノイズレベルを上回る時刻サンプルの割合 (大振幅比率)を短く区切った時間窓毎に算出する。
Compute the ratio of the number of time samples with amplitudes greater than the background noise level (a large amplitude ratio) in each short time window of a time series data given by a Seismic Analysis Code (SAC) file based on the method proposed by Maeda et al. (2020).

◆概要(Overview)

連続波形を用いた地震などのイベント検知には短時間平均(STA)と長時間平均(LTA)の比STA/LTAがしばしば用いられる。この方法ではLTAがバックグラウンドノイズレベルを表すと仮定している。イベントによって一時的に振幅が増大するとLTAはあまり変わらずSTAが大きくなると期待されるため、STA/LTAの増大がイベントを表すという考え方である。しかしイベントの振幅が大きい場合、LTAも影響を受けてしまう。
The ratio of short-term average (STA) to long-term average (LTA) is widely used for detection of events (e.g., earthquakes) from continuous waveforms. In the STA/LTA method, the LTA is assumed to represent a background noise level. When the amplitude temporalily increases by an event, the STA is expected to increase while the LTA is kept stable, so that the increase in the STA/LTA ratio represents an event. A problem in this method is that the LTA is also affected by an event with a large amplitude.

そこでMaeda et al. (2020)では LTAよりもイベントの影響を受けずにバックグラウンドノイズレベルを推定する手法を考案した。この手法ではバックグラウンドノイズが平均値を0とする正規分布に従うと仮定している。 $N$サンプルからなる波形のうち、絶対値振幅が小さい順に$N’$サンプルのみが正規分布に従うと仮定し、それらの絶対値振幅の累積頻度分布と正規分布から期待される累積頻度分布が最も合う$N’$を $2\leq N’\leq N$の範囲で探索する。得られた最適な$N’$に対応する振幅がバックグラウンドノイズレベルを表すと考える。というのは、それよりも小さな振幅が正規分布に従う一方で、それよりも大きな振幅になると正規分布からずれると考えられるからである。
Maeda et al. (2020) proposed an alternative method to estimate the background noise level that is less affected by events than the LTA. This method assumes that the background noise oveys a normal distribution with zero average. Among the total $N$ samples of a waveform, assume that the smallest $N’$ samples in absolute amplitudes obey the normal distribution, and search the optimal $N’$ in $2\leq N’\leq N$ such that the cumulative distribution of the smallest $N’$ samples of absolute amplitudes is best fitted by what is expected from the normal distribution. The amplitude corresponding to this optimal $N’$ is regarded to represent the background noise level because samples with amplitudes below this level ovey the normal distribution while those above it deviate from the normal distribution.

手法の詳細や実際の観測データを用いた検証結果については Maeda et al. (2020)を参照のこと。
See Maeda et al. (2020) for more detail of the method and resuls of examinations by real observation data.

◆ソースコード(Source code)

$YMAEDA_OPENTOOL_DIR/event_detection/src/sacfile_get_signal_ratio.c

◆使用方法(Usage)

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

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

引数 Argument	与える値 Quantity to be given
第1引数 1st argument	入力として用いるSAC時系列データファイル名。 Name of the input SAC time series data file.
第2引数 2nd argument	出力する大振幅比率の時系列データファイル名。拡張子は ymaeda_opentools独自の時系列データファイル形式のいずれかにしなければならない。 The name of the output time series data for the large amplitude ratios. The extension must be one of the special file formats of ymaeda_opentools for time series data.

●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
long_window_length	バックグラウンドノイズレベルの計算に用いる長時間ウインドウの長さ。 The length of long time windows used to compute the background noise level.	長さを秒単位で指定する。正の実数値の後に単位を表す「s」を付ける⁽¹⁾。長さは入力時系列データの長さの整数分の1 かつ入力時系列データのサンプリング間隔の偶数倍でなければならない。 Specify the length in the unit of second. Append the unit “s” after a positive real number.⁽¹⁾ The length must be a divisor of the length of the input time series data and an even number multiple of the sampling interval of the data. なお、本手法では長時間ウインドウのデータサンプル数の2乗に比例して処理時間が増大する。 100Hzサンプリングの地震波形をリアルタイムで処理する場合、使用するコンピュータの性能にもよるが長時間ウインドウの長さを600秒程度以下に留めるのが現実的である。 Note that the processing time by this method increases as a square of the number of data samples in the long time window. For real-time processing of a seismic waveform trace with 100 Hz sampling, the length of the long time window should not be longer than 600 s, although this limitation depends on the computer used.	300.0s
short_window_length	大振幅比率の計算対象となる短時間ウインドウの長さ。 The length of short time windows for which the large amplitude ratios are to be computed.	長さを秒単位で指定する。正の実数値の後に単位を表す「s」を付ける⁽¹⁾。長さは長時間ウインドウ(パラメータlong_window_length)の整数分の1 かつ入力時系列データのサンプリング間隔の整数倍でなければならない。 Specify the length in the unit of second. Append the unit “s” after a positive real number.⁽¹⁾ The length must be a divisor of the long window length (given by parameter long_window_length) and an integer multiple of the sampling interval of the data.	1.0s
stddev_summary_file	推定したバックグラウンドノイズの平均値と標準偏差の出力先ファイル名。 The name of an output file into which the averages and standard deviations of the estimated background noise are to be written.	ファイル名を表す文字列。 A string that represents a file name.	このオプションの省略時はファイルが出力されない。 The file is not created when this option is omitted.
amp_threshold_summary_file	推定したバックグラウンドノイズレベル(振幅閾値)の出力先ファイル名。 The name of an output file into which the estimated background noise levels (threshold amplitudes) are to be be written.	ファイル名を表す文字列。 A string that represents a file name.	このオプションの省略時はファイルが出力されない。 The file is not created when this option is omitted.
noise_fitting_detail_dir	バックグラウンドノイズレベルの推定の詳細の出力先ディレクトリ名。 The name of an output directory into which details of the investigation of the background noise level are to be written.	ディレクトリ名を表す文字列。 A string that represents a directory name.	このオプションの省略時はディレクトリが出力されない。 The directory is not created when this option is omitted.
remove_mean	バックグラウンドノイズレベルの推定に先立って対象となる長時間ウインドウ内の平均値を波形データから差し引くか否か。 Whether or not to remove the mean in each long window before estimating the background noise level in the window.	yes 平均値を差し引く。 Remove the mean. no 平均値を差し引かない。 Do not remove the mean.	yes
verbose	表示する進行状況のレベル。 Level of displaying the progress.	0 進行状況を表示しない。 Do not display the progress. 1 1つの長時間ウインドウの処理が終わるごとに進行状況を表示する。 Display the progress whenever processings for each long time window finish. 2 上記に加え、最適な$N’$の探索において $N’$に関するループが100ステップ進むごとに進行状況を表示する。 In addition to above, display the progress for each 100 steps of the loop with regard to $N’$ during the search for the optimal $N’$.	0

「s」以外の単位は不可。単位「s」を付ける仕様にしているのはユーザが誤ってデータサンプル数を指定してしまうミスの防止用である。
Units other than ‘s’ are not available. The unit ‘s’ is appended to prevent users from specifying the number of data samples by mistake.

◆動作(Behaviour)

第1引数で指定したSAC時系列データを読み込んでパラメータlong_window_lengthで指定した長さのタイムウインドウに分割し、各ウインドウ毎にバックグラウンドノイズレベルを推定する。次にそのバックグランドノイズレベルを使用してパラメータshort_window_lengthで指定したタイムウインドウ毎に大振幅比率を計算し、第2引数で指定したファイルに時系列データとして出力する。
Read the SAC time series data from the file specified by the 1st argument, divide the data into time windows of the length specified by parameter long_window_length, and compute the background noise level in each window. Then, using the background noise level, the large amplitude ratio in each time window of the length specified by parameter short_window_length. The resultant large amplitude ratios are written into the file specified by the 2nd argument as a time series data.

パラメータstddev_summary_file, amp_threshold_summary_file, noise_fitting_detail_dirが指定された場合にはそれらに対応するファイルも出力する。それらの中身は以下の通りである。
Optionally, files specified by parameters stddev_summary_file, amp_threshold_summary_file, and noise_fitting_detail_dir are created. The contents of these files are as follows.

stddev_summary_file
テキストファイルであり、 1行につき1つのタイムウインドウ(長時間ウインドウ)での値を表す。各行は4列から成り、列の区切りにはタブが用いられる。各列の値は下表の通り。
A text file. Each line represents quantities in each long time window, composed of four columns separated by tabs. The table below shows the quantities in individual columns.

列 Column	値 Quantity
第1列 1st column	タイムウインドウの先頭時刻[s]。 The beginning time [s] of a time window.
第2列 2nd column	タイムウインドウの末尾時刻[s]。 The end time [s] of the time window.
第3列 3rd column	そのタイムウインドウにおける平均振幅。 The average amplitude in the time window.
第4列 4th column	そのタイムウインドウにおける振幅の標準偏差。 The standard deviation of amplitudes in the time window.

amp_threshold_summary_file
テキストファイルであり、 1行につき1つのタイムウインドウ(長時間ウインドウ)での値を表す。各行は3列から成り、列の区切りにはタブが用いられる。各列の値は下表の通り。
A text file. Each line represents quantities in each long time window, composed of three columns separated by tabs. The table below shows the quantities in individual columns.

列 Column	値 Quantity
第1列 1st column	タイムウインドウの先頭時刻[s]。 The beginning time [s] of a time window.
第2列 2nd column	タイムウインドウの末尾時刻[s]。 The end time [s] of the time window.
第3列 3rd column	そのタイムウインドウにおけるバックグラウンドノイズレベル(振幅閾値)。 The background noise level (threshold amplitude) in the time window.

noise_fitting_detail_dir
タイムウインドウ(長時間ウインドウ)毎に以下の3種類のファイルが作成される。ファイル名の[tmin], [tmax]はそれぞれ長時間ウインドウの先頭・末尾の時刻[s]を小数点以下3桁で表したものである。
The directory consists of the following three files for each long time window, where [tmin] and [tmax] are the start and end times [s] of the window with three digits after the decimal point.

residual.t[tmin]-[tmax]s.dat
$N’$を動かしたときの、データにおける絶対値振幅の累積頻度分布と正規分布を仮定したときの累積頻度分布とのずれ具合。これを最小にする$N’$が最適な$N’$である。
Misfits between the cumulative distribution of absolute amplitude of data and that expected from the normal distribution for moving $N’$. The smallest misfit corresponds to the optimal $N’$.

このファイルはテキストファイルであり、 1行につき1つの$N’$に対する値を表す。各行は6列から成り、列の区切りにはタブが用いられる。各列の値は下表の通り。表中の記号はMaeda et al. (2020)に基づく。
This is a text file. Each line represents quantities in each long time window, composed of six columns separated by tabs. The table below shows the quantities in individual columns. Symbols in the table are based on Maeda et al. (2020).

列 Column	値 Quantity	意味 Meaning
第1列 1st column	$N’$	使用したサンプル数。 The number of samples used.
第2列 2nd column	$\sigma^{odd}(N’/2)$	奇数番目のデータサンプルの小さい方から$N’/2$個の標準偏差。 The standard deviation of the smallest $N’/2$ samples of odd-numbered data.
第3列 3rd column	$\mu^{eo}(N’/2)$	偶数番目のデータサンプルの小さい方から$N’/2$個に基づく累積頻度分布と平均0、標準偏差$\sigma^{odd}(N’/2)$の正規分布に基づく累積頻度分布とのずれ具合。 Misfit between the cumulative distribution of the smallest $N’/2$ samples of even-numbered data and that of the normal distribution with zero average and a standard deviation of $\sigma^{odd}(N’/2)$.
第4列 4th column	$\sigma^{even}(N’/2)$	偶数番目のデータサンプルの小さい方から$N’/2$個の標準偏差。 The standard deviation of the smallest $N’/2$ samples of even-numbered data.
第5列 5th column	$\mu^{oe}(N’/2)$	奇数番目のデータサンプルの小さい方から$N’/2$個に基づく累積頻度分布と平均0、標準偏差$\sigma^{even}(N’/2)$の正規分布に基づく累積頻度分布とのずれ具合。 Misfit between the cumulative distribution of the smallest $N’/2$ samples of odd-numbered data and that of the normal distribution with zero average and a standard deviation of $\sigma^{even}(N’/2)$.
第6列 6th column	$\mu(N’/2)$	$\mu^{eo}(N’/2)$と$\mu^{oe}(N’/2)$ のうちの大きい方。この値を最小にする$N’$が最適な$N’$である。 The larger one of $\mu^{eo}(N’/2)$ and $\mu^{oe}(N’/2)$; the minimum value of this quantity corresponds to the optimum $N’$.

cumulative_probability.t[tmin]-[tmax]s.obs.dat
観測データに基づく振幅の累積確率。テキストファイルであり、各行は下表に示す2列から成り、列の区切りにはタブが用いられる。
The cumulative probabilities of amplitudes based on the observed data. This is a text file. Each line consists of two columns described in the table below, separated by a tab.

列 Column	値 Quantity
第1列 1st column	絶対値振幅。 An absolute amplitude.
第2列 2nd column	絶対値振幅がその値以下となる累積確率。 The cumulative probability that the absolute amplitude is less than or equal to the value given in the 1st column.

cumulative_probability.t[tmin]-[tmax]s.syn.dat
正規分布を仮定したときの振幅の累積確率。実際のデータが存在する振幅値での確率にすると振幅や確率に大きな飛びが発生してしまう場合があるので標準偏差の0.01倍の振幅刻み幅で計算・出力する。テキストファイルであり、各行は下表に示す2列から成り、列の区切りにはタブが用いられる。
The cumulative probabilities of amplitudes expected from a normal distribution. To avoid large jumps in amplitudes and probabilities, the probabilities are written not at the amplitudes of the data but at an uniform amplitude interval of 0.01 times the standard deviation. This is a text file. Each line consists of two columns described in the table below, separated by a tab.

列 Column	値 Quantity
第1列 1st column	絶対値振幅。 An absolute amplitude.
第2列 2nd column	絶対値振幅がその値以下となる累積確率。 The cumulative probability that the absolute amplitude is less than or equal to the value given in the 1st column.

◆使用例(Example)

sacfile_get_signal_ratio data.sac signal_ratio.seq1 --long_window_length=180.0s --stddev_summary_file=stddev.dat

◆引用文献 (References)

★ は本プログラムを用いた研究成果の発表時に必ず引用すべき論文を表す。
The star (★) indicates the references that must be cited whenever a research that used this program is published or presented.

★ Maeda Y, Yamanaka Y, Ito T, Horikawa S (2020) Machine learning based detection of volcano seismicity using the spatial pattern of amplitudes, Geophys J Int 225(1), 416-444. https://doi.org/10.1093/gji/ggaa593

この論文は下記の名古屋大学リポジトリからも利用できる。
This paper is also available from the repository of Nagoya University below.
https://nagoya.repo.nii.ac.jp/records/2001674

列 Column	値 Quantity	意味 Meaning
第1列 1st column	\(N’\)	使用したサンプル数。 The number of samples used.
第2列 2nd column	\(\sigma^{odd}(N’/2)\)	奇数番目のデータサンプルの小さい方から\(N’/2\)個の標準偏差。 The standard deviation of the smallest \(N’/2\) samples of odd-numbered data.
第3列 3rd column	\(\mu^{eo}(N’/2)\)	偶数番目のデータサンプルの小さい方から\(N’/2\)個に基づく累積頻度分布と平均0、標準偏差\(\sigma^{odd}(N’/2)\)の正規分布に基づく累積頻度分布とのずれ具合。 Misfit between the cumulative distribution of the smallest \(N’/2\) samples of even-numbered data and that of the normal distribution with zero average and a standard deviation of \(\sigma^{odd}(N’/2)\).
第4列 4th column	\(\sigma^{even}(N’/2)\)	偶数番目のデータサンプルの小さい方から\(N’/2\)個の標準偏差。 The standard deviation of the smallest \(N’/2\) samples of even-numbered data.
第5列 5th column	\(\mu^{oe}(N’/2)\)	奇数番目のデータサンプルの小さい方から\(N’/2\)個に基づく累積頻度分布と平均0、標準偏差\(\sigma^{even}(N’/2)\)の正規分布に基づく累積頻度分布とのずれ具合。 Misfit between the cumulative distribution of the smallest \(N’/2\) samples of odd-numbered data and that of the normal distribution with zero average and a standard deviation of \(\sigma^{even}(N’/2)\).
第6列 6th column	\(\mu(N’/2)\)	\(\mu^{eo}(N’/2)\)と\(\mu^{oe}(N’/2)\) のうちの大きい方。この値を最小にする\(N’\)が最適な\(N’\)である。 The larger one of \(\mu^{eo}(N’/2)\) and \(\mu^{oe}(N’/2)\); the minimum value of this quantity corresponds to the optimum \(N’\).

sacfile_get_signal_ratioコマンド マニュアル