= ライブラリとパッケージ =
<<TableOfContents>>

== はじめに: Pythonのバージョンについて ==
2026年現在、KAGRA/PEMの解析環境としては '''Python 3.11''' をベースにすることを強く推奨します。
最新の 3.12~14 は、一部の科学技術計算ライブラリ（特に古い計測機器制御や特殊な信号処理系）がまだ完全に対応していない場合があり、環境構築でトラブルの原因になりやすいためです。

== 用語の整理 ==
Pythonを触っているとよく出てくる用語について、簡単にまとめておきます。

 * '''関数 (Function)''': 何らかの入力（引数）を受け取り、処理を行って結果（戻り値）を返す命令の塊です。例: {{{y = sin(x)}}}
 * '''クラス (Class)''': データと、それを処理する関数をひとまとめにした設計図です。GWpyの {{{TimeSeries}}} もクラスの一種で、これを実体化（インスタンス化）して使います。
 * '''モジュール (Module)''': Pythonのコードが書かれた1つのファイル（{{{.py}}}ファイル）。{{{import math}}} のように読み込んで使います。
 * '''パッケージ (Package)''': 複数のモジュールをディレクトリ（フォルダ）にまとめて整理したもの。通常 {{{__init__.py}}} というファイルが含まれています。
 * '''ライブラリ (Library)''': 複数のパッケージやモジュールをまとめて、特定の機能（数値計算、グラフ描画など）を提供するための集合体。「インストールして使う便利道具箱」です。

== 環境構築・インストールの方法 ==
ライブラリのインストールには、主に '''Conda (Mamba)''' を使用します。
具体的なセットアップ方法やコマンドの使い方は、以下のページを参照してください。

 * [[KAGRA/Subgroups/PEM/Conda|Conda (Miniforge/Mamba) の使い方]]

== よく使う標準ライブラリ (インストール不要) ==
Pythonをインストールした時点で最初から入っているライブラリです。
これらは {{{mamba install}}} する必要はありませんが、解析スクリプト内で頻繁に {{{import}}} します。
(リンク先はPython公式ドキュメントです)

|| '''import時の名前''' || '''説明''' ||
|| [[https://docs.python.org/3/library/os.html|os]] || ファイルパスの操作、ディレクトリの作成などOS機能へのアクセス。 ||
|| [[https://docs.python.org/3/library/sys.html|sys]] || Pythonのシステム設定、パスの追加、スクリプトの引数処理など。 ||
|| [[https://docs.python.org/3/library/glob.html|glob]] || {{{glob.glob('*.gwf')}}} のように、ワイルドカードでファイルリストを取得する。 ||
|| [[https://docs.python.org/3/library/datetime.html|datetime]] || 日付や時刻の計算・変換。GPS時刻との変換時によく使う。 ||
|| [[https://docs.python.org/3/library/math.html|math]] || 基本的な数学関数（sin, cos, sqrtなど）。配列を扱わない単純計算用。 ||

== よく使う外部ライブラリ一覧 ==
KAGRA/PEMのデータ解析において「これだけは入れておくべき」というライブラリのリストです。
環境構築時にまとめてインストールしてしまいましょう。

'''注意''': インストールコマンドは、仮想環境（conda environment）に入った状態で実行してください。

=== 解析・グラフ描画の基礎 ===
科学技術計算の「三種の神器」＋αです。便利なユーティリティも含みます。

|| '''import時の名前''' || '''インストールコマンド''' || '''説明''' ||
|| [[https://numpy.org/|numpy]] || (gwpy等で自動インストール) || 数値計算の基礎。配列（ベクトル・行列）計算を高速に行う。必須。 ||
|| [[https://scipy.org/|scipy]] || (gwpy等で自動インストール) || 科学技術計算。信号処理（フィルタ、FFT）、最適化、統計など。必須。 ||
|| [[https://matplotlib.org/|matplotlib]] || (gwpy等で自動インストール) || グラフ描画のデファクトスタンダード。必須。 ||
|| [[https://pandas.pydata.org/|pandas]] || (geopandas等で自動インストール) || 表形式データの処理。CSVの読み書きや時系列データの整理に便利。 ||
|| [[https://corner.readthedocs.io/|corner]] || {{{mamba install -c conda-forge corner}}} || パラメータ推定(MCMC等)の結果から、多次元の相関を示すコーナープロットを簡単に作成するツール。 ||
|| [[https://natsort.readthedocs.io/|natsort]] || {{{mamba install -c conda-forge natsort}}} || 自然順ソート（file1, file2, ... file10 の順に並べる）に使う。 ||
|| [[https://pypi.org/project/chardet/|chardet]] || {{{mamba install -c conda-forge chardet}}} || 文字コード判定。日本語を含む古いCSVなどを読み込む際のトラブルシューティングに。 ||
|| [[https://bottleneck.readthedocs.io/|bottleneck]] || {{{mamba install -c conda-forge bottleneck}}} || 移動平均などのスライディングウィンドウ処理を高速化するライブラリ。 ||
|| [[https://lmfit.github.io/lmfit-py/|lmfit]] || {{{mamba install -c conda-forge lmfit}}} || 非線形最小二乗法ライブラリ。Scipyよりも直感的にフィッティングができる。 ||
|| [[https://iminuit.readthedocs.io/|iminuit]] || {{{mamba install -c conda-forge iminuit}}} || 高エネルギー物理で標準的な「Minuit」のPython版。高度なフィッティング用。 ||

=== 重力波・KAGRAデータ解析 ===
我々の分野に特化したライブラリです。多くのツールは {{{conda-forge}}} チャンネルで提供されています。

|| '''import時の名前''' || '''インストールコマンド''' || '''説明''' ||
|| [[https://gwpy.github.io/|gwpy]] || {{{mamba install -c conda-forge gwpy}}} || 重力波データ解析用。時系列データの取得・プロット・スペクトル解析が簡単。'''※現在バージョン4.0.xがリリースされており、pip/conda共に最新版が利用可能です。''' ||
|| [[https://lscsoft.docs.ligo.org/lalsuite/|lalsuite]] || {{{mamba install -c conda-forge lalsuite}}} || LAL (LIGO Algorithm Library)。直接呼ばなくても、フレームファイルの読み書きの裏側で必須。 ||
|| [[https://gwosc.readthedocs.io/|gwosc]] || (gwpy等で自動インストール) || LIGO/Virgo/KAGRAの公開データ (Open Data) を取得するツール。 ||
|| [[https://gwdatafind.readthedocs.io/|gwdatafind]] || (gwdetchar等で自動インストール) || 分散ストレージ上のフレームファイルのパスを検索するツール。 ||
|| [[https://git.ligo.org/gwinc/gwinc|gwinc]] || {{{mamba install -c conda-forge gwinc}}} || 干渉計のノイズバジェット（感度計算）を行うシミュレーションツール。 ||
|| [[https://anaconda.org/conda-forge/inspiral-range|inspiral_range]] || {{{mamba install -c conda-forge inspiral-range}}} || 検出器のノイズスペクトルから、連星中性子星(BNS)などの到達距離(Range)を計算するツール。 ||
|| [[https://gwdetchar.readthedocs.io/|gwdetchar]] || {{{mamba install -c conda-forge gwdetchar}}} || 検出器の特性評価（DetChar）用ツール群。 ||
|| [[https://gwsumm.readthedocs.io/|gwsumm]] || {{{mamba install -c conda-forge gwsumm}}} || 解析結果のサマリーページ（HTML）を作成するツール。 ||
|| [[https://pycbc.org/|pycbc]] || {{{mamba install -c conda-forge pycbc}}} || コンパクト連星合体（CBC）の探索・パラメータ推定用ライブラリ。 ||
|| [[https://pygwb.readthedocs.io/|pygwb]] || {{{mamba install -c conda-forge pygwb}}} || 背景重力波（SGWB）解析用ライブラリ。 ||

=== DTT / 計測制御系システム ===
KAGRAのデジタル制御システムや、診断ツール(DTT)に関連するパッケージです。

|| '''import時の名前''' || '''インストールコマンド''' || '''説明''' ||
|| [[https://pypi.org/project/nds2-client/|nds2]] || {{{mamba install -c conda-forge python-nds2-client}}} || KAGRAのクローズドなデータサーバー (NDS) にアクセスするために必要。 ||
|| [[https://anaconda.org/conda-forge/ndscope|ndscope]] || {{{mamba install -c conda-forge ndscope}}} || NDS2サーバーからデータを取得し、ターミナルやGUI上で波形を確認できるオシロスコープツール。 ||
|| [[https://anaconda.org/conda-forge/dtt-xml-tools|dttxml]] || {{{mamba install -c conda-forge dtt-xml-tools}}} || KAGRA/LIGOの計測制御で使うDTT (Diagnostics Test Tools) のXMLファイルを読み書きするツール。 ||
|| (コマンドとして使用) || {{{mamba install -c conda-forge dtt-diaggui}}} || DTTのGUIフロントエンド（DiagGUI）を利用するためのパッケージ。 ||
|| [[https://python-control.readthedocs.io/|control]] || {{{mamba install -c conda-forge python-control}}} || 制御工学（伝達関数、状態空間モデル、ボード線図など）の解析・設計を行うためのライブラリ。 ||

=== 地球物理・環境モニター系 ===
PEMグループではよく使う、地図・座標・地震学関連のライブラリです。

|| '''import時の名前''' || '''インストールコマンド''' || '''説明''' ||
|| [[https://docs.obspy.org/|obspy]] || {{{mamba install -c conda-forge obspy}}} || 地震学用ライブラリ。地震計データの解析、miniseedフォーマット等の読み込みに強力。 ||
|| [[https://geopandas.org/|geopandas]] || {{{mamba install -c conda-forge geopandas}}} || Pandasの拡張。地図データ（シェープファイル等）を扱う。 ||
|| [[https://www.pygmt.org/|pygmt]] || {{{mamba install -c conda-forge pygmt}}} || 地図や地球科学系の高品質なプロットを作成するGMTのPythonインターフェース。観測所の配置図作成などに便利。 ||
|| [[https://pyproj4.github.io/pyproj/|pyproj]] || (geopandas等で自動インストール) || 地図投影法や座標変換（緯度経度⇔平面直角座標など）を行う。 ||

=== 機械学習・データサイエンス ===
グリッチ分類や環境ノイズの相関調査などで活用される機械学習ライブラリです。

|| '''import時の名前''' || '''インストールコマンド''' || '''説明''' ||
|| [[https://scikit-learn.org/|sklearn]] || {{{mamba install -c conda-forge scikit-learn}}} || 古典的な機械学習アルゴリズム（SVM、ランダムフォレスト、PCAなど）の標準ライブラリ。 ||
|| [[https://pytorch.org/|torch]] || {{{mamba install -c conda-forge pytorch}}} || 深層学習（ディープラーニング）フレームワーク。ニューラルネットワークの構築に使用。 ||
|| [[https://lightgbm.readthedocs.io/|lightgbm]] || {{{mamba install -c conda-forge lightgbm}}} || 決定木ベースの勾配ブースティングライブラリ。表形式データの分類・回帰において非常に高速で高精度。 ||

=== 解析環境・コード品質ツール ===
Pythonのコードを書いたり実行したり、品質を保つためのツールです。

|| '''import時の名前''' || '''インストールコマンド''' || '''説明''' ||
|| (コマンドとして使用) || {{{mamba install -c conda-forge jupyterlab}}} || [[https://jupyter.org/|JupyterLab]]: ブラウザで対話的に解析できるノートブック環境。必須。 ||
|| [[https://marimo.io/|marimo]] || {{{mamba install -c conda-forge marimo}}} || 次世代のリアクティブなPythonノートブック。Jupyterと異なり、セルの実行順序による状態の不整合が起きない。 ||
|| [[https://www.h5py.org/|h5py]] || (gwpy等で自動インストール) || HDF5形式のデータを読み書きする。大量のデータを保存する場合に使用。 ||
|| [[https://tqdm.github.io/|tqdm]] || {{{mamba install -c conda-forge tqdm}}} || {{{for}}} ループの進捗バーを表示する。長い解析のイライラ解消に。 ||
|| (コマンドとして使用) || {{{mamba install -c conda-forge ruff}}} || Rust製の超高速なコードリンター＆フォーマッター。PEP8準拠の綺麗なコードを保つために推奨。 ||
|| (コマンドとして使用) || {{{mamba install -c conda-forge mypy}}} || 静的型チェッカー。変数や関数の型ヒントを検証し、実行前のバグ発見に役立つ。 ||
|| (コマンドとして使用) || {{{mamba install -c conda-forge pytest}}} || Pythonの標準的なテストフレームワーク。解析モジュールやパイプラインの動作確認・自動テストに使用。 ||

== インストールコマンドのまとめ ==
個別にインストールするのは手間なので、以下のコマンドで一括インストールすることをお勧めします。
（すべて {{{conda-forge}}} チャンネルから取得・解決されます）

{{{
# 1. 基礎・データ解析・DTT制御系
mamba install -c conda-forge python=3.11 gwpy python-nds2-client lalsuite ndscope inspiral-range gwinc gwdetchar gwsumm pycbc pygwb dtt-xml-tools dtt-diaggui python-control

# 2. 地球物理・可視化・機械学習系
mamba install -c conda-forge obspy geopandas pygmt corner scikit-learn pytorch lightgbm

# 3. ユーティリティ・開発・コード品質ツール
mamba install -c conda-forge jupyterlab marimo natsort chardet bottleneck lmfit iminuit tqdm ruff mypy pytest
}}}