# tkmlr マニュアル

## 1. 役割

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

## 2. 推奨import

```python
from tkmlr import create_model, registered_models, regression_report
```

## 3. 基本例

```python
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 |

実行時の登録一覧:

```python
print(list(registered_models()))
```

## 5. 共通interface

`BaseRegressor` の主要契約:

```text
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を回帰器として使う

```python
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から除外 |

```python
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として保持します。

```python
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登録

```python
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

```bash
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向けコード生成ルール

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