tkmlr マニュアル

1. 役割

tkmlr は、複数の回帰backendを共通の fit/predict interfaceで扱う小型ライブラリです。通常の回帰を担当し、次の実験点を選ぶadaptive optimizationは tkbo に分離されています。

2. 推奨import

from tkmlr import create_model, registered_models, regression_report

3. 基本例

from tkmlr import create_model, regression_report

model = create_model("gpr", alpha=1.0e-6)
model.fit(X_train, y_train)
y_pred, y_std = model.predict(X_test, return_std=True)

metrics = regression_report(y_test, y_pred)

標準偏差を返せないmodelで return_std=True を指定した場合の挙動はwrapper実装に依存するため、model.supports_std を確認してください。

4. 登録model

名前	backend
`linear`	sklearn LinearRegression
`ridge`	sklearn Ridge
`lasso`	sklearn Lasso
`elastic`	sklearn ElasticNet
`mlp`	sklearn MLPRegressor
`rf`, `random_forest`	sklearn RandomForestRegressor
`gpr`, `gp`	sklearn GaussianProcessRegressor
`svr`	sklearn SVR
`physbo`	PHYSBO GP/RFM surrogate wrapper

実行時の登録一覧:

print(list(registered_models()))

5. 共通interface

BaseRegressor の主要契約:

model.fit(X, y) -> model
model.predict(X, return_std=False)
model.get_params(deep=True) -> dict
model.set_params(**params) -> model
model.score(X, y) -> float

X: shape (n_samples, n_features)。1次元入力は (n, 1) に変換。
y: shape (n_samples,)。
supports_std: predictive uncertainty対応。
supports_score: backend固有score対応。

6. PHYSBOを回帰器として使う

model = create_model(
    "physbo",
    num_rand_basis=200,
    interval=0,
    standardize=True,
    random_seed=1,
)
model.fit(X_train, y_train)
y_mean, y_std = model.predict(X_candidates, return_std=True)
ei = model.acquisition(X_candidates, mode="EI")

これは回帰・score計算用wrapperであり、ask/tell は実装しません。adaptive searchには tkbo を使います。

7. 表データとtarget列規則

tkmlr.data.parse_target_columns() は列名から目的を読み取ります。

列名例	意味
`max:y`	yを最大化
`min:y`	yを最小化（内部で符号反転）
`=3.5:y`	yを3.5へ近づける（負の二乗誤差へ変換）
`t1:y`, `o1:y`	最大化targetとplot index指定
`-comment`	descriptorから除外

from tkmlr.data import read_table, make_xy_from_table

df = read_table("data.xlsx")
X, y, spec, descriptors, work = make_xy_from_table(df)

8. 前処理

Standardizer はNumPyだけで動く単純標準化器です。分散0列はscale=1として保持します。

from tkmlr.preprocessing import Standardizer

scaler = Standardizer().fit(X_train)
X_train_std = scaler.transform(X_train)
X_test_std = scaler.transform(X_test)

LogTransformer はDataFrameの指定列へcolumn-wise log変換を行います。0以下の値の扱いは入力側で検討してください。

9. 独自model登録

from tkmlr import BaseRegressor, register_model

class MyRegressor(BaseRegressor):
    name = "my_model"

    def fit(self, X, y):
        self.model_ = ...
        return self

    def predict(self, X, return_std=False):
        ...


@register_model("my_model")
def build_my_model(**params):
    return MyRegressor(**params)

登録はbuilder関数に対するdecoratorです。register_model("name", cls) 形式ではありません。

10. CLI

python -m tkmlr.cli \
  --input data.xlsx \
  --method gpr \
  --target max:y \
  --return-std 1

現CLIは全データでfitし、同じデータに対するmetricを表示する簡易動作です。holdoutやcross validationを自動実行すると仮定しないでください。

11. 依存関係

numpy, pandas, scikit-learn, openpyxl
PHYSBO modelのみ physbo
plotを追加する場合は matplotlib

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

model生成は create_model(name, **params) を使う。
回帰とBayesian optimizationを分け、tkmlr に ask/tell を期待しない。
return_std=True の前に supports_std またはmodel種別を確認する。
PHYSBO回帰器の標準化は内部で行われるため、二重標準化しない。
target列の min: や =value: は内部目的値へ変換される。予測値を元単位のtargetと混同しない。
CLI metricはtraining metricであり、汎化性能評価として報告しない。
新backendはregistryへbuilderを登録し、factory本体を書き換えない。