tkfilter マニュアル

1. 役割と責務分離

tkfilter は、装置・ソフトウェア固有のデータreaderをpluginとして読み込み、入力ファイルに適合するpluginを優先順に選ぶパッケージです。

要素	責務
filter plugin	自分が読める形式か判定し、ファイルを読み、`inf` 辞書を返す
`tkFilterManager`	pluginのロード、優先順位、適合判定、複数ファイル処理
アプリケーション	`inf` を解析・表示・保存する

新規コードでは「pluginは読む、managerは探す、アプリは使う」という分離を維持します。

2. 推奨import

from tkfilter import load_filters, read_data, read_files, tkFilterManager

3. 単一ファイル

from tkfilter import read_data

inf = read_data(
    "sample.ras",
    plugin_dir="filter",
    manifest="filter/plugin_order.txt",
)

4. managerの再利用

from tkfilter import load_filters

manager = load_filters(
    plugin_dir="filter",
    manifest="filter/plugin_order.txt",
    include_unlisted=False,
    is_print=False,
)

inf1 = manager.read_data("sample1.ras")
inf2 = manager.read_data("sample2.ras")

大量ファイルでは、毎回pluginをimportし直さずmanagerを再利用します。

5. 複数ファイル

results = manager.read_files(
    "data/*.*",
    skip_temporary=True,
    skip_output=True,
    raise_error=False,
)

既定では、~ で始まる一時ファイルと、名前に -out. を含む出力ファイルを除外します。

6. plugin優先順位

manifest / order_file に1行1pluginを書きます。

# vendor-specific readers first
miniflex_ras2xrd.py
bruker2xrd.py

# generic readers last
txt2xrd.py
csv2xrd.py

空行と # コメントは無視されます。
.py あり・なしを利用できます。
専用readerを先、汎用readerを後に置きます。
include_unlisted=True のときだけ未掲載pluginを最後に追加します。
manifest未指定では plugin_dir/fmask をファイル名順で読みます。

7. pluginの最小契約

新規pluginで必須に近い関数は次の2つです。

def check_file_type(infile, inf=None, app=None, cparams=None):
    # 対応する場合は情報を返し、非対応ならNone
    return {"file_type": input_type}


def read_data(infile, app=None, cparams=None, is_print=False):
    return inf

任意フック:

def initialize(app=None, cparams=None): ...
def update_vars(app=None, cparams=None): ...
def convert(inf, app=None, cparams=None): return inf
def get_input_type(inf=None, app=None, cparams=None): ...
def get_output_type(inf=None, app=None, cparams=None): ...
def get_output_path(infile, inf=None, app=None, cparams=None): ...
def print_data(inf, app=None, cparams=None): ...
def plot_data(inf, app=None, cparams=None): ...
def save_data(outfiles, inf, app=None, cparams=None, is_print=False): ...

通常の形式不一致では例外を出さず None を返します。対応形式と判定した後の読み込み失敗は、ValueError 等をraiseする設計を推奨します。

8. 標準 `inf` 辞書

単一region・単一spectrumの推奨形:

inf = {
    "filename": str(infile),
    "sample_name": sample_name,
    "data_list_type": "[[x, y]]",
    "meta": meta,
    "labels": [[r"2$\theta$ (degree)", "Intensity"]],
    "data_list": [[x, y]],
    "nregion": 1,
    "nspectrum": 1,
    "ndata": len(x),
    "xmin": float(min(x)),
    "xmax": float(max(x)),
    "xstep": float(x[1] - x[0]),
    "yscale": "linear",
}

複数spectrumでは1region内を [x, y1, y2, ...]、複数regionでは data_list の外側listを増やします。特殊情報は diffractions, conv_data 等の追加キーに格納できます。

managerは辞書に filter_name と file_type がなければ補います。

9. `return_filter` とエラー制御

inf, filt, file_type = manager.read_data(
    "sample.ras",
    return_filter=True,
    raise_error=True,
)

一致pluginがない場合:

raise_error=True: RuntimeError
raise_error=False: None（return_filter=True なら (None, None, None)）

10. 同梱plugin群

同梱ソースには次のカテゴリがあります。

alamode: ALAMODE出力・構造変換
atlas: Silvaco ATLASデータ
crystal: JSON結晶構造→CIF
electrical: 電気特性測定表
pes: PES/HAXPES/ARPES
thermal: 熱物性データ
vasp: POSCAR、vasprun、DOS、band等
xrd: 各社・各形式の粉末XRD
xrf: XRF出力

個別pluginの正確な関数シグネチャと input_type / output_type はAPIリファレンスを参照してください。

10A. 同梱pluginカタログ（ソース定数から抽出）

分類	plugin	拡張子	入力形式	出力形式
`alamode`	`alamode_property2xlsx`	`.in`	ALMODE anphon input .in	Excel .xlsx
`alamode`	`alamode_xyz2cif`	`.xyz`	ALAMODE .xyz	CIF
`atlas`	`atlas_dat2xlsx`	`.dat`	ATLAS output .dat	MS-Excel .xlsx
`atlas`	`atlas_dos2xlsx`	`.out`	ATLAS output .out	MS-Excel .xlsx
`atlas`	`atlas_tft2dat`	`.log`	ATLAS output .log	MS-Excel .xlsx
`atlas`	`atlas_tft2xlsx`	`.log`	ATLAS output .log	MS-Excel .xlsx
`crystal`	`json2cif`	`.json`	JSON crystal structure	CIF
`electrical`	`S-sigma-T2xlsx`	`.xlsx`	S-sigma-T .xlsx	MS-Excel .xlsx
`electrical`	`resitest8300_csv_T2xlsx`	`.csv`	Resitest8300 .csv	Hall T
`electrical`	`resitest8300_hdt_T2xlsx`	`.hdt`	Resitest8300 .hdt	Hall T
`electrical`	`resitest8400_T2xlsx`	`.xlsx`	Resitest8400 .xlsx	Hall T
`pes`	`MDR_haxpes2xlsx`	`.csv`	MDR HAXPES .csv	MSExcel .xlsx
`pes`	`PIX2xlsx`	`.xlsx`	Photo ionization cross-section HAXPES .xlsx	MS-Excel .xlsx
`pes`	`arpes_pxt2xlsx`	`.pxt`	KEK ARPES .pxt	MS-Excel .xlsx
`pes`	`spring8_haxpes2xlsx`	`.txt`	SPring-8 HAXPES .txt	MS-Excel .xlsx
`pes`	`vasp2pes`	``	VASP output	PES
`thermal`	`picotr2xlsx`	`.csv`	CSV	MSExcel .xlsx
`vasp`	`poscar2cif`	``	VASP POSCAR	CIF
`vasp`	`vasp2band`	``	VASP output	Band
`vasp`	`vasp2cif`	``	VASP POSCAR/vasprun.xml	CIF
`vasp`	`vasp2dos`	``	VASP output	DOS
`vasp`	`vasp2dos - #U30b3#U30d4#U30fc`	``	VASP output	DOS
`vasp`	`vaspkit2dos`	`.dat`	VASPKIT output	DOS
`vasp`	`vasprun2inputs`	`.xml`	vasprun.xml	VASP input files
`xrd`	`bruker2xrd`	`.txt`	Bruker Lynkx .txt	pXRD
`xrd`	`cif2xrd`	`.cif`	CIF	pXRD
`xrd`	`csv2xrd`	`.csv`	CSV	pXRD
`xrd`	`miniflex_ras2xrd`	`.ras`	MiniFlex .ras	pXRD
`xrd`	`pdf_xlsx2xrd`	`.xlsx`	PDF2 data copied to .xlsx	pXRD
`xrd`	`rietan_int2xrd`	`.int`	RIETAN .int	pXRD
`xrd`	`rietan_pat2xrd`	`.pat`	RIETAN .pat	pXRD
`xrd`	`rint2xrd`	`.asc`	RINT2000 .asc	pXRD
`xrd`	`topas_pro2xrd`	``	TOPAS .pro	pXRD
`xrd`	`topas_txt2EVA`	``	TOPAS .txt	EVA xy .txt
`xrd`	`topas_txt2xrd`	``	TOPAS .txt	pXRD
`xrd`	`txt2xrd`	`.txt`	Text .txt	pXRD
`xrd`	`xlsx2xrd`	``	MSExcel .xlsx	pXRD
`xrd`	`xy2xrd`	`.xy`	xy data .xy	pXRD
`xrf`	`bruker_tiger2xlsx`	`.txt`	Bruker S8 Tiger .txt	xlsx

11. 互換性と依存関係

多くの旧pluginは app=None, cparams=None を保持し、旧 tklib、pymatgen、NumPy、SciPy、Matplotlib、pandas/openpyxl等に依存します。tkfilter コア自体と個別pluginの依存は分けて考えてください。

ファイル名にハイフンや空白を含むpluginは通常の import package.module に向きません。managerのファイルパスロードを使います。

12. 新規pluginテンプレート

from pathlib import Path
import numpy as np

plugin_ver = "data:0.2"
default_ext = ".txt"
input_type = "Example text"
output_type = "[[x, y]]"


def check_file_type(infile, inf=None, app=None, cparams=None):
    path = Path(infile)
    if path.suffix.lower() != default_ext:
        return None
    with path.open("r", encoding="utf-8", errors="replace") as fh:
        first = fh.readline()
    if "EXAMPLE" not in first:
        return None
    return {"file_type": input_type}


def read_data(infile, app=None, cparams=None, is_print=False):
    data = np.loadtxt(infile, comments="#")
    if data.ndim != 2 or data.shape[1] < 2:
        raise ValueError("Expected at least two numeric columns")
    x = data[:, 0]
    y = data[:, 1]
    return {
        "filename": str(infile),
        "data_list_type": "[[x, y]]",
        "labels": [["x", "y"]],
        "data_list": [[x, y]],
        "nregion": 1,
        "nspectrum": 1,
        "ndata": len(x),
        "xmin": float(np.min(x)),
        "xmax": float(np.max(x)),
        "yscale": "linear",
    }

13. 生成AI向けコード生成ルール

アプリ側から個別pluginを直接import・総当たりせず、read_data() または tkFilterManager を使う。
pluginの検出順はmanifestに置き、pluginコードに優先順位を埋め込まない。
check_file_type() は非対応時に None を返す。通常の不一致を例外にしない。
read_data() は成功時に辞書を返し、app.terminate() を呼ばない。
旧pluginの戻り値・依存を勝手に一括変更しない。
inf["data_list"] のnestingと labels のnestingを対応させる。
app / cparams は互換引数として保持し、不要なら無視する。
一般形式readerはmanifest後方に置く。
plugin固有の出力ファイル名や変換仕様は、そのpluginの実装・APIリファレンスで確認する。