API‐Reference - LostRuneCloud/AutoML GitHub Wiki

概要

このドキュメントは、AutoMLシステムの主要APIクラスとメソッドの詳細な仕様を説明します。実際のコード実装に基づいた正確な仕様を提供します。

メインクラス: AutoML

初期化

from automl_pipeline import AutoML

automl = AutoML(config={
    "task_type": None,              # 'classification', 'regression', None (auto-detect)
    "time_budget": 3600,            # 秒単位（デフォルト: 1時間）
    "optimization_metric": None,    # 最適化指標（自動選択）
    "complexity_level": "balanced", # 'simple', 'balanced', 'advanced'
    "explanation_level": "detailed", # 'basic', 'detailed', 'full'
    "resource_constraint": "balanced", # 'fast', 'balanced', 'unlimited'
    "save_path": "./models",        # モデル保存パス
    # 評価モジュール設定
    "evaluation_mode": "standard",  # 'standard', 'enhanced'
    "cross_validation_folds": 5,    # クロスバリデーション分割数
    "enable_statistical_tests": False, # 統計的検定の有効化
    "enable_visualization": True,   # 可視化の有効化
    # 最適化設定
    "adaptive_time_budget": True,   # 適応的時間管理
    "enable_checkpoint": True,      # チェックポイント機能
    "parallel_processing": True     # 並列処理
})

設定パラメータ詳細

パラメータ	型	デフォルト	説明
`task_type`	str/None	`None`	タスクタイプ。Noneで自動検出
`time_budget`	int	`3600`	最大実行時間（秒）
`optimization_metric`	str/None	`None`	最適化指標（accuracy, f1, rmse等）
`complexity_level`	str	`"balanced"`	処理の複雑さ（simple/balanced/advanced）
`explanation_level`	str	`"detailed"`	説明の詳細レベル
`resource_constraint`	str	`"balanced"`	リソース制約レベル
`save_path`	str	`"./models"`	モデル保存ディレクトリ
`evaluation_mode`	str	`"standard"`	評価モード
`cross_validation_folds`	int	`5`	CVの分割数
`enable_statistical_tests`	bool	`False`	統計的検定の有効化
`enable_visualization`	bool	`True`	可視化機能の有効化

主要メソッド

1. `load_and_profile(data_path, target_column=None)`

データを読み込み、プロファイリングを実行します。

data_profile = automl.load_and_profile(
    data_path="data.csv",
    target_column="target"
)

パラメータ:

data_path (str): データファイルのパス（CSV, Excel, Parquet, JSON対応）
target_column (str, optional): 目的変数のカラム名

サポートファイル形式:

CSV (.csv) - UTF-8, Shift_JIS, CP932エンコーディング対応
Excel (.xlsx, .xls)
Parquet (.parquet)
JSON (.json)

戻り値:

{
    "shape": (1000, 10),
    "target_type": "classification",  # or "regression"
    "missing_values_ratio": 0.05,
    "categorical_features": ["cat1", "cat2"],
    "numerical_features": ["num1", "num2"],
    "data_quality_score": 0.85,
    "profile_summary": "データ品質: 良好",
    "task_type_confidence": 0.95,
    "large_dataset": False,  # 大規模データセット判定
    "memory_usage_mb": 125.4
}

2. `fit(data=None, target=None, test_size=0.2, random_state=42)`

モデルの学習を実行します。

results = automl.fit(
    data=None,        # Noneの場合はload_and_profileで読み込んだデータを使用
    target=None,      # Noneの場合は事前に指定したtarget_columnを使用
    test_size=0.2,    # テストデータの割合
    random_state=42   # 乱数シード
)

パラメータ:

data (DataFrame, optional): 学習データ（省略時は事前読み込みデータを使用）
target (str/Series, optional): 目的変数
test_size (float): テストデータの割合（0.1-0.4）
random_state (int): 乱数シード

戻り値:

{
    "version": "Enhanced",  # or "Standard"
    "execution_time": 245.7,
    "preprocessing_info": {
        "transformations_applied": ["StandardScaler", "LabelEncoder"],
        "feature_engineering": True,
        "pipeline_complexity": "balanced",
        "quality_score": 0.92
    },
    "model_info": {
        "algorithm": "RandomForestClassifier",
        "hyperparameters": {
            "n_estimators": 100,
            "max_depth": 10,
            "random_state": 42
        },
        "optimization_method": "bayesian",  # Enhanced版の場合
        "ensemble": True,
        "feature_importance": {"feature1": 0.35, "feature2": 0.28}
    },
    "evaluation_results": {
        "metrics": {
            "accuracy": 0.87,
            "f1_score": 0.86,
            "precision": 0.88,
            "recall": 0.84,
            "roc_auc": 0.91
        },
        "confusion_matrix": [45, 5], [8, 42](/LostRuneCloud/AutoML/wiki/45,-5],-[8,-42),
        "cross_validation": {
            "cv_scores": [0.85, 0.88, 0.84, 0.89, 0.86],
            "cv_mean": 0.864,
            "cv_std": 0.018
        },
        "statistical_tests": {  # Enhanced版で統計的検定が有効な場合
            "wilcoxon_p_value": 0.023,
            "significance_level": 0.05,
            "is_significant": True
        },
        "evaluation_type": "comprehensive"  # or "basic", "fallback"
    }
}

3. `predict(X)`

新しいデータに対して予測を実行します。

predictions = automl.predict(new_data)

パラメータ:

X (DataFrame): 予測対象データ

戻り値:

# 分類の場合
array([0, 1, 0, 1])

# 回帰の場合  
array([123.45, 234.56, 345.67, 456.78])

注意事項:

モデルが学習済み（is_fitted=True）である必要があります
入力データは学習時と同じ特徴量構造である必要があります
前処理が自動的に適用されます
分類でラベルエンコーディングが使用された場合、自動的に元のラベルに逆変換されます

4. `save(path=None)`

モデルと前処理器を保存します。

saved_paths = automl.save(path="./my_models")

パラメータ:

path (str, optional): 保存ディレクトリパス（省略時は設定のsave_pathを使用）

戻り値:

{
    "model": "./my_models/model_20250618_143022.pkl",
    "preprocessor": "./my_models/preprocessor_20250618_143022.pkl",
    "label_encoder": "./my_models/label_encoder_20250618_143022.pkl",  # 分類の場合のみ
    "metadata": "./my_models/metadata_20250618_143022.json",
    "evaluation_report": "./my_models/evaluation_report_20250618_143022.html"  # 詳細評価が実行された場合
}

保存される内容:

model: 学習済みモデル（joblib形式）
preprocessor: 前処理パイプライン（joblib形式）
label_encoder: ラベルエンコーダー（分類タスクのみ）
metadata: 設定と性能情報（JSON形式）
evaluation_report: 詳細評価レポート（HTML形式）

内部状態プロパティ

# 学習状態の確認
automl.is_fitted          # bool: モデルが学習済みか
automl.execution_time     # float: 最後の実行時間（秒）
automl.target_column      # str: 目的変数のカラム名
automl.task_type          # str: 検出されたタスクタイプ

# 学習データの保持（評価用）
automl.X_train           # DataFrame: 学習用特徴量
automl.y_train           # Series: 学習用目的変数  
automl.X_test            # DataFrame: テスト用特徴量
automl.y_test            # Series: テスト用目的変数

# 学習済みコンポーネント
automl.model             # object: 学習済みモデル
automl.preprocessor      # object: 前処理パイプライン
automl.label_encoder     # object: ラベルエンコーダー（分類の場合）

バージョン別機能差異

Enhanced版 vs Standard版

機能	Enhanced版	Standard版
アルゴリズム数	17種類	4種類
最適化手法	ベイズ最適化、メタ学習	グリッドサーチ
統計的検定	Wilcoxon、t検定対応	基本指標のみ
アンサンブル	投票・スタッキング	単一モデル
説明可能性	SHAP統合	特徴量重要度のみ
転移学習	対応	非対応
依存ライブラリ	optuna, shap, plotly等	scikit-learn, pandas等

フォールバック機能

# 3段階フォールバック
try:
    # Enhanced版の実行
    model_builder = AutoModelBuilderEnhanced()
except ImportError:
    # Standard版にフォールバック
    model_builder = AutoModelBuilderStandard()
except Exception:
    # RandomForestにフォールバック
    model_builder = RandomForestFallback()

エラーハンドリング

例外クラス

# 主要例外
ValueError          # 不正なパラメータ、データ形式
FileNotFoundError   # データファイル不存在
ImportError         # 依存ライブラリ不足
RuntimeError        # 実行時エラー

一般的なエラーと対処法

try:
    automl = AutoML()
    results = automl.fit()
except FileNotFoundError as e:
    print(f"データファイルエラー: {e}")
except ImportError as e:
    print(f"依存ライブラリエラー: {e}")
    # Standard版で再試行
except ValueError as e:
    print(f"パラメータエラー: {e}")
except Exception as e:
    print(f"予期しないエラー: {e}")

使用例

基本的な使用パターン

from automl_pipeline import AutoML

# 1. 初期化
automl = AutoML(config={
    "time_budget": 1800,
    "complexity_level": "balanced"
})

# 2. データ読み込み・プロファイリング
profile = automl.load_and_profile("data.csv", "target")
print(f"データ形状: {profile['shape']}")
print(f"タスクタイプ: {profile['target_type']}")

# 3. モデル学習
results = automl.fit(test_size=0.2)
print(f"使用バージョン: {results['version']}")
print(f"精度: {results['evaluation_results']['metrics']['accuracy']:.3f}")

# 4. 新データ予測
new_predictions = automl.predict(new_data)

# 5. モデル保存
save_info = automl.save("./production_model")
print(f"モデル保存: {save_info['model']}")

高度な設定例

# Enhanced版を明示的に使用（高性能環境）
enhanced_config = {
    "complexity_level": "advanced",
    "time_budget": 7200,
    "enable_statistical_tests": True,
    "evaluation_mode": "enhanced",
    "resource_constraint": "unlimited",
    "adaptive_time_budget": True,
    "parallel_processing": True
}

automl = AutoML(config=enhanced_config)
results = automl.fit(test_size=0.15)

# 統計的検定結果の確認
if "statistical_tests" in results["evaluation_results"]:
    stats = results["evaluation_results"]["statistical_tests"]
    print(f"統計的有意性: {stats['is_significant']}")

制約環境での使用例

# 軽量設定（低リソース環境）
lightweight_config = {
    "complexity_level": "simple",
    "time_budget": 300,
    "resource_constraint": "fast",
    "enable_statistical_tests": False,
    "parallel_processing": False
}

automl = AutoML(config=lightweight_config)
results = automl.fit()  # Standard版が自動選択される

パフォーマンス指標

実行時間目安

データサイズ	Enhanced版	Standard版	メモリ使用量
小規模 (<1K行)	30秒-2分	15秒-1分	2-4GB
中規模 (1K-10K行)	2分-10分	1分-5分	4-8GB
大規模 (10K+行)	10分-1時間	5分-30分	8-16GB

精度目安

タスク	Enhanced版	Standard版
分類	Accuracy 0.85-0.95	Accuracy 0.80-0.90
回帰	R² 0.80-0.95	R² 0.75-0.90

API‐Reference - LostRuneCloud/AutoML GitHub Wiki

概要

メインクラス: AutoML

初期化

設定パラメータ詳細

主要メソッド

1. load_and_profile(data_path, target_column=None)

2. fit(data=None, target=None, test_size=0.2, random_state=42)

3. predict(X)

4. save(path=None)

内部状態プロパティ

バージョン別機能差異

Enhanced版 vs Standard版

フォールバック機能

エラーハンドリング

例外クラス

一般的なエラーと対処法

使用例

基本的な使用パターン

高度な設定例

制約環境での使用例

パフォーマンス指標

実行時間目安

精度目安

1. `load_and_profile(data_path, target_column=None)`

2. `fit(data=None, target=None, test_size=0.2, random_state=42)`

3. `predict(X)`

4. `save(path=None)`