関数wintosac マニュアル

(The documentation of function wintosac)

Last Update: 2025/6/13

◆機能・用途(Purpose)

WINデータをSeismic Analysis Code (SAC)形式に変換する。
Convert WIN data to Seismic Analysis Code (SAC) format.

◆形式(Format)

#include <win/convert.h>
inline struct sac_timeseq wintosac
(const int NsecondBlock,const struct win_secondBlock ∗winData,
const struct win_channelTable channelTable,
const int l,const int samplingRate)

◆引数(Arguments)

NsecondBlock	秒ブロックの個数。関数orderWinData に第2引数として渡して値を設定したものを渡すこと。関数win_countSecondBlock の戻り値をそのまま渡してはならない。 The number of second blocks. This value must be determined from the 2nd argument of function orderWinData, NOT from the return value of function win_countSecondBlock.
winData	関数win_eraseDifferentSamplingRateData を用いて作成したWINデータ(秒ブロックのデータを並べた配列)。秒ブロックが時刻順に並んでおり、欠損や重複が無く、チャンネルの登場順も全ての秒ブロックで共通であり、 1つのチャンネルの中でサンプリングレートが途中で変わらないという条件を満たしたデータを与える必要があるため、別の関数で得たWINデータを与えてはならない。 A WIN data (an array composed of the data of second blocks) created by function win_eraseDifferentSamplingRateData. Never give WIN data created by other functions because this data must satisfy the following requirements: the second blocks are sorted in time order without defects nor duplication, the order of channels is common among all second blocks, and the sampling rate of each channel does not change.
channelTable	チャンネルテーブルのデータ。関数sortWinData に第3引数として渡したものと同じデータを用いること。 A channel table data equivalent to what was used for the 3rd argument of function sortWinData.
l	SAC形式に変換したいチャンネルの番号。チャンネルコードではなく、引数channelTable(第3引数)のメンバcontentsの配列要素番号を与える。 An index of a channel to convert to SAC format; not a channel code but an array index of member contents of argument channelTable (3rd argument).
samplingRate	SAC形式に変換したいチャンネルの正しいサンプリングレート(Hz)。 The correct sampling rate (Hz) of the channel to convert to SAC format.

◆戻り値(Return value)

winDataのl番目のチャンネルを(秒ブロックをまたいで)つなげたsacデータ。メンバは以下の通り。
The sac data created from the “l”-th channel of “winData” over the second blocks, composed of the following members.

メンバ Member	値 Value
header	関数wintosac_set_header の戻り値。 The return value of function wintosac_set_header.
data.size	samplingRate∗NsecondBlock
data.t0	0.0
data.dt	1.0/samplingRate
各nに対するdata.value[n] data.value[n] for each n	データが存在する秒ブロックの先頭サンプル The first sample of a valid second block: winData[n].channelBlock[l].initialValue∗ channelTable.contents[l].scale データが存在する秒ブロックの先頭以外のサンプル The second and later samples of a valid second block: 前のサンプルでの値+ winData[n].channelBlock[l]. data_diff[i-n∗samplingRate-1]∗ channelTable.contents[l].scale The value of the previous sample plus winData[n].channelBlock[l]. data_diff[i-n∗samplingRate-1]∗ channelTable.contents[l].scale データが存在しない秒ブロック内の時刻 A time in a dummy second block: 直線による内挿値。直線は以下の条件を満たすように決定される。 An interpolated value by a straight line that satisfies the following requirements. 欠損区間の1つ前の時刻サンプルでの値 = 欠損区間の直前の秒ブロックにおける平均値 (欠損区間の前にデータが存在しない場合は0) The value at the time sample immediately before the beginning of the defect section equals to the average of data in the valid second block immediately before the defect section, or equals to 0 if there is no valid second block before the defect section. 欠損区間の1つ後の時刻サンプルでの値 = 欠損区間の直後の秒ブロックにおける平均値 (欠損区間の後にデータが存在しない場合は0) The value at the time sample immediately after the end of the defect section equals to the average of data in the valid second block immediately after the defect section, or equals to 0 if there is no valid second block after the defect section.

◆使用例(Example)

int NsecondBlock_before =win_countSecondBlock("data.win");

struct win_data winData_before =read_win_file("data.win");

struct win_channelCodeList channels =win_readChannelCode("channel_codes.txt");

struct win_channelTable channelTable_all =win_readChannelTable("channels.tbl");

struct win_channelTable channelTable_use =win_selectChannelTable(channelTable_all,channels);

sortWinData (NsecondBlock_before, winData_before, channelTable_use);

int NsecondBlock_before_after;

struct win_secondBlock winData_after =orderWinData (NsecondBlock_before, &NsecondBlock_after, winData_before);

win_eraseDifferentSamplingRateData (NsecondBlock_after, winData_after, channelTable_use);

wintosac (NsecondBlock_after, winData_after, channelTable_use, 2, winData_after[0]. channelBlock[2].samplingRate);

◆使用上の注意(Note)

この関数はチェック機能が十分でなく、正しく用いないと間違ったデータが何の警告も無しに生成されてしまう恐れがある。特に以下の点に留意して用いること。
This function does not carefully check the input data. Therefore, if this function is used with a wrong manner, the result may be wrong data without warning. To avoid this scenario, pay attention especially to the points below.

必ず
sortWinData
→orderWinData
→win_eraseDifferentSamplingRateData
→wintosac
の順に関数を呼び出すこと。この関数では秒ブロックが時刻順で欠損・重複無く並んでいること、チャンネルの登場順が全ての秒ブロックで共通であること、各チャンネルのサンプリングレートが途中で変化しないことを前提として処理が行われるため、その前提が成り立たないWINデータを第2引数に渡すと誤ったデータが生成される。
Functions must be called sequentially in the following order:
sortWinData
→orderWinData
→win_eraseDifferentSamplingRateData
→wintosac.
This is because this function assumes that the second blocks have been sorted in time order and have not defects nor duplication, the order of channels is common among all channel blocks, and the sampling rate is invariant in each channel. If the WIN data given to the 2nd argument does not meet these assumptions, the result will be wrong data.
更に、各秒ブロック内でのチャンネルの登場順は第3引数で与えたチャンネルテーブルのデータにおけるチャンネルの登場順と一致することが仮定される。この仮定が成り立つことを保証するため、第3引数には必ず関数sortWinData に第3引数として渡したものと同じチャンネルテーブルデータを用いること。
This function also assumes that the order of channels in each second block is equal to the order of channels in the channel table data given by the 3rd argument. To guarantee this assumption, make sure to use the same channel table data as what was used for the 3rd argument of function sortWinData.