sacfiles_matchedFilterコマンド マニュアル

(The documentation of sacfiles_matchedFilter command)
Last Update: 2025/2/26

◆機能・用途(Purpose)

SAC時系列データ形式の連続波形からテンプレート波形との類似度が高い時間帯をリストアップする。 いわゆるmatched filter解析であり、 類似度の評価には複数の観測点・成分を同時に用いることができる。 各観測点・成分の連続波形は日時によって複数ファイルに分かれていても良い。
List the times when the similarity is high between continuous and template waveforms in SAC time series data format. The similarity can be evaluated using multiple stations and components simultaneously (a matched filter analysis). The continuous waveform at each station and component can be separated as multiple files based on dates and times.

◆ソースコード(Source code)

$YMAEDA_OPENTOOL_DIR/event_detection/src/sacfiles_matchedFilter.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 continuous 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)

  • %JJJ
    その年の先頭からの日数(3桁、1月1日が001)
    The number of days from the beginning of the year (3-digits; Jan. 1 corresponds to 001)

  • %hh
    時(2桁)
    Hour (2-digits)

  • %mm
    分(2桁)
    Minute (2-digits)

  • %ss
    秒(2桁)
    Second (2-digits)

  • %STATION
    観測点コード
    Station code

  • %COMPONENT
    成分コード
    Component code

 省略不可
Cannot be omitted
templates テンプレートとして用いる短時間の波形データファイル名。
The name of the short-duration waveform data files used as the templates. 		ファイル名を表す文字列。ディレクトリパスを含んでいても良い。 パターン文字列として「%STATION」「%COMPONENT」 (パラメータinputfiles参照)を含めることができる。
A string that represents a file name, possibly including the directory path. The pattern “%STATION” and “%COMPONENT” (see parameter inputfiles) can be used. 		省略不可
Cannot be omitted
outputfile 出力ファイル名。 テキストファイルであり、拡張子は何でも良い。 類似度が閾値を超えた日時(YYYY/MM/DD hh:mm:ss.sss形式)とそのときの類似度の値が タブ区切りで出力される。
The name of the output file. This is a text file with an arbitrary extension and consists of the dates and times (in YYYY/MM/DD hh:mm:ss.sss format) when the similarity exceeded a threshold value and the threshold value, separated by a tab. 		ファイル名を表す文字列。ディレクトリパスを含んでいても良い。
A string that represents a file name, possibly including the directory path. 		省略不可
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).
trace_list_file 使用する観測点・成分コードのリストファイル。 1行につき1つの観測点・成分を記載したテキストファイルとし、 観測点コードと成分コードはタブで区切る。
A file that lists the stations and components used. This is a text file. Write a station code and a component code in each line of this file. Use a tab to separate the station and component codes. 		ファイル名を表す文字列。ディレクトリパスを含んでいても良い。
A string that represents a file name, possibly including the directory path. 		パラメータinputfiles, templatesの値に 「%STATION」または「%COMPONENT」が含まれる場合は省略不可。 「%STATION」「%COMPONENT」が含まれない場合は このパラメータは用いられない。
Cannot be omitted if the values of parameters inputfiles and templates consist of “%STATION” or “%COMPONENT”; if none of them are included, this parameter is not used.
similarity 使用する波形の類似度の指標。
A measure of the similarity of waveforms used.
  • correlation_ave
    全観測点・成分について相関係数を平均した値。 取りうる値の範囲:\([-1,1]\)、デフォルト値:0.7。
    The correlation coefficients averaged over all stations and components. The possible range of the value: \([-1,1]\), default value: 0.7.

 correlation_ave
threshold 類似度の閾値。 パラメータsimilarityで定義する類似度が この値を超える時刻をリストアップする。
A threshold value for the similarity; the program lists the times when the similarity defined by parameter similarity exceeds this threshold value. 		パラメータsimilarityで定義する指標の取りうる範囲の実数値。
A real number within the possible range of the measure defined by parameter similarity. 		パラメータsimilarityの説明参照。
See the description of parameter similarity.
minimum_interval 検出する時刻の最小間隔(s)。 類似度が閾値を超える時刻がこの時間間隔未満の範囲に複数存在する場合、 その中で類似度の値が最大のもののみをリストアップする。
The minimum time interval of the detection (s). If the similarity exceeds a threshold value twice or more in a time interval less than this value, only the time at which the similarity is maximal is listed. 		波形のサンプリングレートの整数倍かつ2倍以上、 パラメータfile_intervalの値の半分未満の実数。
A real number that is a multiple of the sampling rate of waveforms, greater than or equal to twice the sampling rate, and less than half the value of parameter file_interval. 		テンプレート波形の最大長さ。
The maximum length of template waveforms.


◆動作(Behaviour)

パラメータstartで指定した日時からendで指定した日時までの期間における、 パラメータfile_intervalで指定した時間間隔で区切られた SAC形式の時系列データファイル (パラメータinputfilesで指定したファイル名パターンを持つもの) を順次読み込み、 これらを連続した時系列データと見なして時間窓を連続的にずらしながら パラメータtemplatesで指定したテンプレートの時系列データとの類似度 (パラメータsimilarityで定義)を計算する。 類似度が閾値(パラメータthresholdで定義)を超えた時刻を パラメータoutputfileで指定したファイルに出力する。
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. Regard them as a continuoues time series data and compute the similarity (defined by parameter similarity) between these waveforms and the template waveforms specified by parameter templates in a continuously moving window. Output the times when the similarity exceeds a threshold value (defined by parameter threshold) into a file specified by parameter outputfile.

◆使用例(Example)

sacfiles_matchedFilter --inputfiles=data/%STATION.%COMPONENT/%YYYY-%MM-%DD.sac --templates=templates/%STATION.%COMPONENT.sac --outputfile=eventList.dat --start=2024-01-01.00-00-00 --end=2025-02-15.23-59-59 --trace_list_file=traces.conf --threshold=0.8

(traces.conf)
STN1[TAB]U
STN2[TAB]U
STN3[TAB]U

ここでSTN1, STN2, STN3は観測点コード、Uは成分コードであり、 [TAB]はタブを表す。
Here, STN1, STN2, and STN3 are station codes, U is a component code, and [TAB] represents a tab.

◆使用上の注意(Note)

テンプレートファイルはSAC形式の時系列データファイルで与える。 1つの観測点・成分につき1つのファイル(すなわち1つのイベント波形)とする。 複数のイベント波形をテンプレートにしたい場合は 各イベント毎にこのコマンドを繰り返し実行する。
Each template file must be a time series data file of SAC format. Only one template file (i.e., a file for one event) can be used for each station and component. To use multiple events as the templates, repeat this command for each event.
全ての観測点・成分についてサンプリングレートは共通でなければならない。 またテンプレート波形の基準日時 (SACヘッダのNZYEAR, NZJDAY, NZHOUR, NZMIN, NZSEC, NZMSEC) も全ての観測点・成分で共通でなければならない。 観測点・成分毎に異なる時刻範囲をテンプレートとするには SACヘッダのB, E, NPTSで各テンプレートファイルの時刻範囲を調整する。
The sampling rate must be common among all stations and components. In addition, the reference date and time (SAC headers NZYEAR, NZJDAY, NZHOUR, NZMIN, NZSEC, and NZMSEC) of the template files must be common among all stations and components. To use different time windows for different stations and components, use different values of SAC headers B, E, and NPTS.
正しい例(Correct example)
ファイル
File 		基準日時
Reference date and time 		データの時刻範囲(s)
Time window (s) of the data
templates/STN1.U.sac 2025/01/23 04:56:00 \([-10,10]\)
templates/STN2.U.sac 2025/01/23 04:56:00 \([-8,12]\)
templates/STN3.U.sac 2025/01/23 04:56:00 \([-15,5]\)

誤った例(Wrong example)
ファイル
File 		基準日時
Reference date and time 		データの時刻範囲(s)
Time window (s) of the data
templates/STN1.U.sac 2025/01/23 04:55:50 \([0,20]\)
templates/STN2.U.sac 2025/01/23 04:55:52 \([0,20]\)
templates/STN3.U.sac 2025/01/23 04:55:45 \([0,20]\)

出力波形における日時はテンプレート波形の基準日時がベースとなる。 例えば上記の例において2025/02/01 01:23:45が検知された場合、 その意味は2025/02/01の01:23:35-01:23:55におけるSTN1.U、 01:23:37-01:23:57におけるSTN2.U、 01:23:30-01:23:50におけるSTN3.U がテンプレート波形との類似度が高いということである。
The dates and times in the output file are based on the reference date and time of the template waveforms. For example, if an event was detected at 01:23:45 on February 1, 2025, in the example above, it means that the waveforms are highly similar to the templates in 01:23:35-01:23:55 on this day for STN1.U, 01:23:37-01:23:57 for STN2.U, and 01:23:30-01:23:50 for STN3.U.