The documentation of “sequence/structure.h”

sequence/structure.h マニュアル

(The documentation of sequence/structure.h)

Last Update: 2025/7/24

sequence/structure.hでは sequenceヘッダファイルパッケージで主に用いる構造体が定義されている。各構造体の定義を以下に示す。
Structures mainly used in sequence header file package are defined in sequence/structure.h. Definitions of individual structures are shown below.

◆目次(Table of contents)

struct sequence型構造体 (a struct sequence-type structure)
struct imsequence型構造体 (a struct imsequence-type structure)
struct imsequence2型構造体 (a struct imsequence2-type structure)
struct signal_ratio_data型構造体 (a struct signal_ratio_data-type structure)

◆struct sequence型構造体 (A struct sequence-type structure)

時系列データを表現するための構造体である。以下のメンバから成る。
A structure to represent a time series data. This structure is composed of the following members.

型 Type	メンバ名 Name of member	メンバの意味 Meaning of member
int	size	データサンプル数。 The number of data samples.
double	t0	最初のサンプルの時刻。 The time of the first sample.
double	dt	データサンプルの時間刻み。 The time step of the data samples.
double	tmax	最後のサンプルの時刻。 The time of the last sample.
double	length	データのウインドウ長。 The window length of the data.
double ∗	value	各時刻での値を並べた配列。 An array composed of the values at individual sample times.
char	checked[1]	構造体が正しい構造になっていることをチェック済みか否かを示すフラグ。正しい構造とは例えばデータ点数が正である、メンバvalueが配列として動的メモリが確保されている(NULLではない)、など構造体が時系列データを表すと見なせるように各メンバの値が適切に設定されていることを指す。チェック済みの場合: checked[0]=′y′ 未チェックの場合: checked[0]=′n′ である。 1文字だけであるが関数内での値の変更が関数外にも反映されるように、またNULLにならないように固定長配列としている。 A flag indicating whether the structure has been checked that the members are properly set to represent a time series data; for example, whether the number of data points is positive, and whether the dynamic memory has been allocated for member value (i.e., it is not NULL). The value of this member is: checked[0]=′y′ if the structure has been checked, checked[0]=′n′ otherwise. Although this is a single character, a fixed size array is used to reflect changes of the value in a function to outside of it, and to avoid NULL.
struct humanTime	startDateTime	データの先頭日時。絶対時刻を用いない場合は未設定でも良い。 The beginning time of the data; setting this member can be skipped if the absolute time is not used.

◆struct imsequence型構造体 (A struct imsequence-type structure)

フーリエスペクトルや複素数値の時系列データを表現するための構造体である。以下のメンバからなる。
A structure to represent a Fourier spectrum and a time series data of complex numbers. This structure is composed of the following members.

型 Type	メンバ名 Name of member	メンバの意味 Meaning of member
int	size	データサンプル数。 The number of data samples.
double	t0	最初のサンプルの周波数(あるいは時刻)。できるだけstruct sequence型構造体と同じ構造になるようにあえてf0ではなくt0という名前にしている。 The frequency (or time) of the first sample. The name t0 is used, not f0, to make the format as similar as that of a struct sequence-type structure.
double	dt	データサンプルの周波数(あるいは時間)刻み。 The frequency (or time) step of the data samples.
double	tmax	最後のサンプルの周波数(あるいは時刻)。 The frequency (or time) of the last sample.
double	length	データのウインドウ長。 The window length of the data.
struct im ∗	value	各周波数(あるいは時刻)での値を並べた配列。 An array composed of the values at individual sample frequencies (or times).
char	checked[1]	構造体が正しい構造になっていることをチェック済みか否かを示すフラグ。チェック済みの場合: checked[0]=′y′ 未チェックの場合: checked[0]=′n′ である。詳しくはstruct sequence型構造体の説明参照。 A flag indicating whether the structure has been checked. The value of this member is: checked[0]=′y′ if the structure has been checked, checked[0]=′n′ otherwise. For more detail, see the description of a struct sequence-type structure.

◆struct imsequence2型構造体 (A struct imsequence2-type structure)

フーリエスペクトルや複素数値の時系列データを表現するための構造体(改良版)である。以下のメンバからなる。
A structure (improved version) to represent a Fourier spectrum and a time series data of complex numbers. This structure is composed of the following members.

型 Type	メンバ名 Name of member	メンバの意味 Meaning of member
int	size	データサンプル数。 The number of data samples.
double	t0	最初のサンプルの周波数(あるいは時刻)。できるだけstruct sequence型構造体と同じ構造になるようにあえてf0ではなくt0という名前にしている。 The frequency (or time) of the first sample. The name t0 is used, not f0, to make the format as similar as that of a struct sequence-type structure.
double	dt	データサンプルの周波数(あるいは時間)刻み。 The frequency (or time) step of the data samples.
double	tmax	最後のサンプルの周波数(あるいは時刻)。 The frequency (or time) of the last sample.
double	length	データのウインドウ長。 The window length of the data.
double complex ∗	value	各周波数(あるいは時刻)での値を並べた配列。 An array composed of the values at individual sample frequencies (or times).
char	checked[1]	構造体が正しい構造になっていることをチェック済みか否かを示すフラグ。チェック済みの場合: checked[0]=′y′ 未チェックの場合: checked[0]=′n′ である。詳しくはstruct sequence型構造体の説明参照。 A flag indicating whether the structure has been checked. The value of this member is: checked[0]=′y′ if the structure has been checked, checked[0]=′n′ otherwise. For more detail, see the description of a struct sequence-type structure.

◆struct signal_ratio_data型構造体 (A struct signal_ratio_data-type structure)

Maeda et al. (2020) のアルゴリズムに基づいて計算した大振幅比率の計算結果や中間データを表現するための構造体である。
A structure to represent the final results and intermediate data of the computation of large amplitude ratios based on the algorithm proposed by Maeda et al. (2020).

Maeda et al. (2020)では2つの異なる長さの移動時間窓を用いて大振幅比率を計算する。 1つ目はバックグラウンドノイズレベルの評価に用いる長い時間窓であり、 Maeda et al. (2020)では長さを\(\bar{T}\)と表記し、その値は5分とした。 2つ目はバックグラウンドノイズレベルを上回るサンプルの個数や登場割合(大振幅比率)の計算に用いる短い時間窓であり、 Maeda et al. (2020)では長さを\(T\)と表記し、その値は1秒とした。本マニュアルではこれらを「長時間窓」「短時間窓」と表記する。
Maeda et al. (2020) used moving time windows with two different lengths to compute large amplitude ratios. One was a long window used to evaluate the background noise levels; Maeda et al. (2020) expressed the length of this window as \(\bar{T}\) and used 5 min for it. The other was a short window used to calculate the numbers and ratios (large amplitude ratios) of samples whose values were greater than the background noise level; Maeda et al. (2020) expressed the length of this window as \(T\) and used 1 s for it. These windows are expressed as long and short windows in this documentation, respectively.

時間窓はオーバーラップさせない。すなわち長時間窓は\(\bar{T}\)ずつずらし、短時間窓は\(T\)ずつずらす。このようにしている理由はバックグラウンドノイズレベルの計算に時間がかかるためである。例えばMaeda et al. (2020)の\(\bar{T}\)(5分)と\(T\)(1秒)を用いた場合、もし短時間窓を動かすたびに(1秒毎に) 長時間窓も動かしてバックグラウンドノイズレベルを計算し直したら 1秒分の計算に1秒よりも長い時間がかかってしまう。それを避けるため、バックグラウンドノイズレベルは5分に1度だけ計算し、 5分間はバックグラウンドノイズレベルが変化しないものとして1秒毎の大振幅比率を求める。
That the windows are not overlapped; the long window is moved by \(\bar{T}\) and the short window is moved by \(T\). This approach is adopted to reduce computation time for the calculation of the background noise level. For example, suppose that 5 min and 1 s are used for \(\bar{T}\) and \(T\), respectively (Maeda et al. 2020). If the background noise level is re-computed by updating the long window for every 1 s when the short window is moved, then the total computation time for 1-s data is longer than 1 s. To avoid this situation, the background noise level is computed every 5 min, and the large amplitude ratio in each 1 s is computed assuming that the background noise level does not change during the 5 min.

バックグラウンドノイズレベルの評価は以下の考え方で行う。長時間窓のサンプルのうち絶対値振幅が小さい順に\(N’\)個が正規分布に従うランダムノイズであると仮定する。このときバックグラウンドノイズの振幅\(v\)の確率分布は \[\begin{equation} G(v;N’) =\frac{1}{\sqrt{2\pi}\sigma(N’)} \exp\left[-\frac{v^2}{2\sigma(N’)^2}\right] \label{eq.G} \end{equation}\] と書ける。ここで正規分布の平均値は0であると仮定し、標準偏差はデータの絶対値振幅が小さい順に \(N’\)個の振幅値\(\{v_n; n=0,1,\cdots,N’-1\}\)を用いて \[\begin{equation} \sigma(N’)=\sqrt{\frac{1}{N’}\sum_{n=0}^{N’-1}v_n^2} \label{eq.sigma} \end{equation}\] と計算されるものとする。 (\ref{eq.G})式に基づく絶対値振幅の累積確率分布は \[\begin{equation} \Pi(|v|;N’)=erf\left[\frac{|v|}{\sqrt{2}\sigma(N’)}\right] \label{eq.Pi} \end{equation}\] と書ける。一方、実際のデータに基づく絶対値振幅の累積確率分布は \[\begin{equation} \Theta(|v_n|;N’)=\frac{n}{N’-1} \label{eq.Theta} \end{equation}\] であり、この\(\Pi\)と\(\Theta\)のずれ具合を最小にする\(N’\)に対応する絶対値振幅\(|v_{N’-1}|\)がバックグラウンドノイズレベルの推定値である。
The outline of the evaluation method of the background noise level is as follows. Suppose that the smallest \(N’\) samples in a long window on the basis of absolute amplitudes are caused by a random noise that obeys a normal distribution. Then, the probability distribution of the amplitude \(v\) of the background noise is expressed by Eq. (\ref{eq.G}), where the average of the normal distribution is assumed to be zero and the standard deviation is assumed to be computed from the smallest \(N’\) absolute amplitudes of the data \(\{v_n; n=0,1,\cdots,N’-1\}\) using Eq. (\ref{eq.sigma}). From Eq. (\ref{eq.G}), the cumulative probability distribution of absolute amplitudes is calculated as Eq. (\ref{eq.Pi}), while the cumulative probability distribution from the actual data is given by Eq. (\ref{eq.Theta}). A search for the optimal \(N’\) that minimizes the misfit between \(\Pi\) and \(\Theta\) gives an estimate of a background noise level \(|v_{N’-1}|\).

Maeda et al. (2020)では\(N’\)が小さい場合にも計算結果が安定するようにもうひと工夫加えた。以下がそのアルゴリズムである。
Maeda et al. (2020) used an additional technical contrivance to stabilize the computation results for small \(N’\), as follows.

長時間窓のサンプルのうち偶数番目の時刻のもののみに注目し、その中で絶対値振幅が小さい順に\(N’/2\)個を取り出して (\ref{eq.G})-(\ref{eq.Theta})式と同様に
- 正規分布\(G^{even}(v;N’/2)\)
- その標準偏差\(\sigma^{even}(N’/2)\)
- 正規分布の仮定に基づく累積確率分布\(\Pi^{even}(|v|;N’/2)\)
- 実際のデータに基づく累積確率分布\(\Theta^{even}(|v_n|;N’/2)\)
を計算する。
Use only the data at even-numbered time samples in a long window. From them, extract the smallest \(N’/2\) samples on the basis of absolute amplitudes, and then compute the following quantities in the same manner as Eqs. (\ref{eq.G})-(\ref{eq.Theta}):
- a normal distribution \(G^{even}(v;N’/2)\),
- its standard deviation \(\sigma^{even}(N’/2)\),
- the cumulative probability distribution from the normal distribution \(\Pi^{even}(|v|;N’/2)\), and
- the cumulative probability distribution of the actual data \(\Theta^{even}(|v_n|;N’/2)\).
同様に奇数番目の時刻のデータを用いて \(G^{odd}(v;N’/2)\), \(\sigma^{odd}(N’/2)\), \(\Pi^{odd}(|v|;N’/2)\), \(\Theta^{odd}(|v_n|;N’/2)\) を計算する。
In the same way, use only the data at odd-numbered time samples to compute \(G^{odd}(v;N’/2)\), \(\sigma^{odd}(N’/2)\), \(\Pi^{odd}(|v|;N’/2)\), and \(\Theta^{odd}(|v_n|;N’/2)\).
その上で
- \(\Theta^{even}\)と\(\Pi^{odd}\)のずれ具合\(\mu^{eo}(N’/2)\)
- \(\Theta^{odd}\)と\(\Pi^{even}\)のずれ具合\(\mu^{oe}(N’/2)\)
を計算し、そのうちの大きい方の値\(\mu(N’/2)\)をこの\(N’\)におけるずれ具合として採用する。これにより、\(N’\)が小さい場合に \(\Theta\)と\(\Pi\)が偶然近くなることによる最適な\(N’\)の過小評価を回避できると期待される。
Finally, the following two quantities are computed:
- the misfit \(\mu^{eo}(N’/2)\) between \(\Theta^{even}\) and \(\Pi^{odd}\), and
- the misfit \(\mu^{oe}(N’/2)\) between \(\Theta^{odd}\) and \(\Pi^{even}\).
Taking the larger one of them, denoted as \(\mu(N’/2)\), as the misfit at \(N’\). By this method, a scenario of adventitious good fit between \(\Theta\) and \(\Pi\) and the resultant under-estimation of the optimal \(N’\) is expected to be avoided.

バックグラウンドノイズレベルが得られたら、各短時間窓において絶対値振幅がバックグラウンドノイズレベルを上回るサンプル数をカウントし、それを短時間窓内の総サンプル数で割ることで大振幅比率を求める。
Once the background noise level is obtained, count the number of samples with absolute amplitudes greater than the background noise level in each short time window, and divide it by the total number of samples in the short time window to compute a large amplitude ratio.

この構造体は上記のアルゴリズムによって得られる大振幅比率の時系列データやその計算の途中過程で得られる量を保存するための構造体であり、以下のメンバから成る。
This structure is deviced to express a time series data of large amplitude ratios computed by the algorithm explained above and intermediate quantities that are obtained during the computation. The structure is composed of the following members.

型 Type	メンバ名 Name of member	メンバの意味 Meaning of member
int	Nlong_windows	長時間窓の個数。 The number of long windows.
int	Nshort_windows	短時間窓の個数。 The number of short windows.
int	Nsamples_in_long_window	1つの長時間窓に含まれる時刻サンプルの個数。 The number of time samples in a long window.
int	Nsamples_in_short_window	1つの短時間窓に含まれる時刻サンプルの個数。 The number of time samples in a short window.
int	Nshort_windows_in_long_window	1つの長時間窓に含まれる短時間窓の個数。 The number of short windows in a long window.
double ∗	tmin_long	長時間窓の先頭時刻を全ての長時間窓について並べた配列。 An array composed of the beginning time of every long window.
double ∗	tmax_long	長時間窓の末尾時刻を全ての長時間窓について並べた配列。 An array composed of the end time of every long window.
struct sequence	ave	長時間窓内のサンプルの振幅の平均値を全ての長時間窓について並べた時系列データ。時刻は時間窓の先頭時刻を用いる。 A time series data composed of the average amplitude of the samples in every long time window. The beginning time of each window is used for the time.
struct sequence ∗	waveform_in_window	長時間窓内の絶対値時系列データを全ての長時間窓について並べた配列。絶対値を取る前に長時間窓内の平均値を差し引く場合がある(ユーザの指定による)。 An array composed of the absolute-valued time series data in every long window. The average in each long window may have been subtracted before taking the absolute values (depending on the user's usage).
int ∗∗	order	メンバwaveform_in_windowのサンプルを昇順に並べるための配列要素の並び順を表す2次元配列。各長時間窓ilについて、 waveform_in_window[il].value[order[il][m]] がmに関して昇順となるように定義される。 A 2-D array that represents the order of array components to sort the samples of member waveform_in_window into an ascending order; it is defined to make waveform_in_window[il].value[order[il][m]] an ascending order with respect to m for each long window il.
double ∗∗	sigma_even	\(\sigma^{even}(N’/2)\)の値を全ての長時間窓、全ての\(N’/2\)について並べた2次元配列。 A 2-D array composed of the values of \(\sigma^{even}(N’/2)\) for all long windows and all trial values of \(N’/2\).
double ∗∗	sigma_odd	\(\sigma^{odd}(N’/2)\)の値を全ての長時間窓、全ての\(N’/2\)について並べた2次元配列。 A 2-D array composed of the values of \(\sigma^{odd}(N’/2)\) for all long windows and all trial values of \(N’/2\).
double ∗∗	mu_eo	\(\mu^{eo}(N’/2)\)の値を全ての長時間窓、全ての\(N’/2\)について並べた2次元配列。 A 2-D array composed of the values of \(\mu^{eo}(N’/2)\) for all long windows and all trial values of \(N’/2\).
double ∗∗	mu_oe	\(\mu^{oe}(N’/2)\)の値を全ての長時間窓、全ての\(N’/2\)について並べた2次元配列。 A 2-D array composed of the values of \(\mu^{oe}(N’/2)\) for all long windows and all trial values of \(N’/2\).
double ∗∗	mu	\(\mu(N’/2)\)の値を全ての長時間窓、全ての\(N’/2\)について並べた2次元配列。 A 2-D array composed of the values of \(\mu(N’/2)\) for all long windows and all trial values of \(N’/2\).
int ∗	best_Ndash	推定した最適な\(N’\)の値を全ての長時間窓について並べた配列。 An array composed of the estimated optimal value of \(N’\) for every long window.
struct sequence	noise_stddev	最適な\(N’\)を用いたときの (\ref{eq.sigma})式に基づく\(\sigma(N’)\)の値を全ての長時間窓について並べた時系列データ。時刻は時間窓の先頭時刻を用いる。 A time series data composed of the value of \(\sigma(N’)\) (Eq. \ref{eq.sigma}) for the optimal \(N’\) in every long window. The beginning time of each window is used for the time.
struct sequence	noise_level	推定したバックグラウンドノイズレベル\(\|v_{N’-1}\|\)を全ての長時間窓について並べた時系列データ。時刻は時間窓の先頭時刻を用いる。 A time series data composed of the estimated background noise level \(\|v_{N’-1}\|\) in every long window. The beginning time of each window is used for the time.
int ∗∗	Nsignal_samples	絶対値振幅がバックグラウンドノイズレベルを上回るサンプル数を全ての短時間窓について並べた2次元配列。第1引数は長時間窓の番号を表し、第2引数は同じ長時間窓に含まれる短時間窓の番号を表す。 A 2-D array composed of the number of samples with absolute amplitudes greater than the background noise level in every short window. The 1st argument of the 2-D array represents an index of a long window, and the 2nd argument represents an index of a short window in the same long window.
struct sequence	signal_ratio	大振幅比率を全ての短時間窓について並べた時系列データ。時刻は時間窓の先頭時刻を用いる。 A time series data composed of large amplitude ratio in every short window. The beginning time of each window is used for the time.