ymaeda_opentools マニュアル

(The documentation of ymaeda_opentools)
version 2024-03-08a

目次(Table of contents)


1. 概要 (Overview)

ymaeda_opentoolsは地震学・火山学分野のデータ解析を念頭に置いて著者が開発した オープンソースのソフトウェアパッケージである。 C言語で書かれており、LinuxまたはMacのコンピュータにおいて動かすことができる。
An open-source software package, ymaeda_opentools, was developed by the author for data analyses in seismology and volcanology. The source codes are written in C and can be implemented on Linux or Mac computers.
ymaeda_opentoolsには Zenodo のデジタルオブジェクト識別子(DOI)が付与され、 クリエイティブ・コモンズ・ライセンス (表示 4.0 国際; CC BY 4.0) のもとで提供される。
A digital object identifier (DOI) of Zenodo is assigned to ymaeda_opentools, and distributed under the creative commons license (Attribution 4.0 International; CC BY 4.0).
著者は自分用に開発したプログラムコードをymaeda_toolsの名前で一括管理し、 一部の研究者からのリクエストに応じて個別に提供してきた。 近年のオープンサイエンスの流れを踏まえ、 ymaeda_toolsの中から公開可能なものを選別したパッケージが ymaeda_opentoolsである。 今後のアップデートの中でプログラムの追加も予定している。 なおZenodoのDOIはバージョンごとに付与される。
The author has maintained program codes developed for myself under a single package of a name ymaeda_tools, which has been distributed personally to researchers upon requests. Taking into account the recent trend to open science, programs that can be opened were selected from ymaeda_tools to create ymaeda_opentools. Programs are planned to be added to ymaeda_opentools in future updates. The DOI of Zenodo differs by version.

2. システム要件 (System requirements)

ymaeda_opentoolsはC言語に標準的に組み込まれている機能のみを 用いてコーディングしているため、 大多数のLinuxディストリビューションおよびMac OSで 動かすことができると期待される。 著者が思いつく限り、以下がシステム要件である。
Because ymaeda_opentools is coded with only the standard built-in features of C language, it is expected to be available on most Linux distributions and Mac OS. As long as the author is aware of, below are the system requirements.

追記(Additional notes)
利用者からCygwinでコンパイルがうまく行かない旨の情報をいただいた。 著者においてもCygwinでの動作確認は行っていない。 Windowsでymaeda_opentoolsを使用するには
  1. WindowsにOracle VM Virtual BoxなどのOS仮想化ソフトウェアをインストールする
  2. そのソフトウェア内でLinux OSをインストールする
  3. そのLinux OS内でymaeda_opentoolsをインストールする
という方法を推奨する。
According to information from a user, the compilation of the program fails in Cygwin environment. The author does not check ymaeda_opentools in Cygwin; an alternative way for Windows users is to first install a virtual machine software (e.g., Oracle VM Virtual Box) in the Windows computer, then install a Linux OS in that software, and finally install ymaeda_opentools in that Linux environment.

3. ファイル構成 (File structure)

ymaeda_opentoolsは以下のファイル構成になっている。
The structure of files of ymaeda_opentools is as below.
  • README
  • include
  • share
  • version.txt
  • サブパッケージ1(Sub package 1)
    • Makefile
    • src
    • bin
    • …
  • サブパッケージ2(Sub package 2)
    • Makefile
    • src
    • bin
    • …
  • …

3-1. README

このマニュアルページへのリンクである。
A link to this documentation site.

3-2. include

全てのサブパッケージで共通に用いるヘッダファイルから成る。 これらのヘッダファイルでは 関数、マクロ、グローバル変数、構造体が定義されている。
This directory consists of header files used commonly by all the sub packages. In these header files, definitions of functions, macros, grobal variables, and structures are given.

3-3. share

全てのサブパッケージで共通に用いる設定ファイルとMakefileから成る。
This directory consists of configuration files and the Makefile used commonly by all the sub packages.
【注意】Makefileはこのディレクトリ内で実行しないこと。
 ATTENTION: Do not execute the Makefile in this directory.

3-4. version.txt

パッケージのバージョン番号が記載されている。
The version number of the package is written.

3-5. 各サブパッケージ内のファイル (Files in individual sub packages)


4. インストールと初期設定 (Installation and initial set up)

ymaeda_opentoolsのインストールと初期設定の手順は以下の通り。
Shown below are the steps to install and set up ymaeda_opentools.

4-1. 新規インストール (New installation)

  1. ダウンロードサイト(Zenodo) からファイル一式をダウンロードする。 これらは1つのtgzファイルにまとめてあり、 ファイル名はymaeda_opentools.バージョン番号.tar.gzになっている。
    Download the files of ymaeda_opentools from the download site (Zenodo). These are included in a single tgz file, with a name ymaeda_opentools.(version number).tar.gz.
  2. ダウンロードしたファイルを好みの場所に置き、解凍する。
    Place the downloaded file at a preferred location, and uncompress it.
    (例 / Example)
    mv ymaeda_opentools.2024-03-08a.tar.gz /usr/local/
    cd /usr/local
    tar xvfz ymaeda_opentools.2024-03-08a.tar.gz
    解凍するとtarコマンドを実行したディレクトリの下に ymaeda_opentoolsというサブディレクトリが作られる。
    By uncompressing, a subdirectory of a name ymaeda_opentools is created under the directory where the tar command was executed.
  3. ymaeda_opentoolsを使用するための環境設定。 前のステップで作成されたymaeda_opentoolsディレクトリの絶対パスを 環境変数YMAEDA_OPENTOOL_DIRとして設定し、 その下のshare/initall.bashrcまたはshare/initall.cshrcを 自動的に読み込むように設定する。
    Environmental settings to use ymaeda_opentools. Set an environmental variable YMAEDA_OPENTOOL_DIR that points to the absolute path of ymaeda_opentools directory created by the previous step, and configure a setting to automatically read share/initall.bashrc or share/initall.cshrc beneath the directory.
    bashユーザの場合 (For bash users)
    ~/.bashrcに以下の2行を追記する。 但し/usr/local/ymaeda_opentoolsは例であり、 前のステップで作成したディレクトリパスで読み替える。
    Add the following two lines to ~/.bashrc; however, /usr/local/ymaeda_opentools is just an example and replace with the directory path that was created in the previous step.
    export YMAEDA_OPENTOOL_DIR=/usr/local/ymaeda_opentools
    source $YMAEDA_OPENTOOL_DIR/share/initall.bashrc

    C-shellユーザの場合 (For C-shell users)
    ~/.cshrcに以下の2行を追記する。 但し/usr/local/ymaeda_opentoolsは例であり、 前のステップで作成したディレクトリパスで読み替える。
    Add the following two lines to ~/.cshrc; however, /usr/local/ymaeda_opentools is just an example and replace with the directory path that was created in the previous step.
    setenv YMAEDA_OPENTOOL_DIR /usr/local/ymaeda_opentools
    source $YMAEDA_OPENTOOL_DIR/share/initall.cshrc

    設定後は~/.bashrcまたは~/.cshrcを読み込み直すか、 または現在の端末を閉じて新たに端末を開く。
    After this setup, reload ~/.bashrc or ~/.cshrc, or close the current terminal and open a new terminal.
  4. ファイルのパーミッションの修正。 複数のユーザが使用するコンピュータや、 ユーザは1名であってもツールをroot権限でインストールする場合には ymaeda_opentoolsディレクトリ内の全ファイルについて 全てのユーザに読み込み権限(ファイル)、読み込み・実行権限(ディレクトリ) を与えることが望ましい。 これは以下のコマンドで実行できる。
    Modify permissions for files. If multiple users share your computer or you install the tool by root, permissions for all files in ymaeda_opentools directory should be modified such that all users can read all regular files and they can read and execure all subdirectories. This is achieved by the commands below.
    find $YMAEDA_OPENTOOL_DIR -type f -exec chmod go+r {} +
    find $YMAEDA_OPENTOOL_DIR -type d -exec chmod go+rx {} +
  5. デフォルトではプログラムからのメッセージは日本語で出力される。 英語で出力したい場合は $YMAEDA_OPENTOOL_DIR/include/macro.hの先頭にある 「#define ENGLISH_MODE」の部分のコメントアウトを外す。
    By default, messages from the programs are displayed in Japanese. To switch them to English, uncomment “#define ENGLISH_MODE” at the top of $YMAEDA_OPENTOOL_DIR/include/macro.h.
  6. 各プログラムのコンパイル。compile_all.shを実行する。 以下のオプションがある。 通常、ライトユーザは「./compile_all.sh」、 ヘビーユーザは「./compile_all.sh O3」を行えば良い。
    Compile all programs by executing compile_all.sh. The following options are available. Recommended options are “./compile_all.sh” for light users and “./compile_all.sh O3” for hevy users.
    特定のサブパッケージ内のプログラムのみをコンパイルしたい場合、 compile_all.shは使用せず、 各サブディレクトリに移動してその中で「make」を実行する。 この場合も上と同じオプションを用いることができる(例: 「make O3」)。
    To compile only the programs in a certain sub package, go to that subdirectory and execute “make” instead of running compile_all.sh. The “make” command accepts the same options as those for compile_all.sh (e.g., “make O3”).
    コンパイル時にエラーが発生した場合は 上記3の設定が正しく読み込まれているかを確認する。 特に、rootでコンパイルを行う場合には 上記3の設定をroot用にも行わなければならない点に留意する。
    If a compilation error occured, check that the configurations of the step 3 above are correctly in effect. Especially, when you compile the programs by root, make sure that the configurations of the step 3 are in effect for the root account.

4-2. 古いバージョンからの更新 (Update from an older version)

古いymaeda_opentoolsをディレクトリごと削除した上で 新規インストールのステップ1, 2, 4, 5, 6を実行する。
Remove old ymaeda_opentools directory, and then follow the steps 1, 2, 4, 5, and 6 of the new installation.
ymaeda_opentoolsは頻繁にバージョンアップを行っており、 最新版への更新時は上記のように古いディレクトリを丸ごと削除して 差し替える必要がある。 そのためymaeda_opentoolsディレクトリ内に自作のファイルを置くことは非推奨とする。
Note that placing your original files in ymaeda_opentools is discouraged. This is because the update of ymaeda_opentools is frequent and needs replacing the entire directory of the old version of the program to the newer version, as instructed above.

5. 独自のファイル形式 (Special file formats)

ymaeda_opentoolsでは 行列、時系列データ、スペクトル、2次元・3次元データを表現するための 様々な独自ファイル形式を定義して用いている。 それらを以下にリストアップする。 各ファイル形式の詳細はリンクをクリックして参照のこと。
In ymaeda_opentools, many special file formats are defined to represent matrices, time series data, spectra, and 2D and 3D data. These formats are listed below. For details of individual formats, click the links.

6. 個々のサブパッケージのマニュアル (Documentations of individual sub packages)

ymaeda_opentoolsのプログラムは 「4. インストールと初期設定」で述べた通りの手順で準備を行えば パス無しで実行できるようになっており、 プログラム名がそのまま端末から実行するコマンド名となる。 そのため本マニュアル全体を通して 「プログラム」と「コマンド」は同じ意味で用いている。
All the programs in ymaeda_opentools can be executed without paths, as long as the procedures described in “4. Installation and initial set up” is followed, and the name of each program is equal to the name of the command to be executed from a terminal. For this reason, “program” and “command” are used as the same meaning throughout this documentation.
類似の機能を持つプログラム(コマンド)ごとに別々のサブディレクトリにまとめてあり、 これらサブディレクトリ単位のプログラム群を「サブパッケージ」と呼ぶ。 ymaeda_opentoolsのサブパッケージ一覧を下表に示す。 各サブパッケージの詳細はリンクをクリックして参照のこと。 また、プログラム(コマンド)名による索引も下に用意している。
Programs (commands) in ymaeda_opentools are grouped based on their roles, and are stored in different sub directories; assemblies based on these sub directories are called “sub packages”. A list of sub packages of ymaeda_opentools is given in the table below. For details of individual sub packages, click the links. Also, an index based on the program (command) name is available below.
サブパッケージ名
Sub package Name 		説明
Description
3d_data 3次元データファイルに対して様々な処理を行うプログラム。
Programs to perform various processings for 3-D data files.
event_detection 長時間の時系列データ(地震波の連続波形など)を用いて その中に含まれるイベントを検知するプログラム。
Programs to detect events from a long time series data (e.g., a continuous seismic waveform).
general 一般的なデータ解析を行うプログラム。
Programs to perform general data analysis.
geography 地理関係の処理を行うプログラム。
Programs to perform processings for geography.
hypo 震源決定を行うプログラム。
Programs to determine hypocenters.
matrix 行列のファイルに対して様々な処理を行うプログラム。
Programs to perform various operations for matrix files.
opentws 地震波動場の数値シミュレーションを行うプログラム。
Programs to perform numerical simulations for seismic wavefield.
sac_data Seismic Analysis Code (SAC)のデータファイルに対して 様々な処理を行うプログラム。
Programs to perform various operations for data files of Seismic Analysis Code (SAC).
sequence 時系列データやスペクトルのファイルに対して様々な処理を行うプログラム。
Programs to perform various processings for time series and spectral data files.
structural_survey 地下構造の推定を行うプログラム。
Programs to estimate subsurface structures.
win_data WIN形式(日本の標準的な地震波形データフォーマット) のデータファイルに対して様々な処理を行うプログラム。
Programs to perform various operations for data files of WIN format, which is the Japanese standard format for seismic waveform data.
winv 地震ソースに関する波形インバージョンを行うプログラム。
Programs to perform waveform inversion for seismic sources.
xml Extensible Markup Language (XML)ファイルに対して 様々な処理を行うプログラム。
Programs to perform various operations for Extensible Markup Language (XML) files.
索引(アルファベット順) (An index in alphabetic order)

7. ymaeda_opentoolsの目的別ガイド (Guide of ymaeda_opentools by purposes)

この節ではymaeda_opentoolsを用いてどのようなことが出来るのか、 目的別に紹介します。
This section introduces what can be done by ymaeda_opentools based on purposes.

8. ヘッダファイルのマニュアル (Documentations of header files)

ymaeda_opentools内のサブパッケージでは 多数のC言語関数、マクロ、グローバル変数、構造体を使用する。 これらは全てのサブパッケージで共通に用いるものであり、 includeディレクトリの下に置いてある。 これらのヘッダファイルを用いれば ユーザはC言語を用いた独自プログラムの開発を より簡単に行うことができる。 ヘッダファイルのマニュアルは書き直し中のため現時点で非公開のものも多いが 下記のリンクから部分的に利用可能である。
Sub packages in ymaeda_opentools use many C language functions, macros, grobal variables, and structures. They are used commonly from all sub packages, and are placed in include directory. Using these header files, users can develop their original C programs more easily than without using the header files. The documentations of the header files are partially available from the links below, although many of them are still not publically available as they are under rewriting.

9. バージョン情報 (Version history)

ymaeda_opentoolsでは 公開日(YYYY-MM-DD形式)の後にa,b,…を付けたものが バージョン番号となる。 各バージョンでの更新履歴はリンクをクリックして参照のこと。
The version number of ymaeda_opentools is the published date (YYYY-MM-DD format) followed by a, b, …. Updates in individual versions are listed in the links below.


10. 著作権と利用条件 (Copyright and terms of use)


10-1. 著作権 (Copyright)

ymaeda_opentoolsには クリエイティブ・コモンズ・ライセンス (表示 4.0 国際; CC BY 4.0) を適用する。
ライセンスの内容を表示
The creative commons license (Attribution 4.0 International; CC BY 4.0) is applied to ymaeda_opentools.
Click here to show the license.


なお クリエイティブ・コモンズ・ライセンスが適用されるのは ymaeda_opentoolsのみであり、 ymaeda_tools (研究者からのリクエストに応じて著者が個人的に提供してきたパッケージ) には適用されない点に留意。 ymaeda_toolsの再配布は禁止とする。
Note that the creative commons license applies only to ymaeda_opentools and does NOT apply to ymaeda_tools that have been distributed personally to researchers upon requests. Redistribution of ymaeda_tools is forbidden.

10-2. 引用について (Citation)

ymaeda_opentoolsを利用した研究成果の公表時は下記の論文またはDOIを引用のこと。
The following article or DOI needs to be cited when a research that used ymaeda_opentools is published.
使用したプログラム(コマンド)
Program (command) used 		含めるべき引用
Citations to be included
calculate_crack_frequency Maeda Y, Kumagai H (2017) A generalized equation for the resonance frequencies of a fluid-filled crack, Geophys J Int 209(1), 192-201. https://doi.org/10.1093/gji/ggx019
detect_inflation Maeda Y (2023) A systematic survey for precursory tilt changes at all monitored eruptions in Japan, J Volcanol Geotherm Res, 439, 107831. https://doi.org/10.1016/j.jvolgeores.2023.107831
detect_inflation_preeruptive2 Maeda Y (2023) A systematic survey for precursory tilt changes at all monitored eruptions in Japan, J Volcanol Geotherm Res, 439, 107831. https://doi.org/10.1016/j.jvolgeores.2023.107831
detect_VLP Kazahaya R, Maeda Y, Mori T, Shinohara H, Takeo M (2015) Changes to the volcanic outgassing mechanism and very-long-period seismicity from 2007 to 2011 at Mt. Asama, Japan, Earth Planet Sci Lett 418, 1-10. https://doi.org/10.1016/j.epsl.2015.02.034
reflection_response_event Maeda Y, Watanabe T (2022) Estimating errors in autocorrelation functions for reliable investigations of reflection profiles, Earth Planets Space 74, 48. https://doi.org/10.1186/s40623-022-01606-5
sacfile_get_signal_ratio Maeda Y, Yamanaka Y, Ito T, Horikawa S (2020) Machine learning based detection of volcano seismicity using the spatial pattern of amplitudes, Geophys J Int 225(1), 416-444. https://doi.org/10.1093/gji/ggaa593
waterPML
  • 計算に水域を含む場合
    (If your computation includes water-filled regions)
    Maeda Y, Kumagai H (2013) Effects of water domains on seismic wavefields: A simulation case study at Taal volcano, Philippines, Earth Planets Space 65(2), 85-96. https://doi.org/10.5047/eps.2012.07.004

  • 計算に水域を含まない場合
    (If your computation does not include water-filled regions)
    Maeda Y, Takeo M, Ohminato T (2011) A waveform inversion including tilt: method and simple tests, Geophys J Int 184(2), 907-918. https://doi.org/10.1111/j.1365-246X.2010.04892.x

上記以外
Other


10-3. その他の利用条件 (Other terms of use)


11. 著者 (The author)

前田 裕太 (まえだ ゆうた)
名古屋大学大学院環境学研究科附属地震火山研究センター
E-mail: maeda@seis.nagoya-u.ac.jp
個人ホームページ: https://www.seis.nagoya-u.ac.jp/~maeda/index.html
(2024年3月8日現在)

Yuta Maeda
Earthquake and Volcano Research Center, Graduate School of Environmental Studies, Nagoya University, Nagoya, Japan
E-mail: maeda@seis.nagoya-u.ac.jp
Personal website: https://www.seis.nagoya-u.ac.jp/~maeda/index.html
(on March 8, 2024)