sacfiles_filter_continuousコマンドマニュアル

(The documentation of sacfiles_filter_continuous command)

Last Update: 2023/12/4

◆機能・用途(Purpose)

複数ファイルに分割されたSAC時系列データを 1つの連続する時系列データと見なしてフィルターを掛ける。
Apply a filter to a continuous SAC time series data that is separated into multiple files.

長期間の連続地震波形は通常、 1時間あるいは1日などの時間単位で区切って別々のファイルに格納される。それら個々のファイル内の波形データに対して個別にフィルターを掛ける場合、ファイルの区切り付近の時刻において正しい波形が保持されない。このプログラムの目的なそのような時系列データに対して連続波形全体が1つの巨大なファイルに格納されている場合と完全に同等のフィルターを掛けることである。
A long continuous seismic waveform is usually stored in multiple files, divided based on time sections of, for example, 1-hour or 1-day long. Applying a filter to the waveforms in individual files separately results in distortion near boundary times. The purpose of this program is to apply a filter to such data to obtain a waveform exactly identical to what would be obtained by applying the filter to the entire waveform stored in a single, huge file.

このプログラムでは因果律を満たす漸化式フィルターを取り扱う。元の波形を$f(t)$、フィルターを掛けた波形を$g(t)$、サンプリング間隔を$\Delta t$として、漸化式フィルターは以下の形で表される。 \[\begin{equation} g(t)= a_2f(t-2\Delta t)+a_1f(t-\Delta t)+f(t)-b_2g(t-2\Delta t)-b_1g(t-\Delta t) \label{eq.recursive_base} \end{equation}\] ここで$a_1$, $a_2$, $b_1$, $b_2$はフィルター特性で決まる定数である。 (\ref{eq.recursive_base})式は関数recursive_base で用いられる最も基本的なフィルターであり、定数$a_1$, $a_2$, $b_1$, $b_2$を変えてこれを繰り返し適用することで任意のフィルターを実現できる。
This program treats a causal filter of recursive type (Eq. \ref{eq.recursive_base}), where $f(t)$ and $g(t)$ are the original and filtered waveforms, respectively; $\Delta t$ is the sampling interval; and $a_1$, $a_2$, $b_1$, and $b_2$ are constants determined by the property of the filter. Eq. (\ref{eq.recursive_base}) is the elementary filter used in function recursive_base. Repeatedly applying it with different values of $a_1$, $a_2$, $b_1$, and $b_2$ results in an arbitrary filter.

(\ref{eq.recursive_base})式において$t$がデータの先頭時刻の場合、 $f(t-\Delta t)=f(t-2\Delta t)=g(t-\Delta t)=g(t-2\Delta t)=0$ であることが仮定される。これにより、波形の先頭部はそれ以前の時刻のデータが存在する場合とは異なるものになる。このプログラムでは1つのファイルにおいてはデータの先頭であっても別のファイルにそれ以前の時刻の波形データが存在する場合、それらを繋げて(\ref{eq.recursive_base})式を適用する。これにより、ファイルの区切りをまたいで連続なフィルターを実現できる。
If $t$ is the beginning time of the data, $f(t-\Delta t)=f(t-2\Delta t)=g(t-\Delta t)=g(t-2\Delta t)=0$ is assumed in Eq. (\ref{eq.recursive_base}). Because of this treatment, the beginning part of the filtered waveform is different from what would be if the previous data was present. This program applies Eq. (\ref{eq.recursive_base}) over multiple files; even if $t$ is the beginning of a file, data before that time is referred from another file in which the previous data is stored. This treatment realizes a continuous filter over the time section of the file unit.

◆ソースコード(Source code)

$YMAEDA_OPENTOOL_DIR/sac_data/src/sacfiles_filter_continuous.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
inputfiles	入力として用いる生波形データファイル名。ファイルはSAC形式の時系列データファイルとする。通常、複数のファイルであるが、それらを列挙するのではなく、日時をパターンとして含む形で命名規則で与える。 The name of the raw waveform data files used as the inputs. Each file must be a time series data file of SAC format. Although multiple files are usually used, do not list them but instead give the naming rule of the file names that includes the patterns corresponding to the date and time.	ファイル名を表す文字列。ディレクトリパスを含んでいても良い。以下のパターン文字列を含めることができる。 A string that represents a file name, possibly including the directory path. The patterns listed below can be used. %YYYY 年(西暦、4桁) Year (A.D., 4-digits) %YY 年(西暦、下2桁) Year (A.D., lowest 2-digits) %MM 月(2桁) Month (2-digits) %DD 日(2桁) Day (2-digits) %hh 時(2桁) Hour (2-digits) %mm 分(2桁) Minute (2-digits) %ss 秒(2桁) Second (2-digits)	省略不可 Cannot be omitted
outputfiles	フィルタ後の波形データ(SAC形式)の出力先ファイル名。入力ファイルと同じ時間区切りが用いられるので通常は複数のファイルになるが、それらを列挙するのではなく、日時をパターンとして含む形で命名規則で与える。 The name of the output files for the filtered waveform data (SAC format). Although multiple files are usually created, with the same time sections as the input files, do not list them but instead give the naming rule of the file names that includes the patterns corresponding to the date and time.	ファイル名を表す文字列。ディレクトリパスを含んでいても良い。パラメータinputfilesと同様のパターン文字列を含めることができる。 A string that represents a file name, possibly including the directory path. The patterns same as those for parameter inputfiles can be used.	省略不可 Cannot be omitted
start	解析期間の先頭日時。 The beginning date and time of the analysis period.	「YYYY-MM-DD.hh-mm-ss」の形式の文字列。ここで YYYY: 年(西暦4桁) MM: 月(2桁) DD: 日(2桁) hh: 時(2桁) mm: 分(2桁) ss: 秒(2桁) である。 A string of “YYYY-MM-DD.hh-mm-ss” format, where YYYY is the year (A.D., 4-digits), MM is the month (2-digits), DD is the day (2-digits), hh is the hour (2-digits), mm is the minute (2-digits), and ss is the second (2-digits).	省略不可 Cannot be omitted
end	解析期間の末尾日時。 The end date and time of the analysis period.	「YYYY-MM-DD.hh-mm-ss」の形式の文字列。ここで YYYY: 年(西暦4桁) MM: 月(2桁) DD: 日(2桁) hh: 時(2桁) mm: 分(2桁) ss: 秒(2桁) である。 A string of “YYYY-MM-DD.hh-mm-ss” format, where YYYY is the year (A.D., 4-digits), MM is the month (2-digits), DD is the day (2-digits), hh is the hour (2-digits), mm is the minute (2-digits), and ss is the second (2-digits).	省略不可 Cannot be omitted
file_interval	入力ファイルの時間区切りの長さ(s)。例えば1時間毎に分割されたファイルを用いる場合は3600となる。 The time length (s) of individual input files. For example, the value is 3600 if the files are divided every 1 hour.	正の整数。 A positive integer.	パラメータinputfileに登場するパターン文字列の最小時間単位。例えばパラメータinputfileに%hhまで登場するなら1時間刻み(3600)、 %mmまで登場するなら1分刻み(60)となる。 The minimum time unit of the pattern strings that appear in parameter inputfile. For example, if the parameter inputfile includes down to %hh then the interval is 1 hour (3600); if %mm is included then 1 min (60).
lpc	適用するローパスフィルターのコーナー周波数(Hz)。 ⁽¹⁾ The corner frequency (Hz) of the low-pass filter applied. ⁽¹⁾	正の実数。 A positive real number.	省略時はローパスフィルター無しとなる。 Omitting this parameter results in no low-pass filter.
lpn	適用するローパスフィルターの極の数。 The number of poles of the low-pass filter applied.	正の整数。 A positive integer.	2
hpc	適用するハイパスフィルターのコーナー周波数(Hz)。 ⁽¹⁾ The corner frequency (Hz) of the high-pass filter applied. ⁽¹⁾	lpcよりも小さな正の実数。 A positive real number less than lpc.	省略時はハイパスフィルター無しとなる。 Omitting this parameter results in no high-pass filter.
hpn	適用するハイパスフィルターの極の数。 The number of poles of the high-pass filter applied.	正の整数。 A positive integer.	2

パラメータlpcとhpcは少なくとも一方は指定しなければならない。両方を指定した場合はバンドパスフィルターとなる。バンドパスフィルターは最初にローパスフィルターを掛け、次にハイパスフィルターを掛ける方式で実装されている。
At least one of parameters lpc or hpc must be specified. Specifying the both results in a band-pass filter, implemented by first applying a low-pass filter and then a high-pass filter.

◆動作(Behaviour)

パラメータstartで指定した日時からendで指定した日時までの期間における、パラメータfile_intervalで指定した時間間隔で区切られた SAC形式の時系列データファイル (パラメータinputfilesで指定したファイル名パターンを持つもの) を順次読み込み、パラメータlpc, lpn, hpc, hpnの指定に基づいて因果律を満たす漸化式フィルターを掛け、得られた波形をパラメータoutputfilesで指定したファイルに出力する。ファイルの区切りをまたいで漸化式(\ref{eq.recursive_base})を適用する。
Read the time series data files of SAC format (with a pattern of file names specified by parameter inputfiles) from the date and time specified by parameter start to those specified by parameter end at a time interval given by parameter file_interval. Apply a filter to them based on parameters lpc, lpn, hpc, and hpn. Output the filtered waveforms into files specified by parameter outputfiles. The recursive formula (\ref{eq.recursive_base}) is applied beyond the time sections of the files.

◆使用例(Example)

sacfiles_filter_continuous --inputfiles=data_raw/%YYYY-%MM-%DD.sac --outputfiles=data_filtered/%YYYY-%MM-%DD.sac --start=2023-10-01.00-00-00 --end=2023-11-15.23-59-59 --file_interval=86400 --lpc=2.0 --hpc=8.0

この例では以下のファイルが存在することを仮定している (下記以外の期間のファイルが存在していても構わない)。
This example assumes that the following files are present (no matter if files for periods out of the time range shown below are present).

ファイル File	中身 Content
data_raw/2023-10-01.sac	2023年10月1日の24時間の生波形データ。 A 24-hour raw waveform data on October 1, 2023.
data_raw/2023-10-02.sac	2023年10月2日の24時間の生波形データ。 A 24-hour raw waveform data on October 2, 2023.
data_raw/2023-10-03.sac	2023年10月3日の24時間の生波形データ。 A 24-hour raw waveform data on October 3, 2023.
…
data_raw/2023-11-15.sac	2023年11月15日の24時間の生波形データ。 A 24-hour raw waveform data on November 15, 2023.

これらのファイルを順次読み込んで2-8 Hzのバンドパスフィルターを掛け、結果を下記のファイルに出力する。
These files are sequentially read, a band-pass filter of 2-8 Hz is applied, and the results are written into the files listed below.

ファイル File	中身 Content
data_filtered/2023-10-01.sac	2023年10月1日の24時間の波形データ(フィルターを掛けた波形)。 A 24-hour filtered waveform data on October 1, 2023.
data_filtered/2023-10-02.sac	2023年10月2日の24時間の波形データ(フィルターを掛けた波形)。 A 24-hour filtered waveform data on October 2, 2023.
data_filtered/2023-10-03.sac	2023年10月3日の24時間の波形データ(フィルターを掛けた波形)。 A 24-hour filtered waveform data on October 3, 2023.
…
data_filtered/2023-11-15.sac	2023年11月15日の24時間の波形データ(フィルターを掛けた波形)。 A 24-hour filtered waveform data on November 15, 2023.

個々のファイルの波形に対してフィルターを掛けるのと異なるのはファイル内の先頭・末尾のデータの取り扱いである。例えば2023年10月1日のデータの最後の2サンプルが 2023年10月2日のデータの最初のサンプルに対するフィルタ処理の中で (\ref{eq.recursive_base})式の形で用いられる。
This is different from separately applying the filter to individual files in the treatment of beginning and end data in each file. For example, the last two samples of the data on October 1, 2023, is used to compute the first sample of the filtered data on October 2, 2023, in the form of Eq. (\ref{eq.recursive_base}).

◆検証 (Validation)

以下の関数形$f(t)$を持つ2時間分の波形を作成した。 \[\begin{equation} f(t)= \begin{cases} 0 & (t<t_b) \\ (t-t_b)e^{-(t-t_b)/T_1}\sin\theta(t) & (t\geq t_b) \end{cases} \label{eq.test.f} \end{equation}\] \[\begin{equation} \theta(t)=\omega_0(t-t_b) +\frac{\Delta\omega}{(2\pi/T_2)}\sin\frac{2\pi(t-t_b)}{T_2} \label{eq.test.theta} \end{equation}\] なお(\ref{eq.test.theta})式を微分すると \[\begin{equation} \frac{d\theta(t)}{dt}=\omega_0+\Delta\omega\cos\frac{2\pi(t-t_b)}{T_2} \label{eq.test.theta_dot} \end{equation}\] となるので、$\theta(t)$は角周波数$\omega_0\pm\Delta\omega$での周波数変調の結果として生じる位相を表している。式に登場する定数の値は $t_b=3360$ s, $T_1=200$ s, $\omega_0=2\pi\times 0.3$ Hz, $\Delta\omega=2\pi\times 0.2$ Hz, $T_2=70$ sとした。波形は100 Hzサンプリングとし、先頭日時を2022/12/31 23:00:00とした。この波形に対して0.05-0.1 Hzのバンドパスフィルター(最小位相、極の個数:6) を適用した。
A two-hour-long waveform of function $f(t)$ defined by Eq. (\ref{eq.test.f}) was created, where $\theta(t)$ is defined by Eq. (\ref{eq.test.theta}). The derivative of $\theta(t)$ is given by Eq. (\ref{eq.test.theta_dot}), indicating that $\theta(t)$ represents the phase from a frequency modulation at an angular frequency $\omega_0\pm\Delta\omega$. The constants used were $t_b=3360$ s, $T_1=200$ s, $\omega_0=2\pi\times 0.3$ Hz, $\Delta\omega=2\pi\times 0.2$ Hz, and $T_2=70$ s. The waveform was sampled at 100 Hz, and an absolute time of 23:00:00 on December 31, 2022, was applied to the beginning of the waveform. A band-pass filter of 0.05-0.1 Hz (minimum phase, 6 poles) was applied.

図1aは作成した生波形、図1b, cにおける灰色の線は 2時間の波形全体に対してSACを用いてバンドパスフィルターを掛けた波形である。 2022/12/31 23:55-2023/01/01 00:10の範囲を拡大して表示している。
Fig. 1a shows the raw waveform, and the gray lines in Figs. 1b and c show the filtered waveform, where the band-pass filter was applied to the entire two-hour-long waveform. A time window from 23:55 on December 31, 2022, to 00:10 on January 1, 2023, is shown.

この波形を5分単位で別々のSACファイルに分割して保存した上で、個々のファイルの波形に対して別々に SACを用いてバンドパスフィルターを掛けた波形を図1bに色付きの線で示す。ファイルの区切りでプロット色を変えている。この波形(赤、緑、青)にはファイルの区切りで不連続が生じており、 2時間の波形全体に対してフィルターを掛けた結果(灰色)とは異なっている。
This waveform was then divided into separate SAC files of 5-min-long. For each 5-min waveform, the band-pass filter was applied independently. The results are shown by colored lines in Fig. 1b, where different colors show the results from different files. This waveform (red, green, and blue) consists of discontinuities at the boundary times of file units, and is different from the filtered waveform from the entire two-hour data (gray).

一方、5分毎に区切られた波形に対して sacfiles_filter_continuousコマンドを用いてフィルターを掛けた結果を図1cに色(赤、緑、青)で示す。ファイルの区切りで不連続は生じておらず、 2時間の波形全体に対してフィルターを掛けた結果(灰色)と一致している。
The colored (red, green, and blue) lines in Fig. 1c show the results of filtering for the 5-min separated waveforms using sacfiles_filter_continuous command. There is no discontinuity at the boundary times of file units, and the result is consistent with the filtered waveform from the entire two-hour data (gray).

図1. プログラムのテスト結果。 (a)使用した生波形。 (b)SACを用いてバンドパスフィルターを掛けた波形。灰色:波形全体が1つのファイルに格納されている場合。色:波形が5分刻みで別々のファイルに格納されている場合。 (c)灰色は図1bと同じ。色は5分刻みで別々のファイルに格納されている波形データに対して sacfiles_filter_continuousコマンドを用いてフィルターを掛けた結果。色の区切りはファイルの区切りを示す。
Fig. 1. The result of checking the program. (a) The raw waveform used for the test. (b) Band-pass filtered waveforms from SAC. Gray is the result from the entire waveform in a single file. Color shows the result from individual 5-min waveforms in separate files. (c) Gray is same as Fig. 1b. Color shows the output of sacfiles_filter_continuous command applied to the 5-min separated waveforms. Different colors represent different files.

sacfiles_filter_continuousコマンド マニュアル