ft_exafs_scan プログラム仕様

ft_exafs_scan.py

EXAFSデータのk空間におけるFFT/MEM変換ツールです。

入力データ:

Column 0 : k [A^-1] Column 1 : signal, 通常 chi(k), k^2 chi(k) など。

主な機能:

EXAFS R軸補正: chi(k) ~ sin(2 k R + phase) に基づき、R = pi * frequency を使用。
変換モード: fft, mem, both のいずれかを選択可能。
FFT出力: real, imag, amplitude, power を選択可能。
ゼロパディング: --npadding オプションで制御（デフォルト 1024）。
k重み付け: --korder オプションで制御。
EXAFSスタイルのハニング窓: --hrange と --hwidth オプションで制御。
パラメータスキャンオーバーレイ:
--scan_order START STEP N --scan_hmin START STEP N --scan_hmax START STEP N --scan_korder START STEP N --scan_npadding START STEP N
オプションの正規化:
--normalize none|max

使用例:

# 通常のFFT python ft_exafs_scan.py data.xlsx --mode fft --korder 0 --hrange 2 12 --hwidth 0.5

# MEM, 固定次数 20 python ft_exafs_scan.py data.xlsx 20 --mode mem --korder 0 --hrange 2 12 --hwidth 0.5

# MEM次数をスキャン: 10,20,30,40,50 python ft_exafs_scan.py data.xlsx --mode mem --scan_order 10 10 5 --korder 0 --hrange 2 12 --hwidth 0.5

# ハニング窓の幅をスキャン: 0.2,0.4,0.6,0.8,1.0 python ft_exafs_scan.py data.xlsx --mode fft --scan_hwidth 0.2 0.2 5 --korder 0 --hrange 2 12

# 形状比較のために各曲線を最大値1に正規化してスキャン python ft_exafs_scan.py data.xlsx --mode mem --scan_order 20 20 5 --normalize max

関連リンク:

ft_exafs_scan.py - EXAFSデータ変換ツール

spectrum_.ft_exafs_scan.apply_scan_value(args, scan_param, value, k)[ソース]

渡されたスキャンパラメータの値を args 名前空間に適用し、そのコピーを返します。

詳細説明:: 元の args オブジェクトを変更しないように、まずコピーを作成します。次に、`scan_param`に応じて対応する`args`属性に`value`を適用します。 `hrange`が設定されていない場合は、k軸の全範囲で初期化されます。

パラメータ:

args (argparse.Namespace) -- コマンドライン引数を格納する元の名前空間オブジェクト。
scan_param (str) -- 変更するスキャンパラメータの名前。
value (Union[int, float]) -- 適用するスキャンパラメータの値。
k (numpy.ndarray) -- k軸データ。`hrange`の初期化に使用される場合があります。

戻り値:

指定されたスキャン値が適用された args 名前空間のコピー。

戻り値の型:

argparse.Namespace

例外:

ValueError -- 未知のスキャンパラメータが指定された場合に発生します。

spectrum_.ft_exafs_scan.calc_fft_exafs(signal_used, dk, nfft)[ソース]

EXAFSスタイルのFFTを計算します。

詳細説明:: FFTは np.fft.rfft を使用して計算されます。 EXAFSでは chi(k) ~ sin(2 k R + phi) の関係があるため、R軸は R = pi * frequency と定義されます。積分スケールを模倣するために、FTの結果は dk を乗算されます。結果として、複素FFT、実数部、虚数部、振幅、パワーが返されます。

パラメータ:

signal_used (numpy.ndarray) -- 前処理された信号データ。
dk (float) -- k軸の平均k間隔。
nfft (int) -- FFTのNFFT長（ゼロパディングを含む）。

戻り値:

EXAFS R軸、複素FFT、FFTの実数部、FFTの虚数部、FFTの振幅、FFTのパワー。

戻り値の型:

tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray, numpy.ndarray, numpy.ndarray, numpy.ndarray]

spectrum_.ft_exafs_scan.calc_mem_exafs(signal_used, dk, order, nfft)[ソース]

spectrum.pburg を使用してMEMスペクトルを計算します。

詳細説明:: Burg法（spectrum.pburg）を用いて最大エントロピー法 (MEM) スペクトルを計算します。 pburg.frequencies() は cycles/sample の単位で周波数を返すため、 EXAFSのR軸 (R = pi * frequency / dk) に変換されます。

パラメータ:

signal_used (numpy.ndarray) -- 前処理された信号データ。
dk (float) -- k軸の平均k間隔。
order (int) -- ARモデルの次数。
nfft (int) -- FFTのNFFT長（ゼロパディングを含む）。

戻り値:

EXAFS R軸、サンプルあたりの周波数、MEMスペクトルのパワースペクトル密度 (PSD)。

戻り値の型:

tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray]

spectrum_.ft_exafs_scan.estimate_dk(k, rtol=0.001)[ソース]

k軸からk間隔(dk)を推定します。

詳細説明:: k軸の隣接する値の差分の平均値からk間隔を推定します。 k軸の均一性を相対標準偏差で評価し、均一でない場合は警告を表示します。 FFT/MEMは均一にサンプリングされたkデータを仮定するため、不均一な場合は注意が必要です。

パラメータ:

k (numpy.ndarray) -- k軸データ。
rtol (float) -- k間隔の差分の相対標準偏差の許容範囲。この値を超えると警告が表示されます。デフォルトは1e-3。

戻り値:

推定されたk間隔と、k間隔の差分の相対標準偏差。

戻り値の型:

tuple[float, float]

例外:

ValueError -- dkが0の場合に発生します。

spectrum_.ft_exafs_scan.find_main_peak(R, y, rmin=1e-12)[ソース]

R=0を除外してメインピークを見つけます。

詳細説明:: 指定されたR軸とyデータから、Rが`rmin`よりも大きい範囲でyの最大値を見つけ、そのピークのR値とy値を返します。

パラメータ:

R (numpy.ndarray) -- R軸データ。
y (numpy.ndarray) -- 変換された信号（振幅、PSDなど）。
rmin (float) -- ピーク検索から除外するR軸の最小値。デフォルトは1e-12。

戻り値:

メインピークのR値とy値。ピークが見つからない場合はNaN。

戻り値の型:

tuple[float, float]

spectrum_.ft_exafs_scan.get_active_scan(args)[ソース]

アクティブなスキャンパラメータとその値を取得します。

詳細説明:: 同時に指定できるスキャンパラメータは1つだけです。複数のスキャンパラメータが指定された場合、エラーを発生させます。選択されたスキャンパラメータとそれに対応する値のリストを返します。

パラメータ:: args (argparse.Namespace) -- コマンドライン引数を格納する名前空間オブジェクト。
戻り値:: アクティブなスキャンパラメータの名前と、それに対応する値のリスト。アクティブなスキャンがない場合は (None, None) を返します。
戻り値の型:: tuple[Optional[str], Optional[list[Union[int, float]]]]
例外:: ValueError -- 複数のスキャンパラメータが指定された場合、または有効なスキャン値が生成されない場合に発生します。

spectrum_.ft_exafs_scan.load_xy(infile, sheet=0, xcol=0, ycol=1)[ソース]

.xlsx/.csv/.txt/.datファイルからk軸と信号の列を読み込みます。

詳細説明:: 指定された入力ファイルパスから、k軸と信号のデータを読み込みます。ファイル形式はExcel (.xlsx)、CSV (.csv)、テキスト (.txt, .dat) をサポートします。欠損値 (NaN, Inf) は除去され、データポイントが少ない場合はエラーとなります。 k軸が単調増加でない場合はソートされます。

パラメータ:

infile (str) -- 入力ファイルへのパス。
sheet (Union[str, int]) -- Excelファイルの場合のシート名またはシートインデックス。デフォルトは0。
xcol (int) -- k軸データの列インデックス（0から始まる）。デフォルトは0。
ycol (int) -- 信号データの列インデックス（0から始まる）。デフォルトは1。

戻り値:

k軸データと信号データ。

戻り値の型:

tuple[numpy.ndarray, numpy.ndarray]

例外:

ValueError -- サポートされていないファイル形式、2Dテーブルでないテキスト入力、指定された列インデックスが存在しない、有効なデータポイントが少ない、などの場合に発生します。

spectrum_.ft_exafs_scan.main()[ソース]

スクリプトのメイン実行関数です。

詳細説明:: コマンドライン引数を解析し、データの読み込み、k軸間隔の推定、 FFT/MEM変換の実行、パラメータスキャン処理、結果のExcelファイルへの保存、およびMatplotlibによる結果のプロットを行います。エラーが発生した場合は、適切なメッセージを出力し、プログラムを終了します。

戻り値:: なし
戻り値の型:: None

spectrum_.ft_exafs_scan.make_hanning_range_window(k, hrange=None, hwidth=0.5)[ソース]

k軸にEXAFSスタイルのハニング窓を作成します。

詳細説明:: 指定されたk範囲(hrange)と窓幅(hwidth)に基づいて、ハニング窓を生成します。 `hrange`が指定されない場合、すべてのkに対して1.0の窓関数が返されます。 `hwidth`が0の場合、矩形窓が生成されます。 `2.0 * hwidth`が`hrange`の幅よりも大きい場合、`hwidth`は自動調整されます。

パラメータ:

k (numpy.ndarray) -- k軸データ。
hrange (Optional[list[float]]) -- ハニング窓を適用するk範囲 [KSTART, KEND]。デフォルトはNone。
hwidth (float) -- ハニング窓のテーパー幅 [A^-1]。デフォルトは0.5。

戻り値:

k軸と同じ長さのハニング窓配列。

戻り値の型:

numpy.ndarray

例外:

ValueError -- `hrange`に2つの異なる値が必要な場合、または`hwidth`が0未満の場合に発生します。

spectrum_.ft_exafs_scan.make_output_filename(infile, mode, order, korder, scan_param=None)[ソース]

出力Excelファイル名を生成します。

詳細説明:: 入力ファイル名、変換モード、MEM次数、k重み付け次数、およびオプションのスキャンパラメータに基づいて、自動的に出力ファイル名を生成します。

パラメータ:

infile (str) -- 入力ファイルへのパス。
mode (str) -- 変換モード ("fft", "mem", "both")。
order (int) -- MEMのAR次数。
korder (float) -- k重み付けの次数。
scan_param (Optional[str]) -- アクティブなスキャンパラメータの名前。デフォルトはNone。

戻り値:

生成された出力ファイル名。

戻り値の型:

str

spectrum_.ft_exafs_scan.normalize_curve(y, method='none')[ソース]

プロットや比較のために1つの曲線を正規化します。

詳細説明:: `method`が"none"の場合、入力`y`は変更されずに返されます。 `method`が"max"の場合、`y`の有限値の絶対値の最大値で`y`全体を割って正規化します。これは、MEMスペクトルのスケールがAR次数によって大きく変化する場合の比較に特に有用です。

パラメータ:

y (numpy.ndarray) -- 正規化する曲線データ。
method (str) -- 正規化方法。"none"または"max"。デフォルトは"none"。

戻り値:

正規化された曲線データ。

戻り値の型:

numpy.ndarray

例外:

ValueError -- `method`が"none"または"max"以外の値の場合に発生します。

spectrum_.ft_exafs_scan.normalized_label(label, normalize)[ソース]

プロットラベルに正規化タグを追加します。

詳細説明:: 正規化方法が"max"の場合、元のラベルに / max を追加して返します。それ以外の正規化方法の場合は、元のラベルをそのまま返します。

パラメータ:

label (str) -- 元のプロットラベル。
normalize (str) -- 正規化方法。

戻り値:

正規化タグが追加された（または変更なしの）ラベル。

戻り値の型:

str

spectrum_.ft_exafs_scan.plot_results(args, k, signal_raw, result, scan_results=None, scan_param=None)[ソース]

入力信号と窓関数、変換結果をプロットします。スキャン結果が与えられた場合は、その曲線も重ねて表示します。

詳細説明:: matplotlibを使用して2つのサブプロットを生成します。上段のサブプロットは、生の信号、前処理された信号、およびハニング窓関数を表示します。下段のサブプロットは、FFTまたはMEMの変換結果を表示します。 `scan_results`が提供されている場合、各スキャンにおける変換曲線がオーバーレイされます。正規化オプション、R軸の範囲制限、対数スケールなどのプロットオプションがサポートされます。 `--savefig`が指定されている場合、プロットは画像ファイルとして保存されます。

パラメータ:

args (argparse.Namespace) -- コマンドライン引数を格納する名前空間オブジェクト。
k (numpy.ndarray) -- k軸データ。
signal_raw (numpy.ndarray) -- 生の信号データ。
result (dict) -- 単一の変換結果を含む辞書。`run_transform_for_args`の戻り値。
scan_results (Optional[list[dict]]) -- スキャンモードの場合の各スキャン結果のリスト。デフォルトはNone。
scan_param (Optional[str]) -- アクティブなスキャンパラメータの名前。デフォルトはNone。

戻り値:

None

spectrum_.ft_exafs_scan.preprocess_signal(k, signal_raw, korder=0.0, hrange=None, hwidth=0.5, remove_mean=False)[ソース]

k重み付け、オプションの平均減算、ハニング窓を適用して信号を前処理します。

詳細説明:: 入力された生の信号に、`korder`に基づくk重み付けを適用します。例えば、入力がchi(k)の場合、`korder=2`を指定するとk^2 chi(k)になります。その後、`remove_mean`がTrueの場合、k重み付けされた信号から平均値が減算されます。最後に、`make_hanning_range_window`で作成されたハニング窓が適用され、変換に使用される最終的な信号が生成されます。

パラメータ:

k (numpy.ndarray) -- k軸データ。
signal_raw (numpy.ndarray) -- 生の信号データ。
korder (float) -- 信号に適用するk重み付けの次数。デフォルトは0.0。
hrange (Optional[list[float]]) -- ハニング窓を適用するk範囲 [KSTART, KEND]。デフォルトはNone。
hwidth (float) -- ハニング窓のテーパー幅 [A^-1]。デフォルトは0.5。
remove_mean (bool) -- k重み付け後に信号の平均値を減算するかどうか。デフォルトはFalse。

戻り値:

前処理された信号、k重み付けされた信号、平均値が減算された信号、および適用されたハニング窓。

戻り値の型:

tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray, numpy.ndarray]

spectrum_.ft_exafs_scan.run_transform_for_args(args, k, signal_raw, dk, quiet=False)[ソース]

指定された引数に基づいて、前処理と選択された変換を実行します。

詳細説明:: `preprocess_signal`関数を使用して入力信号を前処理します。次に、`args.mode`に応じてFFT、MEM、または両方の変換を実行します。 MEM変換の場合、`select_ar_order`関数によりARモデルの次数が決定されます。結果の概要は、`quiet`がFalseの場合にコンソールに出力されます。

パラメータ:

args (argparse.Namespace) -- コマンドライン引数を格納する名前空間オブジェクト。
k (numpy.ndarray) -- k軸データ。
signal_raw (numpy.ndarray) -- 生の信号データ。
dk (float) -- k軸の平均k間隔。
quiet (bool) -- 結果の概要をコンソールに出力するかどうか。Trueの場合、出力は抑制されます。デフォルトはFalse。

戻り値:

変換結果を含む辞書。前処理された信号、FFT/MEM結果、AR次数選択情報などが含まれます。

戻り値の型:

dict

spectrum_.ft_exafs_scan.save_results_excel(outfile, args, k, signal_raw, dk, rel_std_dk, result, scan_results=None, scan_param=None)[ソース]

入力データ、FFT/MEM結果、およびスキャン結果をExcelファイルに保存します。

詳細説明:: 結果は複数のシートに分割されて保存されます。 - Input シート: 生の信号、前処理された信号、窓関数など。 - FFT シート (FFTモードの場合): R軸、FFTの実数部、虚数部、振幅、パワー。正規化されたデータも含まれます。 - MEM シート (MEMモードの場合): R軸、MEMのPSD。正規化されたデータも含まれます。 - ScanSummary シート (スキャンモードの場合): 各スキャンパラメータ値でのピーク位置やパラメータの詳細。 - ScanCurves シート (スキャンモードの場合): 各スキャンにおける変換曲線のデータ。 - Summary シート: 変換に使用された主要なパラメータと情報。

パラメータ:

outfile (str) -- 結果を保存するExcelファイルへのパス。
args (argparse.Namespace) -- コマンドライン引数を格納する名前空間オブジェクト。
k (numpy.ndarray) -- k軸データ。
signal_raw (numpy.ndarray) -- 生の信号データ。
dk (float) -- k軸の平均k間隔。
rel_std_dk (float) -- k間隔の差分の相対標準偏差。
result (dict) -- 単一の変換結果を含む辞書。`run_transform_for_args`の戻り値。
scan_results (Optional[list[dict]]) -- スキャンモードの場合の各スキャン結果のリスト。デフォルトはNone。
scan_param (Optional[str]) -- アクティブなスキャンパラメータの名前。デフォルトはNone。

戻り値:

None

spectrum_.ft_exafs_scan.scan_values(start, step, n, integer=False)[ソース]

スキャンパラメータの値を生成します。

詳細説明:: 開始値 (start)、ステップサイズ (step)、およびステップ数 (n) に基づいて、等間隔の数値のリストを生成します。`integer`がTrueの場合、値は整数に丸められます。

パラメータ:

start (float) -- スキャン開始値。
step (float) -- 各ステップでの増分値。
n (int) -- 生成する値の数。
integer (bool) -- 生成された値を整数に丸めるかどうか。デフォルトはFalse。

戻り値:

生成されたスキャン値のリスト。

戻り値の型:

list[float] or list[int]

spectrum_.ft_exafs_scan.select_ar_order(signal, preset_order=8, max_order=40, order_method='bic')[ソース]

AIC/BICまたは事前設定値に基づいてARモデルの次数を選択します。

詳細説明:: 自己回帰 (AR) モデルの次数を選択するために、部分自己相関関数 (PACF)、赤池情報量基準 (AIC)、ベイズ情報量基準 (BIC) を使用します。 PACFは診断情報として表示されますが、主要な次数選択にはAIC/BICが使われます。 `order_method`に基づいて、最適な次数が選択されます。

パラメータ:

signal (numpy.ndarray) -- ARモデルを適用する信号データ。
preset_order (int) -- `order_method`が"preset"の場合に適用される、事前設定のAR次数。デフォルトは8。
max_order (int) -- AIC/BICでテストするARモデルの最大次数。デフォルトは40。
order_method (str) -- AR次数選択方法。"bic", "aic", "preset"のいずれか。デフォルトは"bic"。

戻り値:

選択されたAR次数と、AIC/BICの情報を含む辞書。

戻り値の型:

tuple[int, dict]

例外:

ValueError -- `order_method`がサポートされていない値の場合に発生します。

spectrum_.ft_exafs_scan.y_from_fft_result(fft_result, fft_plot)[ソース]

FFT結果からプロットに適したR軸とyデータを抽出します。

詳細説明:: `fft_plot`引数の値に基づいて、FFTの振幅、パワー、または実数部を返します。

パラメータ:

fft_result (tuple) -- `calc_fft_exafs`関数から返されたFFT結果のタプル。
fft_plot (str) -- プロットするFFTの種類。"amplitude", "power", "realimag"のいずれか。

戻り値:

R軸、プロットするyデータ、yデータの名前。

戻り値の型:

tuple[numpy.ndarray, numpy.ndarray, str]

spectrum_.ft_exafs_scan.y_from_mem_result(mem_result)[ソース]

MEM結果からプロットに適したR軸とyデータを抽出します。

詳細説明:: `calc_mem_exafs`関数から返されたMEM結果から、R軸とMEMのパワースペクトル密度 (PSD) を抽出します。

パラメータ:: mem_result (tuple) -- `calc_mem_exafs`関数から返されたMEM結果のタプル。
戻り値:: R軸、プロットするMEM PSDデータ、yデータの名前。
戻り値の型:: tuple[numpy.ndarray, numpy.ndarray, str]