関数read_sac_timeseq マニュアル

(The documentation of function read_sac_timeseq)

Last Update: 2024/7/31

◆機能・用途(Purpose)

等間隔サンプリングのSAC時系列データをファイルからstruct sac_timeseq型構造体に読み込む。
Read an evenly sampled SAC time series data from a file to a struct sac_timeseq-type structure.

◆形式(Format)

#include <sac/readwrite.h>
inline struct sac_timeseq read_sac_timeseq(const char ∗filename)

◆引数(Arguments)

filename

読み込むSAC時系列データファイル名。
The name of a SAC time series data file to read.

◆戻り値(Return value)

読み込んだ時系列データを表す構造体。メンバの値は以下のようになる。
A structure that represents the time series data from the file. The values of members are as follows.

メンバ Member	値 Value
header	関数read_sac_headerの戻り値。 The return value of function read_sac_header.
data.size	読み込んだSACヘッダNPTS(No. 079)の値。 The value of a SAC header NPTS (No. 079) from the file.
data.t0	読み込んだSACヘッダB(No. 005)の値。 The value of a SAC header B (No. 005) from the file.
data.dt	読み込んだSACヘッダDELTA(No. 000)の値。 The value of a SAC header DELTA (No. 000) from the file.
data.startDateTime	SAC時系列データの先頭日時。読み込んだSACヘッダNZYEAR(No. 070), NZJDAY(No. 071), NZHOUR(No. 072), NZMIN(No. 073), NZSEC(No. 074), NZMSEC(No. 075), B(No. 005)に基づいて計算される。これらのヘッダのいずれかが未定義の場合は2000/01/01 00:00:00となる。 The start date and time of the SAC time series data computed from the values of SAC headers NZYEAR (No. 070), NZJDAY (No. 071), NZHOUR (No. 072), NZMIN (No. 073), NZSEC (No. 074), NZMSEC (No. 075), and B(No. 005) from the file; if either of them is undefined, the value of this member is set as 00:00:00 on Jan 1, 2000.
data.value	読み込んだSAC時系列データの各時刻における値を時刻順に並べた配列。 An array composed of the values of the time series data at all time samples in order of time.

◆使用例(Example)

struct sac_timeseq data=read_sac_timeseq("data.sac");

◆補足(Additional notes)

SAC形式のデータファイルの中には等間隔サンプリングの時系列でないもの (フーリエスペクトルや等間隔でない時系列データなど)も存在するが、それらはこの関数では読み込めない。但し、フーリエスペクトルからkeepamコマンドで振幅のみを取り出したものは読み込める。実際の処理としては
- ファイルの種類を表すSACヘッダIFTYPE(No. 085)の値が itime(時系列データファイル)またはixy(一般的なx,yのファイル)である
- データが等間隔か否かを表すSACヘッダLEVEN(No. 105)の値がTRUEである
という2条件が満たされる場合にデータの読み込みが行われ、その他の場合はエラーとなる。
The SAC data file formats are not limited to evenly sampled time series data; Fourier spectra or time series data with irregular time samples can be expressed in SAC format. However, this function only reads an evenly sampled time series data by checking the following two requirements:
- the value of a SAC header IFTYPE (No. 085), which represents the file type, is either itime (a time series data file) or ixy (a general x-y file); and
- the value of a SAC header LEVEN (No. 105), which represents a distinction of whether the data are evenly sampled, is TRUE.
If the two requirements are not satisfied, the program finishes as an error.
SACヘッダのNPTS(データサンプル数)、B(データの先頭時刻)、DELTA(サンプリング間隔)のいずれかが未定義の場合はエラー終了する。
The program finishes as an error if one of the following SAC headers is undefined: NPTS (the number of data samples), B (the beginning time of the data), and DELTA (the sampling interval).
SACヘッダのIZTYPE(No. 087)の値がiunkn(不明)またはundefined(未定義)の場合、データの先頭が基準時刻であるものとして処理が行われる。
If the value of a SAC header IZTYPE (No. 087) is either iunkn (unknown) or undefined, the beginning time of the data is supposed to be the reference time.
SACヘッダのIFTYPE(No. 085)の値がitime(時系列データファイル)の場合、 SACヘッダDELTA(No. 000; サンプリング間隔)の値をミリ秒単位で四捨五入する。これはファイル内でDELTAが単精度で与えられているので精度が悪く、 DELTAの値をそのまま読み込むと長時間の時系列データにおいて1サンプル以上の時刻誤差が生じるからである。例としてB=0.00 (s)、DELTA=0.01 (s)のとき、データの先頭から4日(34560000サンプル)後の正しい時刻は345600.00 (s)である。ところが単精度実数ではDELTA=0.00999999977648258209229 (s)となり、このDELTAを用いるとデータの先頭から34560000サンプル後の時刻は345599.99 (s) と計算されてしまう。正しい時刻から1サンプルのずれを生じている。 SAC時系列データでは時間刻みの最小単位が1ミリ秒であるのでミリ秒単位で四捨五入することによって時刻誤差を低減できる。
If the value of a SAC header IFTYPE (No. 085) is itime (a time series data file), the value of a SAC header DELTA (No. 000; the sampling interval) is rounded at a mili-second order. This is because the value of DELTA is stored as a single precision real number in the file, which is not accurate enough and results in a 1-sample time difference between correct and calculated times in long time series data. For example, suppose that B = 0.00 (s) and DELTA = 0.01 (s). The correct time at the 4 days (34560000 samples) after the beginning time of this data is 345600.00 (s), whereas the time after the 34560000 samples calculated with a single precision DELTA (0.00999999977648258209229 (s)) is 345599.99 (s), giving a 1-sample time difference. Such errors in time can be reduced by rounding DELTA at a mili-second order; note that the minimum time unit of SAC time series data is 1 ms.
同様の理由でSACヘッダのIFTYPE(No. 085)の値がitime(時系列データファイル)の場合、 SACヘッダB(No. 005; 先頭時刻)の値についてもミリ秒単位で四捨五入する。そうしないとBがDELTAで割り切れない等の不都合が生じるからである。
For the same reason, if the value of a SAC header IFTYPE (No. 085) is itime (a time series data file), the value of a SAC header B (No. 005; the beginning time) is rounded at a mili-second order. By this, if the original B was a multiple of the original DELTA, the modified B will be a multiple of the modified DELTA.