sacfiles_irregular2regularコマンドマニュアル

(The documentation of sacfiles_irregular2regular command)

Last Update: 2025/1/31

◆機能・用途(Purpose)

不規則な時間区切りで分割されたSAC時系列データを規則的な時間区切りに再分割する。
Merge and re-divide irregularly divided SAC time series data into regular time sections.

このプログラムはminiSEED形式の地震波形データの処理を念頭に置いて作成したものである。 miniSEEDファイルはEarthScopeによって開発された mseed2sac という無償のプログラムを用いてSAC時系列データに変換できる。しかしながら、作成されるSAC時系列データは時間区切りが不規則であり、ファイル名には秒までしか含まれないが実際のデータの先頭時刻はミリ秒単位がノンゼロの場合がある等、そのままでは取り扱いにくい。そこで、mseed2sacによって作成されたSAC時系列データファイルを例えば1時間や1日などの規則的な時間区切りになるように再分割するのがこのプログラムの役割である。
This program was developed for processing seismic waveform data in miniSEED format. A miniSEED file can be converted to SAC time series data using a free software mseed2sac developed by EarthScope. However, the resultant SAC files are not convenient to treat because they are divided by irregular time sections, and the file names consists of time units down to a second while the actual beginning time of each file may consist of a non-zero value of mili-second unit. The purpose of this program is to merge and re-divide these SAC files, created by mseed2sac, into regular time sections (e.g., hourly or daily files).

mseed2sacによって出力されるSACファイルは観測点や成分などによって決まる共通の名前の後に「.YYYY.JJJ.hhmmss.SAC」を付けたファイル名となる。ここでYYYYは年、JJJはその年の先頭からの日数、 hhは時(2桁)、mmは分(2桁)、ssは秒(2桁)である。ファイル名は秒までしか含まないが、実際のデータの先頭時刻はミリ秒の単位がノンゼロの場合がある。このプログラムではこのような入力ファイルを想定している。
The names of the SAC files created by mseed2sac begins with a common name determined by station and component followed by “.YYYY.JJJ.hhmmss.SAC”, where YYYY is year, JJJ is the number of days from the beginning of the year, hh is hour (2-digits), mm is minute (2-digits), and ss is second (2-digits). Although the file name consists of time units as fine as 1 s, the actual beginning time of the data may have a non-zero value in the mili-second unit. This program assumes the input files that follow these rules.

◆ソースコード(Source code)

$YMAEDA_OPENTOOL_DIR/sac_data/src/sacfiles_irregular2regular.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 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)	省略不可 Cannot be omitted
outputfiles	出力するSACファイルの名前。通常は複数のファイルになるが、それらを列挙するのではなく、日時をパターンとして含む形で命名規則で与える。 The name of the output files (SAC format). Although multiple files are usually created, 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 data to process.	「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 data to process.	「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
output_file_interval	出力ファイルの時間区切りの長さ(s)。例えば1時間毎に分割されたファイルを出力する場合は3600となる。 The time length (s) of individual output files. For example, the value is 3600 if the output files should be divided every 1 hour.	正の整数。 A positive integer.	パラメータoutputfileに登場するパターン文字列の最小時間単位。例えばパラメータoutputfileに%hhまで登場するなら1時間刻み(3600)、 %mmまで登場するなら1分刻み(60)となる。 The minimum time unit of the pattern strings that appear in parameter outputfile. For example, if the parameter outputfile includes down to %hh then the interval is 1 hour (3600); if %mm is included then 1 min (60).
output_dt	出力する時系列データのサンプリング間隔(s)。 The sampling interval (s) of the output time series data.	0.001の倍数かつパラメータoutput_file_intervalの約数となる正の実数。 A positive real number that is a multiple of 0.001 and a divisor of the value of parameter output_file_interval.	最初の入力時系列データのサンプリング間隔。 The sampling interval of the first input time series data.

◆動作(Behaviour)

パラメータstartで指定した日時からendで指定した日時までの期間における、パラメータinputfilesで指定したファイル名パターンを持つ全てのSAC時系列データファイルを順次読み込み、パラメータstartで指定した日時が先頭かつ output_dtで指定した時間刻みがサンプリング間隔となるように線形補間とリサンプルを行い、パラメータoutput_file_intervalで指定した長さごとに再分割してパラメータoutputfilesで指定した名前のファイルに出力する。
Read all 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, linearly interpolate and resample the data at every output_dt starting at the date and time specified by parameter start, and output the results into files with names specified by parameter outputfiles that are divided by every section of the length specified by parameter output_file_interval.

◆使用例(Example)

例として、以下のSAC時系列データファイルが存在するとする。
Suppose that the SAC time series data files listed below are present.

ファイル名 File name	先頭日時 Start date and time	末尾日時 End date and time	サンプリング間隔 Sampling interval
data_original/NU.STN1..BHZ..2025.031.000123.SAC	2025/01/31 00:01:23.456	2025/02/01 00:12:34.566	0.01 s
data_original/NU.STN1..BHZ..2025.032.001234.SAC	2025/02/01 00:12:34.576	2025/02/02 00:03:04.056	0.01 s
data_original/NU.STN1..BHZ..2025.033.000305.SAC	2025/02/02 00:03:05.876	2025/02/03 00:06:54.656	0.02 s

以下のコマンドを実行する。
Execute the command below.

sacfiles_irregular2regular --inputfiles=data_original/NU.STN1..BHZ..%YYYY.%.JJJ.%hh%mm%ss.SAC --outputfiles=data_regular/NU.STN1.%YYYY-%MM-%DD.sac --start=2025-01-31.00-00-00 --end=2025-02-03.23-59-59

これにより、以下のファイルが作成される。
This command creates the files listed below.

ファイル名 File name	先頭日時 Start date and time	末尾日時 End date and time	サンプリング間隔 Sampling interval
data_regular/NU.STN1.2025-01-31.sac	2025/01/31 00:00:00.000	2025/01/31 23:59:59.990	0.01 s
data_regular/NU.STN1.2025-02-01.sac	2025/02/01 00:00:00.000	2025/02/01 23:59:59.990	0.01 s
data_regular/NU.STN1.2025-02-02.sac	2025/02/02 00:00:00.000	2025/02/02 23:59:59.990	0.01 s
data_regular/NU.STN1.2025-02-03.sac	2025/02/03 00:00:00.000	2025/02/03 23:59:59.990	0.01 s

この例ではパラメータoutput_file_intervalを指定していないのでパラメータoutputfilesに登場する最小の時間単位(%DD)に対応する 1日区切りのファイルが作成される。
In this example, parameter output_file_interval is not specified. Therefore, the output files are divided by 1 day, according to the smallest time unit (%DD) in the value of parameter outputfiles.
パラメータoutput_dtを指定していないので最初の入力ファイル(data_original/NU.STN1..BHZ..2025.031.000123.SAC) のサンプリング間隔である0.01 sが用いられる。
Parameter output_dt is not specified. Therefore, the sampling interval of the first input file (data_original/NU.STN1..BHZ..2025.031.000123.SAC; 0.01 s) is used.
入力データの先頭は2025/01/31 00:01:23.456であるが、出力データの先頭はパラメータstartの値である2025/01/31 00:00:00.000となる。その直前のサンプルである2025/01/30 23:59:59:990での値が0.0であるものとして、最初のデータサンプル(2025/01/31 00:01:23.456)との間を線形補間した値が出力される。
Although the input data begins at 00:01:23.456 on Jan 31, 2025, the output data begins at 00:00:00.000 on Jan 31, 2025, based on the value of parameter start. The output data before the first input data are determined by linear interpolation of a virtual data of 0.0 at the time sample immediately before the beginning (23:59:59.990 on Jan 30, 2025) and the first input sample at 00:01:23.456 on Jan 31, 2025.
入力データはミリ秒単位が006, 016, 026, …での値が与えられているが、出力データにおいてはこれらを線形補間してミリ秒単位が000, 010, 020, …での値が計算・出力される。
Although the input data are given at times with the mili-second unit of 006, 016, 026, …, they are linearly interpolated at times with the mili-second unit of 000, 010, 020, …, in the output data.
入力データにおいては2025/02/02 00:03:04.056と 2025/02/02 00:03:05.876の間に抜けがあり、また2025/02/02 00:03:05.876から0.02 sサンプリングに変更されるが、これらも線形補間によって処理される。
The data gap between 2025/02/02 00:03:04.056 and 2025/02/02 00:03:05.876 and the change in the sampling interval after 2025/02/02 00:03:05.876 are also processed by linear interpolation.

sacfiles_irregular2regularコマンド マニュアル