テスト駆動開発から始める機械学習入門

はじめに

本記事は、テスト駆動開発（TDD）を実践しながら Python で機械学習を学ぶプロジェクトの完全ガイドです。４章から８章までの6つの段階を通じて、データ処理の基礎から実用的な機械学習 API まで、段階的にスキルアップできる構成になっています。

「機械学習って難しそう...」「数式ばかりでわからない...」「どこから手をつければいいの？」

そんな不安を持っているあなたも大丈夫！この記事では、テストを書きながら一歩ずつ確実に進んでいく ので、プログラミング初心者でも安心して機械学習の世界に飛び込めます。実際に動くコードを書きながら、データから価値を引き出す楽しさを体験しましょう！

🎯 本記事で学べること

テスト駆動開発（TDD）の実践: Red-Green-Refactor サイクルを実機械学習開発で体験
Python 機械学習開発: scikit-learn による実践的なモデル構築
現代的 Python 開発: uv、Ruff、mypy 等の最新ツールチェーン
段階的スキルアップ: 無理のない学習曲線で確実にレベルアップ

📚 学習の進め方

各章は以下の構成になっています：

学習目標: その章で何を学ぶかを明確化
実装した機能: 実際に作るコードの全体像
TDD 実践例: Red-Green-Refactor の実例
主要な学習ポイント: 深掘りした技術解説
技術的成果: その章での達成事項まとめ

最初の章から順番に進めることをおすすめしますが、気になる章から始めてもOKです！

１章機械学習とは

機械学習の魅力

機械学習は、データからパターンを学習し、予測や分類を行う技術です。従来のプログラミングとは大きく異なる、データ駆動のアプローチが特徴です。

従来のプログラミング:

# ルールを明示的にコーディング
if 花びらの長さ > 5 and 花びらの幅 > 1.5:
    種類 = "バージニカ"
elif 花びらの長さ > 3:
    種類 = "バーシクル"
else:
    種類 = "セトサ"

機械学習のアプローチ:

# データからルールを自動学習
model = DecisionTreeClassifier()
model.fit(訓練データ, 正解ラベル)  # データから学習！

# 未知のデータを予測
予測結果 = model.predict(新しいデータ)

この違い、わかりますか？機械学習では 「ルールを書く」のではなく「データに学ばせる」 のです！

機械学習ができること

機械学習は私たちの生活のあちこちで活躍しています：

📧 スパムメール検知: あなたの受信箱を守る
🎬 映画レコメンド: 次に観たい作品を提案
🏠 不動産価格予測: 家の適正価格を算出
🏥 病気の早期発見: 医療画像から異常を検出
🚗 自動運転: 安全な運転をサポート

本プロジェクトで作るもの

本プロジェクトでは、以下の4つの実践的な機械学習モデルを段階的に実装します：

🌸 分類問題 (離散的な値を予測):

Iris 分類: アヤメの花を 3種類に分類（多クラス分類の基礎）
Survived 分類: タイタニック号の乗客の生存を予測（二値分類の実践）

📊 回帰問題 (連続的な値を予測):

Cinema 予測: 映画の興行収入を予測（線形回帰の基礎）
Boston 予測: ボストンの住宅価格を予測（特徴量エンジニアリングの実践）

最後には、これら4つのモデルを FastAPI で Web API 化して、実際に使える形にします！

２章開発環境のセットアップ

さあ、機械学習の旅を始める準備をしましょう！といっても、難しいことはありません。必要なツールをサクッとインストールして、快適な開発環境を整えます。

現代的 Python 開発環境の構築

「環境構築って面倒...」と思ったあなた、安心してください！本プロジェクトでは、2024年最新の高速ツールを使うので、セットアップはあっという間に終わります。

🛠️ 必要なツール

以下のツールをインストールします。それぞれ強力な機能を持っていますが、今は「こんなのがあるんだな」程度の理解で OK です：

開発の基盤:

Python 3.10+: プログラミング言語本体（型ヒント機能を活用）
uv: 爆速パッケージマネージャー（従来の pip より 10-100倍速い！）

品質管理ツール:

Ruff: コード品質チェック（コードをキレイに保つ）
mypy: 型チェック（バグを事前に発見）
pytest: テストフレームワーク（TDD の要）
tox: タスクランナー（複数環境での品質チェックとタスク管理）

機械学習ライブラリ:

scikit-learn: 機械学習の定番ライブラリ（モデル構築に使用）
pandas: データ分析ライブラリ（データ操作の必需品）
FastAPI: 高性能 Web API フレームワーク（最終章で API 化に使用）

📦 セットアップ手順

ターミナルを開いて、以下のコマンドを順番に実行しましょう：

# ステップ 1: プロジェクトフォルダを作成
mkdir ml-tdd-project && cd ml-tdd-project

# ステップ 2: uv でプロジェクトを初期化
uv init

# ステップ 3: 機械学習に必要なライブラリをインストール
uv add pandas scikit-learn fastapi uvicorn

# ステップ 4: 開発用ツールをインストール
uv add --dev pytest pytest-cov ruff mypy tox

たったこれだけ！uv のおかげで、数秒でインストールが完了します。

⚙️ 品質管理設定

テストや品質チェックを自動化するため、pyproject.toml に設定を追加します：

[tool.ruff]
line-length = 88              # 1行の最大文字数
target-version = "py310"       # Python 3.10 向けにチェック

[tool.ruff.lint.mccabe]
max-complexity = 7             # 複雑すぎる関数を警告

[tool.mypy]
python_version = "3.10"
warn_return_any = true
warn_unused_configs = true
disallow_untyped_defs = true   # 型ヒント必須

[tool.pytest.ini_options]
testpaths = ["test"]
addopts = "--cov=src --cov-report=html --cov-report=term-missing"

また、tox.ini でタスクランナーの設定を行います：

[tox]
env_list = py310, lint, type, test
isolated_build = True

[testenv:test]
description = Run tests with coverage
deps =
    pytest
    pytest-cov
commands = pytest --cov=src --cov-report=html --cov-report=term-missing --verbose {posargs}

[testenv:lint]
description = Run linting with ruff
deps = ruff
commands =
    ruff check .
    ruff format --check .

[testenv:format]
description = Format code with ruff
deps = ruff
commands = ruff format .

[testenv:type]
description = Run type checking with mypy
deps =
    mypy
    pytest
commands = mypy src test {posargs}

[testenv:coverage]
description = Run coverage report
deps =
    pytest
    pytest-cov
commands = pytest --cov=src --cov-report=html --cov-report=term-missing

[testenv:all]
description = Run all quality checks
deps =
    pytest
    pytest-cov
    ruff
    mypy
commands =
    ruff check .
    ruff format --check .
    mypy src test
    pytest --cov=src --cov-report=html --cov-report=term-missing --verbose

この設定により、テストと品質チェックが自動化されます。コードを書くたびに品質が保証されるので、安心してリファクタリングできます！

各章では共通してこの環境を使用するため、最初のセットアップ以降は省略します。

🚀 品質チェックの実行

開発中は、コードの品質を継続的にチェックすることが重要です。tox を使えば、すべての品質チェックを簡単に実行できます。

タスクランナーを使った実行（推奨）:

# すべての品質チェックとテストを実行（推奨）
uv run tox -e all

# 個別タスクの実行
uv run tox -e test        # テストのみ
uv run tox -e lint        # リンターのみ
uv run tox -e type        # 型チェックのみ
uv run tox -e coverage    # カバレッジレポートのみ
uv run tox -e format      # フォーマットのみ

個別コマンドでの実行:

tox を使わず、個別にコマンドを実行することもできます：

# テスト実行
uv run pytest -v

# リンターのみ実行
uv run ruff check .

# 型チェックのみ実行
uv run mypy src test

# コードフォーマット
uv run ruff format .

どちらを使うべき？

開発中は tox -e all がおすすめ: 一度にすべてのチェックを実行できるので、コミット前の確認に最適
特定の問題を修正中は個別コマンド: 素早くフィードバックを得たい時に便利

tox を使うことで、複数の環境でのテストや、チーム全体で統一された品質基準を保つことができます。

プロジェクト構造の作成

「フォルダをどう分けたらいいの？」そんな疑問も、この構造に従えば解決です！

以下のようなディレクトリ構成を作成します：

ml-tdd-project/
├── src/                       # 📝 ソースコード置き場
│   ├── __init__.py
│   └── ml/                    # 機械学習モデル本体
│       ├── __init__.py
│       ├── iris_classifier.py       # アヤメ分類モデル
│       ├── cinema_predictor.py      # 映画興行収入予測モデル
│       ├── survived_classifier.py   # 生存予測モデル
│       └── boston_predictor.py      # 住宅価格予測モデル
├── test/                      # ✅ テストコード置き場
│   ├── __init__.py
│   └── test_basic.py          # 基本的な環境確認テスト
├── data/                      # 📊 データセット置き場
│   ├── iris.csv
│   ├── cinema.csv
│   ├── Survived.csv
│   └── Boston.csv
├── model/                     # 💾 訓練済みモデルの保存先
│   └── .gitkeep
├── script/                     # モデル訓練・評価スクリプト保存先
│   └── .gitkeep
├── notebook/                   # Jupyter Notebook保存先
│   └── .gitkeep
├── pyproject.toml             # ⚙️ プロジェクト設定ファイル
├── tox.ini                    # 🔧 タスクランナー設定ファイル
└── README.md                  # 📖 プロジェクト説明書

各ディレクトリの役割：

src/ml/: 機械学習モデルの実装コード（ここにロジックを書く）
test/: テストコード（TDD のテストを書く場所）
data/: 訓練・テスト用データセット（CSV ファイル）
model/: 訓練済みモデルの保存先（pickle ファイル）

この構造なら、どこに何があるか一目瞭然ですね！

📓 Jupyter Lab のセットアップと活用

機械学習開発では、Jupyter Lab が非常に重要なツールです。「コードを書いて、すぐに結果を確認する」というサイクルを高速で回せるため、データ分析や機械学習の実験に最適です！

Jupyter Lab とは？

Jupyter Lab は、インタラクティブな開発環境です。ブラウザ上で Python コードを実行し、その結果を即座に確認できます。

従来のスクリプト実行との違い：

# 従来の方法（スクリプト全体を実行）
# train.py
import pandas as pd

df = pd.read_csv('data.csv')
print(df.head())
print(df.describe())
# ↑ 毎回全体を実行する必要がある

# Jupyter Lab（セル単位で実行）
# セル 1
import pandas as pd
df = pd.read_csv('data.csv')

# セル 2（セル1の結果を保持したまま実行）
df.head()  # すぐに結果が表示される

# セル 3（必要な部分だけ再実行）
df.describe()  # 他のセルを実行せずに確認できる

Jupyter Lab の強み：

📊 データの可視化が簡単: グラフが即座に表示される
🔍 探索的分析に最適: 少しずつコードを試しながら分析できる
📝 ドキュメントとコードの統合: マークダウンでメモを書きながら開発
🎯 試行錯誤が楽: セル単位で実行・修正できる

🛠️ Jupyter Lab のインストール

uv を使えば、簡単にインストールできます：

# Jupyter Lab のインストール
uv add --dev jupyter jupyterlab

# インストールの確認
uv run jupyter --version
uv run jupyter lab --version

🚀 Jupyter Lab の起動

基本的な起動方法：

# プロジェクトディレクトリで起動
cd ml-tdd-project
uv run jupyter lab

# 自動的にブラウザが開き、Jupyter Lab が起動します
# URL: http://localhost:8888/lab

起動時のオプション：

# 特定のポートで起動
uv run jupyter lab --port 8889

# ブラウザを自動で開かない
uv run jupyter lab --no-browser

# 特定のディレクトリで起動
uv run jupyter lab --notebook-dir=./notebook

起動すると、インターフェースが表示されます：

📝 基本的な使い方

1. 新しいノートブックの作成

File → New → Notebook を選択
カーネル（Python 環境）を選択
.ipynb ファイルとして保存

2. セルの実行

# セルにコードを入力して Shift + Enter で実行
import pandas as pd
import numpy as np

# セルの実行結果がすぐ下に表示される
df = pd.DataFrame({'A': [1, 2, 3], 'B': [4, 5, 6]})
df.head()

3. マークダウンセルの活用

セルタイプを「Markdown」に変更すると、ドキュメントを書けます：

# データ分析の手順

## 1. データの読み込み
以下のコードでデータを読み込みます。

## 2. データの確認
- 行数: 100
- 列数: 4

4. よく使うショートカット

ショートカット	動作
`Shift + Enter`	セルを実行して次のセルへ
`Ctrl + Enter`	セルを実行（移動なし）
`A`	上に新しいセルを挿入
`B`	下に新しいセルを挿入
`DD`	セルを削除
`M`	マークダウンセルに変更
`Y`	コードセルに変更

🎨 便利な拡張機能

1. Variable Inspector（変数ビューア）

現在のメモリ上の変数を一覧表示：

uv add --dev jupyter-lsp jupyterlab-lsp

2. Code Formatter（コードフォーマッター）

Jupyter 上でコードを自動整形：

uv add --dev jupyterlab-code-formatter black isort

設定後、右クリック → Format Cell で整形できます。

3. Table of Contents（目次）

マークダウン見出しから自動で目次を生成：

Jupyter Lab 標準機能として含まれています（左サイドバーの目次アイコン）。

💡 プロジェクトでの活用方法

推奨ディレクトリ構成：

ml-tdd-project/
├── notebook/              # Jupyter Notebook 保存先
│   ├── 01_data_exploration.ipynb    # データ探索
│   ├── 02_iris_tutorial.ipynb       # Iris モデル学習
│   ├── 03_cinema_tutorial.ipynb     # Cinema モデル学習
│   └── 04_experiments.ipynb         # 実験・試行錯誤用
├── src/ml/                 # 本番コード（Notebook から移行）
└── test/                   # テストコード

開発フロー：

Jupyter Lab で探索
- データの確認
- モデルの試行錯誤
- 可視化と分析
動作確認したコードを本番化
- src/ml/ にモジュールとして実装
- TDD でテストを追加
- リファクタリング
Notebook はドキュメントとして保持
- 分析の記録
- チュートリアル
- チーム共有用

🔧 Jupyter Lab と TDD の組み合わせ

Jupyter Lab は探索用、TDD は本番コード用として使い分けます：

# 📓 Jupyter Notebook での探索（notebooks/experiment.ipynb）
# ここで試行錯誤
import pandas as pd
from sklearn.linear_model import LinearRegression

df = pd.read_csv('../data/cinema.csv')
X = df[['SNS1', 'SNS2']]
y = df['sales']

model = LinearRegression()
model.fit(X, y)
score = model.score(X, y)
print(f"R²: {score}")  # 結果を確認

# ↓ 動作確認できたら本番コードへ移行

# 📝 本番コード（src/ml/cinema_predictor.py）
class CinemaPredictor:
    def train(self, X, y):
        self.model = LinearRegression()
        self.model.fit(X, y)
        return self.model.score(X, y)

# ✅ テストコード（test/test_cinema_predictor.py）
def test_model_training():
    predictor = CinemaPredictor()
    X = pd.DataFrame({'SNS1': [100, 200], 'SNS2': [300, 400]})
    y = pd.Series([1000, 2000])

    score = predictor.train(X, y)
    assert score > 0.9  # TDD でしっかり検証

この組み合わせの利点：

🔍 Jupyter Lab: 高速な試行錯誤、データの可視化
✅ TDD: 品質保証、リファクタリングの安全性
📦 本番コード: モジュール化、再利用性

📊 各章での Jupyter Notebook の活用

各章では、以下のような Jupyter Notebook を作成します：

4章（Iris）: notebook/iris_tutorial.ipynb
- データ探索
- 分類モデルの訓練
- 結果の可視化
5章（Cinema）: notebook/cinema_tutorial.ipynb
- 回帰問題の理解
- 特徴量の分析
- 予測結果の評価
6章・7章: 実践的な分析ノートブック

Jupyter Notebook はインタラクティブな学習ツールとして、本書の各章で積極的に活用していきます！

初回の動作確認テストを書こう

TDD の第一歩は、テストを書くこと から始まります。「いきなりテスト？実装じゃなくて？」そう、テストファーストがTDDの神髄です！

まずは環境が正しくセットアップできているか確認するテストを作りましょう。

test/test_basic.py を作成します：

"""基本的な環境確認テスト"""
import pytest
import pandas as pd
import sklearn
import numpy as np


def test_パッケージのインポート確認():
    """必要なパッケージが正しくインストールされているか確認"""
    assert pd is not None      # pandas がインポートできる
    assert sklearn is not None  # scikit-learn がインポートできる
    assert np is not None      # numpy がインポートできる


def test_pandasのバージョン確認():
    """pandas のバージョンが 1.0 以上であることを確認"""
    version = pd.__version__
    major_version = int(version.split('.')[0])
    assert major_version >= 1  # pandas 1.x 以降が必要


def test_scikit_learnのバージョン確認():
    """scikit-learn のバージョンが 1.0 以上であることを確認"""
    version = sklearn.__version__
    major_version = int(version.split('.')[0])
    assert major_version >= 1  # scikit-learn 1.x 以降が必要

テストを実行してみよう！

pytest test/test_basic.py -v

期待される結果:

test/test_basic.py::test_パッケージのインポート確認 PASSED           [ 33%]
test/test_basic.py::test_pandasのバージョン確認 PASSED                [ 66%]
test/test_basic.py::test_scikit_learnのバージョン確認 PASSED           [100%]

============================== 3 passed in 0.15s ==============================

全部 PASSED なら、環境構築は完璧です！🎉

pandas の基本操作を確認

機械学習では pandas でデータを扱うことが多いので、基本操作を確認しておきましょう：

class TestDataFrameBasics:
    """pandas DataFrame の基本操作テスト"""

    def test_DataFrameの作成(self):
        """DataFrame を作成できることを確認"""
        df = pd.DataFrame({'A': [1, 2, 3], 'B': [4, 5, 6]})
        assert len(df) == 3              # 3行のデータ
        assert list(df.columns) == ['A', 'B']  # 列名が正しい

    def test_欠損値の検出(self):
        """欠損値を正しく検出できることを確認"""
        df = pd.DataFrame({'A': [1, np.nan, 3]})
        assert df['A'].isnull().sum() == 1  # 1つ欠損値がある

    def test_欠損値の補完(self):
        """欠損値を平均値で補完できることを確認"""
        df = pd.DataFrame({'A': [1.0, np.nan, 3.0]})
        mean_value = df['A'].mean()  # 平均値を計算: (1 + 3) / 2 = 2.0
        df['A'] = df['A'].fillna(mean_value)  # 欠損値を平均値で埋める

        assert df['A'].isnull().sum() == 0  # 欠損値が0個
        assert df['A'].iloc[1] == 2.0       # 2番目の値が2.0に補完された

scikit-learn の基本操作を確認

次は scikit-learn の基本操作を確認します：

class TestScikitLearnBasics:
    """scikit-learn の基本操作テスト"""

    def test_train_test_splitの動作確認(self):
        """データ分割が正しく動作することを確認"""
        from sklearn.model_selection import train_test_split

        X = [[1, 2], [3, 4], [5, 6], [7, 8]]  # 特徴量データ
        y = [0, 1, 0, 1]                       # ラベルデータ

        # データを訓練用とテスト用に分割（50% ずつ）
        X_train, X_test, y_train, y_test = train_test_split(
            X, y, test_size=0.5, random_state=0
        )

        # 正しく分割されているか確認
        assert len(X_train) == 2  # 訓練データは2個
        assert len(X_test) == 2   # テストデータは2個
        assert len(y_train) == 2
        assert len(y_test) == 2

    def test_決定木モデルの作成(self):
        """決定木モデルを作成できることを確認"""
        from sklearn.tree import DecisionTreeClassifier

        model = DecisionTreeClassifier(max_depth=2)  # 深さ2の決定木
        assert model is not None
        assert model.max_depth == 2  # パラメータが正しく設定されている

テストの実行

それでは、作成したテストをすべて実行してみましょう！

# 📋 pytest による全テスト実行
uv run pytest test/test_basic.py -v

期待される出力:

test/test_basic.py::test_パッケージのインポート確認 PASSED                    [ 11%]
test/test_basic.py::test_pandasのバージョン確認 PASSED                        [ 22%]
test/test_basic.py::test_scikit_learnのバージョン確認 PASSED                  [ 33%]
test/test_basic.py::TestDataFrameBasics::test_DataFrameの作成 PASSED          [ 44%]
test/test_basic.py::TestDataFrameBasics::test_欠損値の検出 PASSED             [ 55%]
test/test_basic.py::TestDataFrameBasics::test_欠損値の補完 PASSED             [ 66%]
test/test_basic.py::TestScikitLearnBasics::test_train_test_splitの動作確認 PASSED [ 77%]
test/test_basic.py::TestScikitLearnBasics::test_決定木モデルの作成 PASSED     [ 88%]
test/test_basic.py::TestScikitLearnBasics::test_線形回帰モデルの作成 PASSED   [100%]

========================== 9 passed in 0.45s ==========================

全部 PASSED！ 🎊 これで機械学習を始める準備が整いました！

「カバレッジも確認したい！」という意欲的なあなたには、こちらのコマンドもおすすめです：

# 📊 カバレッジ付きでの実行（どれだけコードがテストされているか確認）
uv run pytest test/test_basic.py --cov=src --cov-report=term-missing

カバレッジレポートでは、テストがカバーしている範囲が表示されます。本格的な開発では、カバレッジ 80% 以上を目指すのが一般的ですよ！

品質管理ツールの動作確認

「テストは通ったけど、コードの品質は大丈夫？」そんな心配もありますよね。安心してください！本プロジェクトでは、自動的にコード品質をチェックするツールも導入しています。

🎨 Ruff によるコード品質チェック

Ruff は Python の超高速リンター＆フォーマッターです。Rust で書かれているので、従来のツールより 10-100 倍速く動作します！

# コードの問題点をチェック
uv run ruff check .

# コードを自動的にきれいに整形
uv run ruff format .

期待される出力:

All checks passed! ✨

この一言が出れば、あなたのコードは Python の標準的なコーディング規約に従っています！素晴らしい！🎉

🔍 mypy による型チェック

mypy は Python の型ヒントをチェックするツールです。「型ヒント？それって何？」という方も、実際に使ってみればすぐにわかります！

test/test_basic.py に型ヒント付きのテスト関数を追加してみましょう：

import pytest
import pandas as pd
from typing import List  # 型ヒント用のインポート


def test_型ヒント付き関数() -> None:
    """型ヒントが正しく機能することを確認"""
    data: List[int] = [1, 2, 3, 4, 5]  # data は整数のリストという意味
    assert len(data) == 5              # 要素数が 5 個であることを確認

型ヒントをチェックしてみます：

# mypy による型チェック実行
uv run mypy test/test_basic.py

期待される出力:

Success: no issues found in 1 source file ✅

型チェックが通れば、型に関するバグを事前に防げます！これも重要な品質保証の一つですね。

🔄 TDD サイクルの体験

「TDD って実際どうやるの？」そう思いますよね。ここで、TDD の神髄である Red-Green-Refactor サイクルを実際に体験してみましょう！

簡単な DataLoader クラスを例に、TDD の流れを体験します。

🔴 Red: まず失敗するテストを書く

「え？失敗するテストを書くの？」 そうです！TDD では、実装よりも先にテストを書きます。これが成功への近道なんです。

test/test_data_loader.py を作成します：

"""データローダーのテスト（TDD サイクル例）"""
import pytest
import pandas as pd
from src.ml.data_loader import DataLoader  # まだ存在しないモジュールをインポート


class TestDataLoader:
    """DataLoader クラスのテスト"""

    def test_CSVファイルを読み込める(self):
        """CSV ファイルを DataFrame として読み込めることを確認"""
        loader = DataLoader()                        # DataLoader のインスタンス作成
        df = loader.load_csv('data/iris.csv')        # CSV ファイルを読み込む

        assert df is not None                        # データが読み込まれている
        assert isinstance(df, pd.DataFrame)          # DataFrame 型である
        assert len(df) > 0                           # データが空でない

テストを実行してみましょう：

uv run pytest test/test_data_loader.py -v

期待される出力（失敗）:

ModuleNotFoundError: No module named 'src.ml.data_loader'
❌ FAILED

失敗しました！ でも、これは正しい失敗です！これが TDD の第一歩、Red（赤） の状態です。🔴

🟢 Green: テストを通す最小限の実装

次に、このテストを通すための最小限のコードを書きます。「最小限」がポイントです！

まず、必要なディレクトリを作成：

mkdir -p src/ml
touch src/ml/__init__.py

そして、src/ml/data_loader.py を作成：

"""データローダーモジュール"""
import pandas as pd


class DataLoader:
    """CSV データを読み込むクラス"""

    def load_csv(self, file_path: str) -> pd.DataFrame:
        """CSV ファイルを読み込む

        Args:
            file_path: CSV ファイルのパス

        Returns:
            読み込んだ DataFrame
        """
        return pd.read_csv(file_path)  # シンプル！pandas におまかせ

テストを再実行してみましょう：

uv run pytest test/test_data_loader.py -v

期待される出力（成功）:

test/test_data_loader.py::TestDataLoader::test_CSVファイルを読み込める PASSED [100%]
========================== 1 passed in 0.12s ==========================
✅ PASSED

テストが通りました！ これが TDD の第二歩、Green（緑） の状態です！🟢

この瞬間、とても嬉しいですよね！小さな成功体験を積み重ねることが、TDD の醍醐味です。

🔧 Refactor: コードの改善

「テストは通ったけど、これで本当に大丈夫？」良い疑問です！TDD の第三歩、Refactor（リファクタリング） では、テストを壊さずにコードを改善 します。

現在のコードには問題があります。存在しないファイルを読み込もうとしたり、空のパスを指定したりすると、わかりにくいエラーが出てしまいます。これを改善しましょう！

まずテストを追加 します（これも TDD です！）

test/test_data_loader.py の TestDataLoader クラスに追加：

def test_存在しないファイルの処理(self):
    """存在しないファイルを指定した場合に適切なエラーを返すことを確認"""
    loader = DataLoader()

    # pytest.raises で「このエラーが発生することを期待」と宣言
    with pytest.raises(FileNotFoundError):
        loader.load_csv('data/non_existent.csv')  # わざと存在しないファイルを指定


def test_空のファイルパスの処理(self):
    """空のファイルパスを指定した場合にエラーを返すことを確認"""
    loader = DataLoader()

    with pytest.raises(ValueError):  # 空のパスは ValueError
        loader.load_csv('')

次に、実装を改善します：

src/ml/data_loader.py をリファクタリング：

"""データローダーモジュール"""
import os
import pandas as pd
from typing import Optional


class DataLoader:
    """CSV データを読み込むクラス"""

    def load_csv(self, file_path: str) -> pd.DataFrame:
        """CSV ファイルを読み込む

        Args:
            file_path: CSV ファイルのパス

        Returns:
            読み込んだ DataFrame

        Raises:
            ValueError: ファイルパスが空の場合
            FileNotFoundError: ファイルが存在しない場合
        """
        # バリデーション：空のパスはダメ！
        if not file_path:
            raise ValueError("File path cannot be empty")

        # バリデーション：ファイルが存在するか確認
        if not os.path.exists(file_path):
            raise FileNotFoundError(f"File not found: {file_path}")

        # すべてのチェックをパスしたらデータを読み込む
        return pd.read_csv(file_path)

テストを再実行して、すべて通ることを確認します：

uv run pytest test/test_data_loader.py -v

期待される出力:

test/test_data_loader.py::TestDataLoader::test_CSVファイルを読み込める PASSED           [ 33%]
test/test_data_loader.py::TestDataLoader::test_存在しないファイルの処理 PASSED         [ 66%]
test/test_data_loader.py::TestDataLoader::test_空のファイルパスの処理 PASSED           [100%]
========================== 3 passed in 0.15s ==========================

全部 PASSED！ 🎉

これで、TDD の Red → Green → Refactor サイクルを一周しました！

🔴 Red: 失敗するテストを書く
🟢 Green: テストを通す最小限の実装
🔧 Refactor: テストを保ちながらコードを改善

このサイクルを繰り返すことで、安全に、確実に、品質の高いコードを作り上げていくのが TDD です！

📊 サンプルデータの準備

「機械学習って、まずデータがないと始まらないんでしょ？」その通りです！

本チュートリアルでは、機械学習の世界で最も有名な Iris（アヤメ）データセットを使います。アヤメの花びらと萼（がく）の大きさから、アヤメの種類を分類する問題です。

まず、data ディレクトリを作成します：

mkdir -p data

そして、data/iris.csv を作成します（実際には 150 行のデータがありますが、ここでは一部を抜粋）：

sepal_length,sepal_width,petal_length,petal_width,species
5.1,3.5,1.4,0.2,setosa
4.9,3.0,1.4,0.2,setosa
7.0,3.2,4.7,1.4,versicolor
6.4,3.2,4.5,1.5,versicolor
6.3,3.3,6.0,2.5,virginica
5.8,2.7,5.1,1.9,virginica

データの意味：

🌸 sepal_length: 萼（がく）の長さ（cm）
🌸 sepal_width: 萼（がく）の幅（cm）
🌺 petal_length: 花びらの長さ（cm）
🌺 petal_width: 花びらの幅（cm）
🏷️ species: アヤメの種類（setosa、versicolor、virginica の 3 種類）

このデータを使って、花びらや萼のサイズから、どの種類のアヤメかを予測するモデルを作ります！

データが正しく読み込めるか、テストで確認しましょう：

test/test_data_loader.py に追加：

def test_Irisデータセットの読み込み():
    """Iris データセットを正しく読み込めることを確認"""
    loader = DataLoader()
    df = loader.load_csv('data/iris.csv')  # Iris データ読み込み

    # 📋 列名の確認：期待する列がすべて揃っているか？
    expected_columns = ['sepal_length', 'sepal_width', 'petal_length',
                       'petal_width', 'species']
    assert list(df.columns) == expected_columns

    # 🔍 データ型の確認：数値は float、種類は文字列（object）
    assert df['sepal_length'].dtype == 'float64'
    assert df['species'].dtype == 'object'

    # 🌸 種類の確認：3 種類のアヤメがすべて含まれているか？
    species = df['species'].unique()  # ユニークな値を取得
    assert len(species) == 3          # 3 種類
    assert 'setosa' in species        # setosa が含まれる
    assert 'versicolor' in species    # versicolor が含まれる
    assert 'virginica' in species     # virginica が含まれる

テストを実行してみましょう：

uv run pytest test/test_data_loader.py::test_Irisデータセットの読み込み -v

PASSED なら、データの準備は完璧です！🎉

これで、２章「開発環境のセットアップ」は完了です！お疲れさまでした！

次の章からは、いよいよ機械学習モデルの実装に入ります。ワクワクしてきませんか？😊

📊 ２章の技術的成果

２章で何を学び、何を達成したか振り返ってみましょう！

✅ 完成した機能

お疲れさまでした！２章では以下の機能を実装しました：

✅ 現代的 Python 開発環境のセットアップ - uv、Ruff、mypy、pytest
✅ プロジェクト構造の確立 - src/、test/、data/ の整備
✅ 基本的なテストスイートの作成 - 12 個のテストケース
✅ TDD サイクルの実践 - Red-Green-Refactor を体験
✅ DataLoader の実装 - CSV ファイル読み込み機能
✅ 品質管理ツールの設定と確認 - コード品質の自動チェック

📈 定量的成果

数字で見ると、こんなに進歩しました！

指標	実績
🧪 テストケース	12 個
📊 コードカバレッジ	100%（data_loader.py）
🔤 型ヒント使用率	100%
✨ Ruff チェック	全て通過
✅ mypy チェック	エラー 0 件

🎓 習得したスキル

1. 🛠️ 開発環境スキル

uv による高速パッケージ管理
Ruff による統合品質管理
mypy による型安全性確保
pytest による自動テスト

2. 🔄 TDD スキル

Red-Green-Refactor サイクルの実践
テストファースト開発の習慣化
エッジケースを考慮したテスト設計

3. 🐍 Python スキル

型ヒントの活用
例外処理の実装
モジュール構造の設計

4. 🤖 機械学習基礎知識

分類問題と回帰問題の理解
データ前処理の重要性認識
モデル評価の必要性理解

🚀 次の章への準備

２章では、開発環境を整えました！次の４章（３章は理論補足なのでスキップ可）では、いよいよ実際の機械学習モデルを実装します！

これから実装する内容：

🌸 Iris 分類モデルの完全実装 - アヤメを分類するモデル
🌳 決定木アルゴリズムの理解 - 機械学習の基本アルゴリズム
🔧 データ前処理パイプラインの構築 - データをきれいにする
💾 モデルの保存と読み込み - 学習したモデルを再利用

準備はできましたか？それでは、次の章で実際に機械学習モデルを作っていきましょう！🎉

３章機械学習の基礎理論（補足）

「２章で環境は整ったけど、機械学習って実際どうやって進めるの？」そんな疑問に答えるため、この章では機械学習の基本的な考え方を学びます。

📋 機械学習のワークフロー

機械学習プロジェクトは、だいたい以下のような流れで進めます：

重要なポイント：

📊 データが命：良いモデルは良いデータから生まれます
🔄 反復改善：一度でうまくいくことは稀です。試行錯誤が大切
📈 評価が大事：訓練データでの性能だけでなく、未知のデータでの性能を確認

🎯 分類問題と回帰問題の違い

機械学習の問題は大きく 2 つに分けられます。違いを理解することが重要です！

🏷️ 分類問題（Classification）

「どのカテゴリに属するか？」を予測する問題

目的: カテゴリ（クラス）を予測
出力: 離散値（例: setosa、versicolor、virginica）
評価指標: 正解率、適合率、再現率、F1 スコア
アルゴリズム例: 決定木、ロジスティック回帰、SVM

具体例：

🌸 アヤメの種類を分類（本チュートリアル）
📧 メールがスパムかどうかを判定
🖼️ 画像に写っているものが猫か犬かを判定

📊 回帰問題（Regression）

「どのくらいの値になるか？」を予測する問題

目的: 連続値を予測
出力: 数値（例: 興行収入 10000 万円）
評価指標: 平均絶対誤差（MAE）、平均二乗誤差（MSE）、決定係数（R²）
アルゴリズム例: 線形回帰、リッジ回帰、ランダムフォレスト

具体例：

💰 映画の興行収入を予測（本チュートリアル）
🏠 不動産の価格を予測
🌡️ 明日の気温を予測

⚠️ モデル評価の重要性

機械学習で最も重要なのは、訓練データで学習したモデルが、未知のデータに対してどれだけ性能を発揮できるかです。

「訓練データでは完璧なのに、実際のデータでは全然ダメ...」これが 過学習（Overfitting） です！

過学習（Overfitting）の問題

過学習を実際にテストで確認してみましょう：

def test_過学習の検出():
    """訓練データとテストデータの性能差で過学習を検出"""
    from sklearn.tree import DecisionTreeClassifier
    from sklearn.model_selection import train_test_split

    # 📊 サンプルデータを作成
    X = [[i, i*2] for i in range(100)]          # 特徴量
    y = [0 if i < 50 else 1 for i in range(100)]  # ラベル（0 or 1）

    # データを訓練用（70%）とテスト用（30%）に分割
    X_train, X_test, y_train, y_test = train_test_split(
        X, y, test_size=0.3, random_state=0
    )

    # ❌ 深すぎる決定木（過学習しやすい）
    model_overfit = DecisionTreeClassifier(max_depth=50)  # 深さ 50 は深すぎ！
    model_overfit.fit(X_train, y_train)

    # ✅ 適切な深さの決定木
    model_good = DecisionTreeClassifier(max_depth=3)  # 深さ 3 が適切
    model_good.fit(X_train, y_train)

    # 📈 訓練データでの性能を測定
    train_score_overfit = model_overfit.score(X_train, y_train)  # 過学習モデル
    train_score_good = model_good.score(X_train, y_train)        # 適切なモデル

    # 📉 テストデータでの性能を測定（こっちが重要！）
    test_score_overfit = model_overfit.score(X_test, y_test)  # 過学習モデル
    test_score_good = model_good.score(X_test, y_test)        # 適切なモデル

    # 🔍 過学習の検出：訓練とテストで大きな性能差があると過学習
    overfit_gap = train_score_overfit - test_score_overfit  # 過学習モデルの性能差
    good_gap = train_score_good - test_score_good           # 適切なモデルの性能差

    # 過学習モデルの方が性能差が大きいことを確認
    assert overfit_gap > good_gap

このテストから学べること：

📚 訓練データでの高性能 ≠ 良いモデル
🎯 未知のデータでの性能こそが本当の実力
⚖️ 適切なモデルの複雑さを選ぶことが重要

４章 Iris 分類モデル（分類問題の基礎）

さあ、いよいよ実際の機械学習モデルを作ります！「難しそう...」と思いましたか？大丈夫です！TDD で一歩ずつ進めていきましょう。

🎯 この章の学習目標

この章では、以下のスキルを習得します：

🌸 基本的な分類モデルの構築 - アヤメを分類するモデルを作る
🔄 テスト駆動開発の基礎習得 - Red-Green-Refactor を実践
🛠️ scikit-learn の基本 API 理解 - fit()、predict() の使い方
🔧 データ前処理パイプラインの構築 - データを機械学習用に整形

📊 Iris データセットの理解

「Iris データセットって何？」と思いますよね。これは、機械学習の世界で最も有名な教材用データセットです。統計学者フィッシャーが 1936 年に発表した、アヤメの花のデータです。

データの特徴

項目	内容
🔢 サンプル数	150 件（各種類 50 件ずつ）
📊 特徴量数	4 つ（全て連続値）
🏷️ クラス数	3 つ（setosa、versicolor、virginica）
✨ 欠損値	なし（クリーンなデータ！）

「欠損値なし！」これは初心者にとって嬉しいポイントです。実際のデータは欠損値だらけですが、まずはシンプルなデータで学びましょう。

データ詳細

それぞれの列（カラム）の意味を理解しましょう：

列名	内容	単位	値の範囲
🌸 sepal_length	がく片の長さ	cm	4.3 - 7.9
🌸 sepal_width	がく片の幅	cm	2.0 - 4.4
🌺 petal_length	花びらの長さ	cm	1.0 - 6.9
🌺 petal_width	花びらの幅	cm	0.1 - 2.5
🏷️ species	アヤメの種類	-	setosa、versicolor、virginica

この 4 つの特徴量（長さと幅）から、アヤメが 3 種類のうちどれかを予測するのが、この章の目標です！

🔨 TDD による段階的実装

「いきなり全部作るの？」いいえ！TDD では小さなステップで一歩ずつ進めます。まずはクラスの初期化から始めましょう。

ステップ 1: クラスの初期化テスト

🔴 Red: まず失敗するテストを書く

test/test_iris_classifier.py を作成します：

"""Iris 分類器のテスト"""
import pytest
import pandas as pd
import numpy as np
from src.ml.iris_classifier import IrisClassifier  # まだ存在しないモジュール


class TestIrisClassifierInit:
    """IrisClassifier の初期化テスト"""

    def test_デフォルトパラメータでの初期化(self):
        """デフォルトパラメータで初期化できることを確認"""
        classifier = IrisClassifier()  # 分類器を作成

        assert classifier is not None        # インスタンスが作られた
        assert classifier.model is None      # まだモデルは訓練されていない
        assert classifier.max_depth == 2     # デフォルトの深さは 2

    def test_カスタムパラメータでの初期化(self):
        """カスタムパラメータで初期化できることを確認"""
        classifier = IrisClassifier(max_depth=5)  # 深さ 5 を指定

        assert classifier.max_depth == 5  # 指定した値が設定される

    def test_無効なmax_depthの拒否(self):
        """無効な max_depth を拒否することを確認"""
        # 負の値はダメ！
        with pytest.raises(ValueError):
            IrisClassifier(max_depth=-1)

        # 0 もダメ！
        with pytest.raises(ValueError):
            IrisClassifier(max_depth=0)

テストを実行してみましょう（Red を期待）：

uv run pytest test/test_iris_classifier.py::TestIrisClassifierInit -v

期待される出力（失敗）:

ModuleNotFoundError: No module named 'src.ml.iris_classifier'
❌ FAILED

失敗しました！ これが正しい TDD の第一歩です。🔴

🟢 Green: テストを通す最小限の実装

次に、テストを通すための最小限のコードを書きます。

src/ml/iris_classifier.py を作成：

"""Iris 分類器モジュール"""
from typing import Optional, Tuple
import pandas as pd
import numpy as np
from sklearn import tree
from sklearn.model_selection import train_test_split


class IrisClassifier:
    """Iris データセットを分類する決定木モデル"""

    def __init__(self, max_depth: int = 2) -> None:
        """初期化

        Args:
            max_depth: 決定木の最大深さ（デフォルト: 2）

        Raises:
            ValueError: max_depth が 1 未満の場合
        """
        if max_depth < 1:
            raise ValueError("max_depth must be at least 1")

        self.max_depth = max_depth
        self.model: Optional[tree.DecisionTreeClassifier] = None

テストを実行（Green）：

uv run pytest test/test_iris_classifier.py::TestIrisClassifierInit -v

# 出力例：
# test/test_iris_classifier.py::TestIrisClassifierInit::test_デフォルトパラメータでの初期化 PASSED
# test/test_iris_classifier.py::TestIrisClassifierInit::test_カスタムパラメータでの初期化 PASSED
# test/test_iris_classifier.py::TestIrisClassifierInit::test_無効なmax_depthの拒否 PASSED
# =========== 3 passed in 0.18s ===========

ステップ 2: データ読み込みと前処理

Red: テストを書く

class TestIrisClassifierDataLoading:
    """データ読み込みのテスト"""

    def test_CSVファイルからのデータ読み込み(self):
        """CSV ファイルからデータを読み込めることを確認"""
        classifier = IrisClassifier()
        X, y = classifier.load_data('data/iris.csv')

        assert X is not None
        assert y is not None
        assert isinstance(X, pd.DataFrame)
        assert isinstance(y, pd.Series)

    def test_特徴量の列数確認(self):
        """特徴量が 4 列であることを確認"""
        classifier = IrisClassifier()
        X, y = classifier.load_data('data/iris.csv')

        assert X.shape[1] == 4
        assert list(X.columns) == [
            'sepal_length', 'sepal_width', 'petal_length', 'petal_width'
        ]

    def test_ラベルのユニーク数確認(self):
        """ラベルが 3 種類であることを確認"""
        classifier = IrisClassifier()
        X, y = classifier.load_data('data/iris.csv')

        unique_species = y.unique()
        assert len(unique_species) == 3
        assert 'setosa' in unique_species
        assert 'versicolor' in unique_species
        assert 'virginica' in unique_species

    def test_欠損値の処理(self):
        """欠損値が適切に処理されることを確認"""
        # テスト用に欠損値を含むデータを作成
        import tempfile
        import os

        test_data = """sepal_length,sepal_width,petal_length,petal_width,species
5.1,3.5,1.4,0.2,setosa
,3.0,1.4,0.2,setosa
7.0,,4.7,1.4,versicolor"""

        with tempfile.NamedTemporaryFile(mode='w', delete=False, suffix='.csv') as f:
            f.write(test_data)
            temp_path = f.name

        try:
            classifier = IrisClassifier()
            X, y = classifier.load_data(temp_path)

            # 欠損値が補完されていることを確認
            assert X.isnull().sum().sum() == 0
        finally:
            os.unlink(temp_path)

Green: データ読み込み機能の実装

def load_data(self, file_path: str) -> Tuple[pd.DataFrame, pd.Series]:
    """CSV ファイルからデータを読み込む

    Args:
        file_path: CSV ファイルのパス

    Returns:
        特徴量 DataFrame と正解ラベル Series のタプル

    Raises:
        FileNotFoundError: ファイルが存在しない場合
        ValueError: データの形式が不正な場合
    """
    # ファイルの存在確認
    import os
    if not os.path.exists(file_path):
        raise FileNotFoundError(f"File not found: {file_path}")

    # データの読み込み
    df = pd.read_csv(file_path)

    # 必要な列の存在確認
    required_columns = ['sepal_length', 'sepal_width',
                       'petal_length', 'petal_width', 'species']
    missing_columns = set(required_columns) - set(df.columns)
    if missing_columns:
        raise ValueError(f"Missing columns: {missing_columns}")

    # 特徴量列
    feature_columns = ['sepal_length', 'sepal_width',
                      'petal_length', 'petal_width']

    # 欠損値を平均値で補完
    for col in feature_columns:
        if df[col].isnull().any():
            mean_value = df[col].mean()
            df[col] = df[col].fillna(mean_value)

    # 特徴量と正解ラベルの分割
    X = df[feature_columns]
    y = df['species']

    return X, y

Refactor: ヘルパーメソッドの抽出

def _validate_dataframe(self, df: pd.DataFrame) -> None:
    """データフレームの妥当性を検証

    Args:
        df: 検証する DataFrame

    Raises:
        ValueError: 必要な列が不足している場合
    """
    required_columns = ['sepal_length', 'sepal_width',
                       'petal_length', 'petal_width', 'species']
    missing_columns = set(required_columns) - set(df.columns)
    if missing_columns:
        raise ValueError(f"Missing columns: {missing_columns}")


def _fill_missing_values(self, df: pd.DataFrame,
                        columns: list) -> pd.DataFrame:
    """欠損値を平均値で補完

    Args:
        df: 対象の DataFrame
        columns: 補完する列のリスト

    Returns:
        補完後の DataFrame
    """
    df_filled = df.copy()
    for col in columns:
        if df_filled[col].isnull().any():
            mean_value = df_filled[col].mean()
            df_filled[col] = df_filled[col].fillna(mean_value)
    return df_filled


def load_data(self, file_path: str) -> Tuple[pd.DataFrame, pd.Series]:
    """CSV ファイルからデータを読み込む（リファクタリング後）"""
    import os
    if not os.path.exists(file_path):
        raise FileNotFoundError(f"File not found: {file_path}")

    df = pd.read_csv(file_path)
    self._validate_dataframe(df)

    feature_columns = ['sepal_length', 'sepal_width',
                      'petal_length', 'petal_width']

    df = self._fill_missing_values(df, feature_columns)

    X = df[feature_columns]
    y = df['species']

    return X, y

ステップ 3: モデルの訓練

Red: テストを書く

class TestIrisClassifierTraining:
    """モデル訓練のテスト"""

    def test_モデルの訓練(self):
        """モデルを訓練できることを確認"""
        classifier = IrisClassifier()
        X_train = pd.DataFrame({
            'sepal_length': [5.1, 4.9, 7.0],
            'sepal_width': [3.5, 3.0, 3.2],
            'petal_length': [1.4, 1.4, 4.7],
            'petal_width': [0.2, 0.2, 1.4]
        })
        y_train = pd.Series(['setosa', 'setosa', 'versicolor'])

        classifier.train(X_train, y_train)

        assert classifier.model is not None

    def test_訓練済みモデルの属性確認(self):
        """訓練済みモデルが適切な属性を持つことを確認"""
        classifier = IrisClassifier(max_depth=3)
        X_train = pd.DataFrame({
            'sepal_length': [5.1, 4.9, 7.0],
            'sepal_width': [3.5, 3.0, 3.2],
            'petal_length': [1.4, 1.4, 4.7],
            'petal_width': [0.2, 0.2, 1.4]
        })
        y_train = pd.Series(['setosa', 'setosa', 'versicolor'])

        classifier.train(X_train, y_train)

        assert classifier.model.max_depth == 3
        assert hasattr(classifier.model, 'classes_')

    def test_空のデータでの訓練拒否(self):
        """空のデータでの訓練を拒否することを確認"""
        classifier = IrisClassifier()
        X_train = pd.DataFrame()
        y_train = pd.Series(dtype=str)

        with pytest.raises(ValueError):
            classifier.train(X_train, y_train)

    def test_特徴量とラベルの数が不一致の拒否(self):
        """特徴量とラベルの数が一致しない場合を拒否"""
        classifier = IrisClassifier()
        X_train = pd.DataFrame({
            'sepal_length': [5.1, 4.9],
            'sepal_width': [3.5, 3.0],
            'petal_length': [1.4, 1.4],
            'petal_width': [0.2, 0.2]
        })
        y_train = pd.Series(['setosa'])  # 数が一致しない

        with pytest.raises(ValueError):
            classifier.train(X_train, y_train)

Green: 訓練機能の実装

def train(self, X_train: pd.DataFrame, y_train: pd.Series) -> None:
    """モデルを訓練する

    Args:
        X_train: 訓練用特徴量
        y_train: 訓練用正解ラベル

    Raises:
        ValueError: データが空、または特徴量とラベルの数が不一致の場合
    """
    # データの妥当性チェック
    if len(X_train) == 0 or len(y_train) == 0:
        raise ValueError("Training data cannot be empty")

    if len(X_train) != len(y_train):
        raise ValueError(
            f"X_train and y_train must have the same length: "
            f"{len(X_train)} != {len(y_train)}"
        )

    # 決定木モデルの作成
    self.model = tree.DecisionTreeClassifier(
        max_depth=self.max_depth,
        random_state=0  # 再現性のため
    )

    # モデルの訓練
    self.model.fit(X_train, y_train)

ステップ 4: 予測機能

Red: テストを書く

class TestIrisClassifierPrediction:
    """予測機能のテスト"""

    @pytest.fixture
    def trained_classifier(self):
        """訓練済みの分類器を返す fixture"""
        classifier = IrisClassifier()
        X_train = pd.DataFrame({
            'sepal_length': [5.1, 4.9, 7.0, 6.4],
            'sepal_width': [3.5, 3.0, 3.2, 3.2],
            'petal_length': [1.4, 1.4, 4.7, 4.5],
            'petal_width': [0.2, 0.2, 1.4, 1.5]
        })
        y_train = pd.Series(['setosa', 'setosa', 'versicolor', 'versicolor'])
        classifier.train(X_train, y_train)
        return classifier

    def test_単一サンプルの予測(self, trained_classifier):
        """単一サンプルを予測できることを確認"""
        X_test = pd.DataFrame({
            'sepal_length': [5.0],
            'sepal_width': [3.5],
            'petal_length': [1.3],
            'petal_width': [0.3]
        })

        predictions = trained_classifier.predict(X_test)

        assert len(predictions) == 1
        assert predictions[0] in ['setosa', 'versicolor', 'virginica']

    def test_複数サンプルの予測(self, trained_classifier):
        """複数サンプルを予測できることを確認"""
        X_test = pd.DataFrame({
            'sepal_length': [5.0, 7.0],
            'sepal_width': [3.5, 3.2],
            'petal_length': [1.3, 4.7],
            'petal_width': [0.3, 1.4]
        })

        predictions = trained_classifier.predict(X_test)

        assert len(predictions) == 2

    def test_未訓練モデルでの予測拒否(self):
        """未訓練モデルでの予測を拒否することを確認"""
        classifier = IrisClassifier()
        X_test = pd.DataFrame({
            'sepal_length': [5.0],
            'sepal_width': [3.5],
            'petal_length': [1.3],
            'petal_width': [0.3]
        })

        with pytest.raises(ValueError):
            classifier.predict(X_test)

Green: 予測機能の実装

def predict(self, X_test: pd.DataFrame) -> np.ndarray:
    """予測を実行する

    Args:
        X_test: テスト用特徴量

    Returns:
        予測されたクラスラベルの配列

    Raises:
        ValueError: モデルが未訓練の場合
    """
    if self.model is None:
        raise ValueError("Model has not been trained yet")

    return self.model.predict(X_test)

ステップ 5: モデル評価

Red: テストを書く

class TestIrisClassifierEvaluation:
    """モデル評価のテスト"""

    @pytest.fixture
    def trained_classifier(self):
        """訓練済みの分類器"""
        classifier = IrisClassifier()
        classifier.load_data('data/iris.csv')
        X, y = classifier.load_data('data/iris.csv')
        classifier.train(X, y)
        return classifier

    def test_正解率の計算(self, trained_classifier):
        """正解率を計算できることを確認"""
        X_test = pd.DataFrame({
            'sepal_length': [5.1, 7.0],
            'sepal_width': [3.5, 3.2],
            'petal_length': [1.4, 4.7],
            'petal_width': [0.2, 1.4]
        })
        y_test = pd.Series(['setosa', 'versicolor'])

        accuracy = trained_classifier.evaluate(X_test, y_test)

        assert 0.0 <= accuracy <= 1.0

    def test_完全一致時の正解率(self):
        """全て正解の場合に正解率が 1.0 になることを確認"""
        classifier = IrisClassifier()
        X_train = pd.DataFrame({
            'sepal_length': [5.1, 7.0],
            'sepal_width': [3.5, 3.2],
            'petal_length': [1.4, 4.7],
            'petal_width': [0.2, 1.4]
        })
        y_train = pd.Series(['setosa', 'versicolor'])
        classifier.train(X_train, y_train)

        # 訓練データと同じデータでテスト（必ず正解）
        accuracy = classifier.evaluate(X_train, y_train)

        assert accuracy == 1.0

Green: 評価機能の実装

def evaluate(self, X_test: pd.DataFrame, y_test: pd.Series) -> float:
    """モデルの性能を評価する

    Args:
        X_test: テスト用特徴量
        y_test: テスト用正解ラベル

    Returns:
        正解率（0.0 〜 1.0）

    Raises:
        ValueError: モデルが未訓練の場合
    """
    if self.model is None:
        raise ValueError("Model has not been trained yet")

    return self.model.score(X_test, y_test)

ステップ 6: モデルの保存と読み込み

Red: テストを書く

class TestIrisClassifierPersistence:
    """モデルの永続化テスト"""

    def test_モデルの保存(self, trained_classifier, tmp_path):
        """訓練済みモデルを保存できることを確認"""
        model_path = tmp_path / "iris_model.pkl"

        trained_classifier.save_model(str(model_path))

        assert model_path.exists()

    def test_モデルの読み込み(self, tmp_path):
        """保存したモデルを読み込めることを確認"""
        # モデルを訓練して保存
        classifier1 = IrisClassifier()
        X_train = pd.DataFrame({
            'sepal_length': [5.1, 7.0],
            'sepal_width': [3.5, 3.2],
            'petal_length': [1.4, 4.7],
            'petal_width': [0.2, 1.4]
        })
        y_train = pd.Series(['setosa', 'versicolor'])
        classifier1.train(X_train, y_train)

        model_path = tmp_path / "iris_model.pkl"
        classifier1.save_model(str(model_path))

        # 新しいインスタンスでモデルを読み込み
        classifier2 = IrisClassifier()
        classifier2.load_model(str(model_path))

        assert classifier2.model is not None

    def test_保存したモデルでの予測一貫性(self, tmp_path):
        """保存前後で予測結果が一致することを確認"""
        # モデルを訓練
        classifier1 = IrisClassifier()
        X_train = pd.DataFrame({
            'sepal_length': [5.1, 7.0],
            'sepal_width': [3.5, 3.2],
            'petal_length': [1.4, 4.7],
            'petal_width': [0.2, 1.4]
        })
        y_train = pd.Series(['setosa', 'versicolor'])
        classifier1.train(X_train, y_train)

        # テストデータ
        X_test = pd.DataFrame({
            'sepal_length': [5.0],
            'sepal_width': [3.4],
            'petal_length': [1.5],
            'petal_width': [0.2]
        })

        # 保存前の予測
        pred_before = classifier1.predict(X_test)

        # モデルの保存と読み込み
        model_path = tmp_path / "iris_model.pkl"
        classifier1.save_model(str(model_path))

        classifier2 = IrisClassifier()
        classifier2.load_model(str(model_path))

        # 読み込み後の予測
        pred_after = classifier2.predict(X_test)

        assert np.array_equal(pred_before, pred_after)

Green: 永続化機能の実装

import pickle


def save_model(self, file_path: str) -> None:
    """訓練済みモデルをファイルに保存する

    Args:
        file_path: 保存先のファイルパス

    Raises:
        ValueError: モデルが未訓練の場合
    """
    if self.model is None:
        raise ValueError("No trained model to save")

    with open(file_path, 'wb') as f:
        pickle.dump(self.model, f)


def load_model(self, file_path: str) -> None:
    """保存されたモデルをファイルから読み込む

    Args:
        file_path: 読み込むファイルのパス

    Raises:
        FileNotFoundError: ファイルが存在しない場合
    """
    import os
    if not os.path.exists(file_path):
        raise FileNotFoundError(f"Model file not found: {file_path}")

    with open(file_path, 'rb') as f:
        self.model = pickle.load(f)

完全な実装例

すべての機能を統合した完全な IrisClassifier クラス：

src/ml/iris_classifier.py:

"""Iris 分類器モジュール"""
import os
import pickle
from typing import Optional, Tuple
import pandas as pd
import numpy as np
from sklearn import tree


class IrisClassifier:
    """Iris データセットを分類する決定木モデル

    Attributes:
        max_depth: 決定木の最大深さ
        model: 訓練済みの決定木モデル（未訓練時は None）
    """

    def __init__(self, max_depth: int = 2) -> None:
        """初期化

        Args:
            max_depth: 決定木の最大深さ（デフォルト: 2）

        Raises:
            ValueError: max_depth が 1 未満の場合
        """
        if max_depth < 1:
            raise ValueError("max_depth must be at least 1")

        self.max_depth = max_depth
        self.model: Optional[tree.DecisionTreeClassifier] = None

    def _validate_dataframe(self, df: pd.DataFrame) -> None:
        """データフレームの妥当性を検証

        Args:
            df: 検証する DataFrame

        Raises:
            ValueError: 必要な列が不足している場合
        """
        required_columns = ['sepal_length', 'sepal_width',
                           'petal_length', 'petal_width', 'species']
        missing_columns = set(required_columns) - set(df.columns)
        if missing_columns:
            raise ValueError(f"Missing columns: {missing_columns}")

    def _fill_missing_values(self, df: pd.DataFrame,
                            columns: list) -> pd.DataFrame:
        """欠損値を平均値で補完

        Args:
            df: 対象の DataFrame
            columns: 補完する列のリスト

        Returns:
            補完後の DataFrame
        """
        df_filled = df.copy()
        for col in columns:
            if df_filled[col].isnull().any():
                mean_value = df_filled[col].mean()
                df_filled[col] = df_filled[col].fillna(mean_value)
        return df_filled

    def load_data(self, file_path: str) -> Tuple[pd.DataFrame, pd.Series]:
        """CSV ファイルからデータを読み込む

        Args:
            file_path: CSV ファイルのパス

        Returns:
            特徴量 DataFrame と正解ラベル Series のタプル

        Raises:
            FileNotFoundError: ファイルが存在しない場合
            ValueError: データの形式が不正な場合
        """
        if not os.path.exists(file_path):
            raise FileNotFoundError(f"File not found: {file_path}")

        df = pd.read_csv(file_path)
        self._validate_dataframe(df)

        feature_columns = ['sepal_length', 'sepal_width',
                          'petal_length', 'petal_width']

        df = self._fill_missing_values(df, feature_columns)

        X = df[feature_columns]
        y = df['species']

        return X, y

    def train(self, X_train: pd.DataFrame, y_train: pd.Series) -> None:
        """モデルを訓練する

        Args:
            X_train: 訓練用特徴量
            y_train: 訓練用正解ラベル

        Raises:
            ValueError: データが空、または特徴量とラベルの数が不一致の場合
        """
        if len(X_train) == 0 or len(y_train) == 0:
            raise ValueError("Training data cannot be empty")

        if len(X_train) != len(y_train):
            raise ValueError(
                f"X_train and y_train must have the same length: "
                f"{len(X_train)} != {len(y_train)}"
            )

        self.model = tree.DecisionTreeClassifier(
            max_depth=self.max_depth,
            random_state=0
        )
        self.model.fit(X_train, y_train)

    def predict(self, X_test: pd.DataFrame) -> np.ndarray:
        """予測を実行する

        Args:
            X_test: テスト用特徴量

        Returns:
            予測されたクラスラベルの配列

        Raises:
            ValueError: モデルが未訓練の場合
        """
        if self.model is None:
            raise ValueError("Model has not been trained yet")

        return self.model.predict(X_test)

    def evaluate(self, X_test: pd.DataFrame, y_test: pd.Series) -> float:
        """モデルの性能を評価する

        Args:
            X_test: テスト用特徴量
            y_test: テスト用正解ラベル

        Returns:
            正解率（0.0 〜 1.0）

        Raises:
            ValueError: モデルが未訓練の場合
        """
        if self.model is None:
            raise ValueError("Model has not been trained yet")

        return self.model.score(X_test, y_test)

    def save_model(self, file_path: str) -> None:
        """訓練済みモデルをファイルに保存する

        Args:
            file_path: 保存先のファイルパス

        Raises:
            ValueError: モデルが未訓練の場合
        """
        if self.model is None:
            raise ValueError("No trained model to save")

        with open(file_path, 'wb') as f:
            pickle.dump(self.model, f)

    def load_model(self, file_path: str) -> None:
        """保存されたモデルをファイルから読み込む

        Args:
            file_path: 読み込むファイルのパス

        Raises:
            FileNotFoundError: ファイルが存在しない場合
        """
        if not os.path.exists(file_path):
            raise FileNotFoundError(f"Model file not found: {file_path}")

        with open(file_path, 'rb') as f:
            self.model = pickle.load(f)

実践例：Iris 分類モデルの訓練

実際にモデルを訓練して評価する完全な例：

script/train_iris.py:

"""Iris 分類モデルの訓練例"""
from sklearn.model_selection import train_test_split
from src.ml.iris_classifier import IrisClassifier


def main():
    """メイン処理"""
    # 分類器の作成
    classifier = IrisClassifier(max_depth=3)
    print("IrisClassifier を作成しました")

    # データの読み込み
    X, y = classifier.load_data('data/iris.csv')
    print(f"データを読み込みました: {len(X)} サンプル")

    # 訓練データとテストデータに分割
    X_train, X_test, y_train, y_test = train_test_split(
        X, y, test_size=0.3, random_state=0
    )
    print(f"訓練データ: {len(X_train)} サンプル")
    print(f"テストデータ: {len(X_test)} サンプル")

    # モデルの訓練
    classifier.train(X_train, y_train)
    print("モデルの訓練が完了しました")

    # 訓練データでの評価
    train_accuracy = classifier.evaluate(X_train, y_train)
    print(f"訓練データでの正解率: {train_accuracy:.4f}")

    # テストデータでの評価
    test_accuracy = classifier.evaluate(X_test, y_test)
    print(f"テストデータでの正解率: {test_accuracy:.4f}")

    # モデルの保存
    classifier.save_model('model/iris.pkl')
    print("モデルを model/iris.pkl に保存しました")

    # 予測例
    sample = X_test.iloc[:3]
    predictions = classifier.predict(sample)
    print("\n予測例:")
    for i, (idx, row) in enumerate(sample.iterrows()):
        print(f"サンプル {i+1}: {predictions[i]}")
        print(f"  - がく片: 長さ={row['sepal_length']}, 幅={row['sepal_width']}")
        print(f"  - 花弁: 長さ={row['petal_length']}, 幅={row['petal_width']}")


if __name__ == '__main__':
    main()

実行例：

uv run python script/train_iris.py

# 出力例：
# IrisClassifier を作成しました
# データを読み込みました: 150 サンプル
# 訓練データ: 105 サンプル
# テストデータ: 45 サンプル
# モデルの訓練が完了しました
# 訓練データでの正解率: 0.9810
# テストデータでの正解率: 0.9778
#
# 予測例:
# サンプル 1: versicolor
#   - がく片: 長さ=6.1, 幅=2.8
#   - 花弁: 長さ=4.7, 幅=1.2
# サンプル 2: setosa
#   - がく片: 長さ=5.7, 幅=3.8
#   - 花弁: 長さ=1.7, 幅=0.3
# サンプル 3: virginica
#   - がく片: 長さ=7.7, 幅=2.6
#   - 花弁: 長さ=6.9, 幅=2.3

📓 Jupyter Notebook での探索と視覚化

モデルの訓練が完了したら、Jupyter Notebook を使って結果を詳しく分析しましょう！対話的な環境で、データやモデルの挙動を深く理解できます。

🎯 この節の目的

データの分布を視覚的に理解する - 特徴量間の関係性を把握
モデルの性能を多角的に評価する - 混同行列、決定木の可視化
実験を素早く繰り返す - パラメータを変えて結果を比較

📝 Notebook の作成

プロジェクトルートで Jupyter Lab を起動します：

cd app/python/ml_tdd
uv run jupyter lab

notebook/ ディレクトリに新しいノートブック iris_exploration.ipynb を作成しましょう。

1️⃣ 環境セットアップとデータ読み込み

# セル 1: ライブラリのインポート
import sys
sys.path.append('..')  # プロジェクトルートを追加

import pandas as pd
import numpy as np
import matplotlib.pyplot as plt
import seaborn as sns
from sklearn.metrics import confusion_matrix, classification_report
from sklearn import tree

# 日本語フォント設定（Windows の場合）
plt.rcParams['font.sans-serif'] = ['MS Gothic']
plt.rcParams['axes.unicode_minus'] = False

# スタイル設定
sns.set_style("whitegrid")
sns.set_palette("husl")

print("✅ ライブラリの読み込み完了")

# セル 2: モデルとデータの読み込み
from src.ml.iris_classifier import IrisClassifier

# 分類器の初期化
classifier = IrisClassifier(max_depth=3)

# データの読み込み
X, y = classifier.load_data('data/iris.csv')

print(f"データ形状: X={X.shape}, y={y.shape}")
print(f"特徴量: {list(X.columns)}")
print(f"クラス: {y.unique()}")

2️⃣ データ分布の視覚化

# セル 3: 特徴量の分布をペアプロットで確認
# データフレームにラベルを追加
df_viz = X.copy()
df_viz['species'] = y

# ペアプロット（時間がかかる場合があります）
pairplot = sns.pairplot(
    df_viz,
    hue='species',
    diag_kind='hist',
    markers=['o', 's', 'D'],
    height=2.5
)
pairplot.fig.suptitle('Iris データセットの特徴量分布', y=1.02, fontsize=16)
plt.tight_layout()
plt.show()

print("✅ ペアプロット完成！各特徴量の関係性が見えますね")

このグラフから分かること：

petal_length と petal_width で種類がよく分離できる
setosa は他の2種と明確に区別できる
versicolor と virginica は一部重なる

# セル 4: 箱ひげ図で特徴量の分布を比較
fig, axes = plt.subplots(2, 2, figsize=(12, 10))
features = X.columns

for idx, feature in enumerate(features):
    ax = axes[idx // 2, idx % 2]
    df_viz.boxplot(column=feature, by='species', ax=ax)
    ax.set_title(f'{feature} の分布')
    ax.set_xlabel('種類')
    ax.set_ylabel(f'{feature} (cm)')

plt.suptitle('特徴量別の箱ひげ図', fontsize=16)
plt.tight_layout()
plt.show()

3️⃣ モデルの訓練と評価

# セル 5: モデルの訓練
from sklearn.model_selection import train_test_split

# データ分割
X_train, X_test, y_train, y_test = train_test_split(
    X, y, test_size=0.3, random_state=42
)

# 訓練
classifier.train(X_train, y_train)

# 予測
y_pred_train = classifier.predict(X_train)
y_pred_test = classifier.predict(X_test)

# 精度計算
train_accuracy = classifier.score(X_train, y_train)
test_accuracy = classifier.score(X_test, y_test)

print(f"訓練データ精度: {train_accuracy:.4f}")
print(f"テストデータ精度: {test_accuracy:.4f}")

4️⃣ 混同行列の視覚化

# セル 6: 混同行列の作成と可視化
cm = confusion_matrix(y_test, y_pred_test)

# ヒートマップで表示
plt.figure(figsize=(8, 6))
sns.heatmap(
    cm,
    annot=True,
    fmt='d',
    cmap='Blues',
    xticklabels=classifier.model.classes_,
    yticklabels=classifier.model.classes_
)
plt.title('混同行列 (Confusion Matrix)', fontsize=14)
plt.ylabel('実際のクラス')
plt.xlabel('予測クラス')
plt.tight_layout()
plt.show()

# 詳細レポート
print("\n分類レポート:")
print(classification_report(y_test, y_pred_test))

混同行列の読み方：

対角線上の値が大きい = 正しく分類できている
対角線外の値 = 誤分類（どのクラスを間違えやすいか分かる）

5️⃣ 決定木の可視化

# セル 7: 決定木構造の可視化
plt.figure(figsize=(20, 10))
tree.plot_tree(
    classifier.model,
    feature_names=X.columns,
    class_names=classifier.model.classes_,
    filled=True,
    rounded=True,
    fontsize=10
)
plt.title('決定木の構造', fontsize=16)
plt.tight_layout()
plt.show()

print("✅ 決定木の可視化完了！どの特徴量で分岐しているか見てみましょう")

決定木から学べること：

最初にどの特徴量で分岐するか（= 最も重要な特徴量）
各ノードでどのように分類が進むか
葉ノードの色の濃さ = その予測の確信度

6️⃣ 特徴量の重要度

# セル 8: 特徴量重要度の可視化
importances = classifier.model.feature_importances_
feature_importance_df = pd.DataFrame({
    'feature': X.columns,
    'importance': importances
}).sort_values('importance', ascending=False)

plt.figure(figsize=(10, 6))
sns.barplot(data=feature_importance_df, x='importance', y='feature')
plt.title('特徴量の重要度', fontsize=14)
plt.xlabel('重要度スコア')
plt.ylabel('特徴量名')
plt.tight_layout()
plt.show()

print("\n特徴量重要度:")
print(feature_importance_df)

7️⃣ パラメータ実験

# セル 9: 異なる max_depth での性能比較
depths = range(1, 10)
train_scores = []
test_scores = []

for depth in depths:
    clf = IrisClassifier(max_depth=depth)
    clf.train(X_train, y_train)

    train_scores.append(clf.score(X_train, y_train))
    test_scores.append(clf.score(X_test, y_test))

# 結果の可視化
plt.figure(figsize=(10, 6))
plt.plot(depths, train_scores, marker='o', label='訓練データ')
plt.plot(depths, test_scores, marker='s', label='テストデータ')
plt.xlabel('決定木の深さ (max_depth)')
plt.ylabel('正解率')
plt.title('max_depth による性能の変化')
plt.legend()
plt.grid(True, alpha=0.3)
plt.tight_layout()
plt.show()

# 最適な深さを見つける
optimal_depth = depths[np.argmax(test_scores)]
print(f"\n最適な max_depth: {optimal_depth}")
print(f"最高テスト精度: {max(test_scores):.4f}")

このグラフから分かること：

max_depth が小さすぎる = 学習不足（underfitting）
max_depth が大きすぎる = 過学習（overfitting）
テストデータの精度が最大になる点が最適

💡 Notebook 活用のポイント

✅ やること	❌ 避けること
データの分布を視覚的に確認	最初から完璧なコードを書こうとする
パラメータを変えて実験	すべてを Notebook で完結させる
気づきをマークダウンでメモ	グラフの意味を考えずに次へ進む
重要な発見を本番コードに反映	Notebook を散らかしたままにする

🔄 探索から本番コードへ

Notebook での発見を本番コードに反映する流れ：

Notebook で探索 → 最適な max_depth は 3 だと判明
テストに反映 → デフォルト値を検証するテストを追加
本番コードに反映 → IrisClassifier のデフォルトを更新
ドキュメント化 → README に最適パラメータを記載

# 発見: max_depth=3 が最適
# ↓
# test/test_iris_classifier.py に追加
def test_最適なデフォルトパラメータ(self):
    """最適な max_depth がデフォルト値として設定されている"""
    classifier = IrisClassifier()
    assert classifier.max_depth == 3  # Notebook で発見した最適値

📊 ４章の技術的成果

「ついに最初の機械学習モデルが完成しました！」お疲れさまでした！４章で何を達成したか、振り返ってみましょう。

✅ 完成した機能

４章では、以下の機能を実装しました：

✅ Iris 分類器クラスの完全実装 - アヤメを分類するモデル
✅ データ読み込みと前処理パイプライン - CSV から学習用データへ
✅ 決定木モデルの訓練機能 - データから学習
✅ 予測機能 - 新しいデータの種類を予測
✅ モデル評価機能 - 正解率を計算
✅ モデルの保存と読み込み機能 - 学習したモデルを再利用

📈 定量的成果

数字で見ると、こんなに達成しました！

指標	🎯 実績
🧪 テストケース	18 個
📊 コードカバレッジ	95%（iris_classifier.py）
🔤 型ヒント使用率	100%
🌸 モデル正解率	97.78%（テストデータ）
✨ Ruff チェック	全て通過
✅ mypy チェック	エラー 0 件

97.78% の正解率！ これはとても良い結果です！🎉

🎓 習得したスキル

1. 🔄 TDD スキル（発展）

✅ 複雑なクラスの段階的実装
✅ Fixture を活用したテストの効率化
✅ エッジケースの網羅的テスト

2. 🤖 機械学習スキル

✅ 決定木アルゴリズムの理解
✅ 訓練データとテストデータの分割
✅ モデル評価指標（正解率）の理解
✅ モデルの永続化（pickle）

3. 📊 データ処理スキル

✅ pandas による DataFrame 操作
✅ 欠損値の処理
✅ データの妥当性検証

4. 🏗️ ソフトウェア設計スキル

✅ 単一責任の原則（SRP）の適用
✅ ヘルパーメソッドによる責務分離
✅ 型ヒントによる契約の明示

決定木アルゴリズムの理解

決定木とは：
データを複数の条件分岐で分類するアルゴリズムです。

                [Root]
                  |
         petal_length <= 2.45?
         /                    \
       Yes                     No
        |                       |
    setosa            petal_width <= 1.75?
                     /                    \
                   Yes                     No
                    |                       |
              versicolor                virginica

max_depth パラメータの影響：

def test_max_depthと正解率の関係():
    """max_depth が正解率に与える影響を確認"""
    X, y = load_iris_data()
    X_train, X_test, y_train, y_test = train_test_split(
        X, y, test_size=0.3, random_state=0
    )

    results = []
    for depth in [1, 2, 3, 5, 10]:
        classifier = IrisClassifier(max_depth=depth)
        classifier.train(X_train, y_train)

        train_acc = classifier.evaluate(X_train, y_train)
        test_acc = classifier.evaluate(X_test, y_test)

        results.append({
            'depth': depth,
            'train_accuracy': train_acc,
            'test_accuracy': test_acc,
            'gap': train_acc - test_acc
        })

    # depth=2 あたりが適切（過学習を避ける）
    # depth が大きすぎると訓練データに過学習

🚀 次の章への準備

４章では、最初の機械学習モデルを作成しました！次の５章では、以下を実装します：

🎬 Cinema 興行収入予測モデル - 線形回帰による数値予測
📊 外れ値検出と除外 - 異常なデータの処理
📈 複数の評価指標 - R²、MAE、RMSE の使い分け
📉 データの可視化 - グラフで結果を確認

分類問題の次は、回帰問題 に挑戦です！準備はできましたか？😊

５章 Cinema 興行収入予測モデル（回帰問題の基礎）

「分類ができるようになったら、次は何？」次は 回帰問題 に挑戦します！「回帰って何？」簡単に言うと、数値を予測する問題 です。

この章では、映画の情報から興行収入を予測するモデルを作ります。ワクワクしませんか？🎬

🎯 この章の学習目標

この章では、以下のスキルを習得します：

📊 回帰問題の理解と実装 - 数値を予測するモデルを作る
🔧 データの前処理技術 - 欠損値・外れ値の処理方法を学ぶ
📈 評価指標の選択と解釈 - R²、MAE、RMSE の使い分け
📉 線形回帰モデルの構築 - 最もシンプルな回帰モデルを理解

🎬 Cinema データセットの理解

Cinema データセットは、映画の SNS 露出度から興行収入を予測する 回帰問題のデータセットです。

「SNS のつぶやき数で興行収入がわかるの？」と思いましたか？実際、SNS での話題性は興行収入と相関があることが知られています！

データの特徴

項目	内容
🎥 サンプル数	100 件程度
📊 特徴量数	4 つ（数値とカテゴリカル変数の混在）
💰 目的変数	興行収入（連続値）
⚠️ 欠損値	あり（前処理が必要！）
⚠️ 外れ値	あり（データクリーニングが必要！）

「欠損値あり！」これが、Iris データセットとの大きな違いです。実際のデータは完璧ではありません。この章で、現実的なデータ処理を学びましょう！

データ詳細

列名	内容	データ型	値の範囲
🎬 cinema_id	映画作品の ID	int	1 - 100
📱 SNS1	公開後 10 日以内に SNS1 でつぶやかれた数	float	0 - 1000
📱 SNS2	公開後 10 日以内に SNS2 でつぶやかれた数	float	0 - 2000
🎭 actor	主演俳優の昨年のメディア露出度	float	0 - 500
📚 original	原作があるかどうか	int	0（なし）、1（あり）
💰 sales	最終的な興行収入（万円）	float	1000 - 15000

🔍 分類問題と回帰問題の違い

「前の章の Iris と何が違うの？」良い質問です！比較してみましょう：

項目	🌸 Iris（分類）	🎬 Cinema（回帰）
目的	カテゴリを予測	数値を予測
出力	setosa、versicolor、virginica	興行収入（連続値）
アルゴリズム	決定木分類器	線形回帰
評価指標	正解率（Accuracy）	R²、MAE、RMSE
誤差の性質	正解/不正解の 2 値	誤差の大きさが重要

重要な違い：

分類は「どのクラス？」を答える問題
回帰は「どのくらい？」を答える問題

TDD による段階的実装

ステップ 1: クラスの初期化とデータ読み込み

Red: テストを書く

test/test_cinema_predictor.py:

"""Cinema 予測器のテスト"""
import pytest
import pandas as pd
import numpy as np
from src.ml.cinema_predictor import CinemaPredictor


class TestCinemaPredictorInit:
    """CinemaPredictor の初期化テスト"""

    def test_デフォルトパラメータでの初期化(self):
        """デフォルトパラメータで初期化できることを確認"""
        predictor = CinemaPredictor()

        assert predictor is not None
        assert predictor.model is None

    def test_初期化時の属性確認(self):
        """初期化時に必要な属性が設定されることを確認"""
        predictor = CinemaPredictor()

        assert hasattr(predictor, 'model')
        assert predictor.model is None


class TestCinemaPredictorDataLoading:
    """データ読み込みのテスト"""

    def test_CSVファイルからのデータ読み込み(self):
        """CSV ファイルからデータを読み込めることを確認"""
        predictor = CinemaPredictor()
        X, y = predictor.load_data('data/cinema.csv')

        assert X is not None
        assert y is not None
        assert isinstance(X, pd.DataFrame)
        assert isinstance(y, pd.Series)

    def test_特徴量の列数確認(self):
        """特徴量が 4 列であることを確認"""
        predictor = CinemaPredictor()
        X, y = predictor.load_data('data/cinema.csv')

        assert X.shape[1] == 4
        expected_columns = ['SNS1', 'SNS2', 'actor', 'original']
        assert list(X.columns) == expected_columns

    def test_欠損値の補完(self):
        """欠損値が平均値で補完されることを確認"""
        import tempfile
        import os

        # 欠損値を含むテストデータ
        test_data = """cinema_id,SNS1,SNS2,actor,original,sales
1,100,500,200,1,10000
2,,600,250,0,11000
3,150,,300,1,12000"""

        with tempfile.NamedTemporaryFile(mode='w', delete=False, suffix='.csv') as f:
            f.write(test_data)
            temp_path = f.name

        try:
            predictor = CinemaPredictor()
            X, y = predictor.load_data(temp_path)

            # 欠損値が補完されていることを確認
            assert X.isnull().sum().sum() == 0
        finally:
            os.unlink(temp_path)

    def test_目的変数の分離(self):
        """sales が目的変数として正しく分離されることを確認"""
        predictor = CinemaPredictor()
        X, y = predictor.load_data('data/cinema.csv')

        assert 'sales' not in X.columns
        assert y.name == 'sales'

Green: 最小限の実装

src/ml/cinema_predictor.py:

"""Cinema 興行収入予測器モジュール"""
import os
from typing import Optional, Tuple
import pandas as pd
import numpy as np
from sklearn.linear_model import LinearRegression
from sklearn.metrics import mean_absolute_error, mean_squared_error, r2_score


class CinemaPredictor:
    """映画興行収入を予測する線形回帰モデル

    Attributes:
        model: 訓練済みの線形回帰モデル（未訓練時は None）
    """

    def __init__(self) -> None:
        """初期化"""
        self.model: Optional[LinearRegression] = None

    def load_data(self, file_path: str) -> Tuple[pd.DataFrame, pd.Series]:
        """CSV ファイルからデータを読み込む

        Args:
            file_path: CSV ファイルのパス

        Returns:
            特徴量 DataFrame と目的変数 Series のタプル

        Raises:
            FileNotFoundError: ファイルが存在しない場合
            ValueError: データの形式が不正な場合
        """
        if not os.path.exists(file_path):
            raise FileNotFoundError(f"File not found: {file_path}")

        # データの読み込み
        df = pd.read_csv(file_path)

        # 必要な列の存在確認
        required_columns = ['SNS1', 'SNS2', 'actor', 'original', 'sales']
        missing_columns = set(required_columns) - set(df.columns)
        if missing_columns:
            raise ValueError(f"Missing columns: {missing_columns}")

        # 特徴量列
        feature_columns = ['SNS1', 'SNS2', 'actor', 'original']

        # 欠損値を平均値で補完
        df_filled = df.fillna(df.mean())

        # 特徴量と目的変数の分割
        X = df_filled[feature_columns]
        y = df_filled['sales']

        return X, y

ステップ 2: 外れ値処理

回帰問題では、外れ値がモデルの性能に大きく影響します。

Red: テストを書く

class TestCinemaPredictorOutlierRemoval:
    """外れ値除外のテスト"""

    def test_外れ値の検出(self):
        """外れ値を検出できることを確認"""
        predictor = CinemaPredictor()

        # 外れ値を含むデータ
        df = pd.DataFrame({
            'SNS1': [100, 150, 120],
            'SNS2': [500, 1500, 600],  # 1500 が異常に高い
            'actor': [200, 250, 220],
            'original': [1, 0, 1],
            'sales': [10000, 3000, 11000]  # SNS2高いのに sales低い→外れ値
        })

        df_cleaned = predictor.remove_outliers(df)

        # 外れ値が除外されていることを確認
        assert len(df_cleaned) == 2
        assert 1500 not in df_cleaned['SNS2'].values

    def test_正常データは保持される(self):
        """正常なデータは保持されることを確認"""
        predictor = CinemaPredictor()

        # 正常なデータのみ
        df = pd.DataFrame({
            'SNS1': [100, 150, 120],
            'SNS2': [500, 600, 550],
            'actor': [200, 250, 220],
            'original': [1, 0, 1],
            'sales': [10000, 11000, 10500]
        })

        df_cleaned = predictor.remove_outliers(df)

        # 全てのデータが保持される
        assert len(df_cleaned) == 3

    def test_外れ値除外の基準(self):
        """外れ値除外の基準が正しいことを確認"""
        predictor = CinemaPredictor()

        df = pd.DataFrame({
            'SNS1': [100, 150, 120, 140],
            'SNS2': [500, 1500, 600, 700],
            'actor': [200, 250, 220, 230],
            'original': [1, 0, 1, 0],
            'sales': [10000, 3000, 11000, 10500]
        })

        df_cleaned = predictor.remove_outliers(df)

        # SNS2 > 1000 かつ sales < 8500 のデータが除外される
        for _, row in df_cleaned.iterrows():
            if row['SNS2'] > 1000:
                assert row['sales'] >= 8500

Green: 外れ値処理の実装

def remove_outliers(self, df: pd.DataFrame) -> pd.DataFrame:
    """外れ値を除外する

    Args:
        df: 対象の DataFrame

    Returns:
        外れ値を除外した DataFrame

    Note:
        SNS2 が 1000 を超えているにも関わらず sales が 8500 未満のデータを
        異常値として除外します。
    """
    # 外れ値の条件: SNS2 > 1000 かつ sales < 8500
    outlier_condition = (df['SNS2'] > 1000) & (df['sales'] < 8500)
    outlier_indices = df[outlier_condition].index

    # 外れ値を除外
    df_cleaned = df.drop(outlier_indices, axis=0)

    return df_cleaned

Refactor: データ読み込みに外れ値処理を統合

def load_data(self, file_path: str,
              remove_outliers: bool = True) -> Tuple[pd.DataFrame, pd.Series]:
    """CSV ファイルからデータを読み込む（外れ値処理追加）

    Args:
        file_path: CSV ファイルのパス
        remove_outliers: 外れ値を除外するかどうか（デフォルト: True）

    Returns:
        特徴量 DataFrame と目的変数 Series のタプル
    """
    if not os.path.exists(file_path):
        raise FileNotFoundError(f"File not found: {file_path}")

    df = pd.read_csv(file_path)

    required_columns = ['SNS1', 'SNS2', 'actor', 'original', 'sales']
    missing_columns = set(required_columns) - set(df.columns)
    if missing_columns:
        raise ValueError(f"Missing columns: {missing_columns}")

    # 欠損値を平均値で補完
    df_filled = df.fillna(df.mean())

    # 外れ値の除外（オプション）
    if remove_outliers:
        df_filled = self.remove_outliers(df_filled)

    feature_columns = ['SNS1', 'SNS2', 'actor', 'original']
    X = df_filled[feature_columns]
    y = df_filled['sales']

    return X, y

ステップ 3: モデルの訓練

Red: テストを書く

class TestCinemaPredictorTraining:
    """モデル訓練のテスト"""

    def test_モデルの訓練(self):
        """線形回帰モデルを訓練できることを確認"""
        predictor = CinemaPredictor()
        X_train = pd.DataFrame({
            'SNS1': [100, 150, 120],
            'SNS2': [500, 600, 550],
            'actor': [200, 250, 220],
            'original': [1, 0, 1]
        })
        y_train = pd.Series([10000, 11000, 10500])

        predictor.train(X_train, y_train)

        assert predictor.model is not None
        assert isinstance(predictor.model, LinearRegression)

    def test_訓練済みモデルの係数確認(self):
        """訓練済みモデルが係数を持つことを確認"""
        predictor = CinemaPredictor()
        X_train = pd.DataFrame({
            'SNS1': [100, 150, 120],
            'SNS2': [500, 600, 550],
            'actor': [200, 250, 220],
            'original': [1, 0, 1]
        })
        y_train = pd.Series([10000, 11000, 10500])

        predictor.train(X_train, y_train)

        # 線形回帰の係数が設定されていることを確認
        assert hasattr(predictor.model, 'coef_')
        assert hasattr(predictor.model, 'intercept_')
        assert len(predictor.model.coef_) == 4  # 特徴量が4つ

    def test_空のデータでの訓練拒否(self):
        """空のデータでの訓練を拒否することを確認"""
        predictor = CinemaPredictor()
        X_train = pd.DataFrame()
        y_train = pd.Series(dtype=float)

        with pytest.raises(ValueError):
            predictor.train(X_train, y_train)

Green: 訓練機能の実装

def train(self, X_train: pd.DataFrame, y_train: pd.Series) -> None:
    """線形回帰モデルを訓練する

    Args:
        X_train: 訓練用特徴量
        y_train: 訓練用目的変数

    Raises:
        ValueError: データが空の場合
    """
    if len(X_train) == 0 or len(y_train) == 0:
        raise ValueError("Training data cannot be empty")

    if len(X_train) != len(y_train):
        raise ValueError(
            f"X_train and y_train must have the same length: "
            f"{len(X_train)} != {len(y_train)}"
        )

    # 線形回帰モデルの作成
    self.model = LinearRegression()

    # モデルの訓練
    self.model.fit(X_train, y_train)

ステップ 4: 予測と評価

Red: テストを書く

class TestCinemaPredictorPrediction:
    """予測機能のテスト"""

    @pytest.fixture
    def trained_predictor(self):
        """訓練済みの予測器を返す fixture"""
        predictor = CinemaPredictor()
        X_train = pd.DataFrame({
            'SNS1': [100, 150, 120, 140],
            'SNS2': [500, 600, 550, 580],
            'actor': [200, 250, 220, 230],
            'original': [1, 0, 1, 0]
        })
        y_train = pd.Series([10000, 11000, 10500, 10800])
        predictor.train(X_train, y_train)
        return predictor

    def test_単一サンプルの予測(self, trained_predictor):
        """単一サンプルを予測できることを確認"""
        X_test = pd.DataFrame({
            'SNS1': [130],
            'SNS2': [570],
            'actor': [210],
            'original': [1]
        })

        predictions = trained_predictor.predict(X_test)

        assert len(predictions) == 1
        assert isinstance(predictions[0], (int, float, np.number))
        assert predictions[0] > 0  # 興行収入は正の値

    def test_複数サンプルの予測(self, trained_predictor):
        """複数サンプルを予測できることを確認"""
        X_test = pd.DataFrame({
            'SNS1': [130, 160],
            'SNS2': [570, 620],
            'actor': [210, 260],
            'original': [1, 0]
        })

        predictions = trained_predictor.predict(X_test)

        assert len(predictions) == 2


class TestCinemaPredictorEvaluation:
    """モデル評価のテスト"""

    def test_評価指標の計算(self):
        """複数の評価指標を計算できることを確認"""
        predictor = CinemaPredictor()
        X_train = pd.DataFrame({
            'SNS1': [100, 150, 120, 140],
            'SNS2': [500, 600, 550, 580],
            'actor': [200, 250, 220, 230],
            'original': [1, 0, 1, 0]
        })
        y_train = pd.Series([10000, 11000, 10500, 10800])
        predictor.train(X_train, y_train)

        # テストデータ
        X_test = pd.DataFrame({
            'SNS1': [130, 160],
            'SNS2': [570, 620],
            'actor': [210, 260],
            'original': [1, 0]
        })
        y_test = pd.Series([10600, 11200])

        metrics = predictor.evaluate(X_test, y_test)

        # 全ての評価指標が含まれることを確認
        assert 'r2_score' in metrics
        assert 'mae' in metrics
        assert 'rmse' in metrics

    def test_決定係数の範囲(self):
        """決定係数が適切な範囲にあることを確認"""
        predictor = CinemaPredictor()
        X, y = predictor.load_data('data/cinema.csv')

        from sklearn.model_selection import train_test_split
        X_train, X_test, y_train, y_test = train_test_split(
            X, y, test_size=0.2, random_state=0
        )

        predictor.train(X_train, y_train)
        metrics = predictor.evaluate(X_test, y_test)

        # R²は通常 -∞ から 1 の範囲（良いモデルは 0 に近いか正）
        assert metrics['r2_score'] <= 1.0

    def test_MAEとRMSEの関係(self):
        """MAE と RMSE の関係を確認"""
        predictor = CinemaPredictor()
        X, y = predictor.load_data('data/cinema.csv')

        from sklearn.model_selection import train_test_split
        X_train, X_test, y_train, y_test = train_test_split(
            X, y, test_size=0.2, random_state=0
        )

        predictor.train(X_train, y_train)
        metrics = predictor.evaluate(X_test, y_test)

        # RMSE は MAE 以上になる（等号は全ての誤差が同じ時）
        assert metrics['rmse'] >= metrics['mae']

Green: 予測と評価機能の実装

def predict(self, X_test: pd.DataFrame) -> np.ndarray:
    """興行収入を予測する

    Args:
        X_test: テスト用特徴量

    Returns:
        予測された興行収入の配列

    Raises:
        ValueError: モデルが未訓練の場合
    """
    if self.model is None:
        raise ValueError("Model has not been trained yet")

    return self.model.predict(X_test)


def evaluate(self, X_test: pd.DataFrame, y_test: pd.Series) -> dict:
    """モデルの性能を評価する

    Args:
        X_test: テスト用特徴量
        y_test: テスト用目的変数

    Returns:
        評価指標の辞書
        - r2_score: 決定係数（1.0 に近いほど良い）
        - mae: 平均絶対誤差（小さいほど良い）
        - rmse: 平均二乗誤差の平方根（小さいほど良い）

    Raises:
        ValueError: モデルが未訓練の場合
    """
    if self.model is None:
        raise ValueError("Model has not been trained yet")

    y_pred = self.model.predict(X_test)

    return {
        'r2_score': r2_score(y_test, y_pred),
        'mae': mean_absolute_error(y_test, y_pred),
        'rmse': np.sqrt(mean_squared_error(y_test, y_pred))
    }

ステップ 5: モデルの保存と読み込み

Red: テストを書く

class TestCinemaPredictorPersistence:
    """モデルの永続化テスト"""

    def test_モデルの保存(self, tmp_path):
        """訓練済みモデルを保存できることを確認"""
        predictor = CinemaPredictor()
        X_train = pd.DataFrame({
            'SNS1': [100, 150],
            'SNS2': [500, 600],
            'actor': [200, 250],
            'original': [1, 0]
        })
        y_train = pd.Series([10000, 11000])
        predictor.train(X_train, y_train)

        model_path = tmp_path / "cinema_model.pkl"
        predictor.save_model(str(model_path))

        assert model_path.exists()

    def test_保存したモデルでの予測一貫性(self, tmp_path):
        """保存前後で予測結果が一致することを確認"""
        # モデルを訓練
        predictor1 = CinemaPredictor()
        X_train = pd.DataFrame({
            'SNS1': [100, 150],
            'SNS2': [500, 600],
            'actor': [200, 250],
            'original': [1, 0]
        })
        y_train = pd.Series([10000, 11000])
        predictor1.train(X_train, y_train)

        # テストデータ
        X_test = pd.DataFrame({
            'SNS1': [130],
            'SNS2': [570],
            'actor': [210],
            'original': [1]
        })

        # 保存前の予測
        pred_before = predictor1.predict(X_test)

        # モデルの保存と読み込み
        model_path = tmp_path / "cinema_model.pkl"
        predictor1.save_model(str(model_path))

        predictor2 = CinemaPredictor()
        predictor2.load_model(str(model_path))

        # 読み込み後の予測
        pred_after = predictor2.predict(X_test)

        # 予測結果が一致することを確認
        np.testing.assert_array_almost_equal(pred_before, pred_after)

Green: 永続化機能の実装

import pickle


def save_model(self, file_path: str) -> None:
    """訓練済みモデルをファイルに保存する

    Args:
        file_path: 保存先のファイルパス

    Raises:
        ValueError: モデルが未訓練の場合
    """
    if self.model is None:
        raise ValueError("No trained model to save")

    with open(file_path, 'wb') as f:
        pickle.dump(self.model, f)


def load_model(self, file_path: str) -> None:
    """保存されたモデルをファイルから読み込む

    Args:
        file_path: 読み込むファイルのパス

    Raises:
        FileNotFoundError: ファイルが存在しない場合
    """
    if not os.path.exists(file_path):
        raise FileNotFoundError(f"Model file not found: {file_path}")

    with open(file_path, 'rb') as f:
        self.model = pickle.load(f)

評価指標の理解

回帰問題では、複数の評価指標を使用してモデルの性能を多角的に評価します。

1. 決定係数（R² Score）

"""
R² = 1 - (予測誤差の平方和 / 実測値の分散)

- 値の範囲: -∞ から 1
- 1.0: 完璧な予測
- 0.0: 平均値で予測するのと同等
- 負の値: 平均値で予測するより悪い
"""

def test_R2スコアの解釈():
    """R²スコアの意味を確認"""
    # 完璧な予測
    y_true = np.array([100, 200, 300])
    y_pred = np.array([100, 200, 300])
    r2 = r2_score(y_true, y_pred)
    assert r2 == 1.0  # 完璧

    # 平均値で予測
    y_pred = np.array([200, 200, 200])  # 全て平均
    r2 = r2_score(y_true, y_pred)
    assert r2 == 0.0  # 平均値と同等

    # 悪い予測
    y_pred = np.array([300, 100, 100])  # 全く外れている
    r2 = r2_score(y_true, y_pred)
    assert r2 < 0  # 平均値より悪い

2. 平均絶対誤差（MAE: Mean Absolute Error）

"""
MAE = Σ|予測値 - 実測値| / サンプル数

- 値の範囲: 0 から ∞
- 0: 完璧な予測
- 誤差の絶対値の平均（単位は目的変数と同じ）
- 外れ値の影響を受けにくい
"""

def test_MAEの計算():
    """MAE の計算を確認"""
    y_true = np.array([10000, 11000, 12000])
    y_pred = np.array([10200, 10800, 12100])

    mae = mean_absolute_error(y_true, y_pred)

    # (200 + 200 + 100) / 3 = 166.67
    assert abs(mae - 166.67) < 0.01

3. 平均二乗誤差の平方根（RMSE: Root Mean Squared Error）

"""
RMSE = √(Σ(予測値 - 実測値)² / サンプル数)

- 値の範囲: 0 から ∞
- 0: 完璧な予測
- 誤差の二乗平均の平方根（単位は目的変数と同じ）
- 外れ値の影響を受けやすい（大きな誤差にペナルティ）
"""

def test_RMSEの計算():
    """RMSE の計算を確認"""
    y_true = np.array([10000, 11000, 12000])
    y_pred = np.array([10200, 10800, 12100])

    mse = mean_squared_error(y_true, y_pred)
    rmse = np.sqrt(mse)

    # √((200² + 200² + 100²) / 3) = √(90000 / 3) = √30000 ≈ 173.21
    assert abs(rmse - 173.21) < 0.01

完全な実装例

src/ml/cinema_predictor.py:

"""Cinema 興行収入予測器モジュール"""
import os
import pickle
from typing import Optional, Tuple
import pandas as pd
import numpy as np
from sklearn.linear_model import LinearRegression
from sklearn.metrics import mean_absolute_error, mean_squared_error, r2_score


class CinemaPredictor:
    """映画興行収入を予測する線形回帰モデル

    Attributes:
        model: 訓練済みの線形回帰モデル（未訓練時は None）
    """

    def __init__(self) -> None:
        """初期化"""
        self.model: Optional[LinearRegression] = None

    def remove_outliers(self, df: pd.DataFrame) -> pd.DataFrame:
        """外れ値を除外する

        Args:
            df: 対象の DataFrame

        Returns:
            外れ値を除外した DataFrame
        """
        outlier_condition = (df['SNS2'] > 1000) & (df['sales'] < 8500)
        outlier_indices = df[outlier_condition].index
        return df.drop(outlier_indices, axis=0)

    def load_data(self, file_path: str,
                  remove_outliers: bool = True) -> Tuple[pd.DataFrame, pd.Series]:
        """CSV ファイルからデータを読み込む

        Args:
            file_path: CSV ファイルのパス
            remove_outliers: 外れ値を除外するかどうか

        Returns:
            特徴量 DataFrame と目的変数 Series のタプル

        Raises:
            FileNotFoundError: ファイルが存在しない場合
            ValueError: データの形式が不正な場合
        """
        if not os.path.exists(file_path):
            raise FileNotFoundError(f"File not found: {file_path}")

        df = pd.read_csv(file_path)

        required_columns = ['SNS1', 'SNS2', 'actor', 'original', 'sales']
        missing_columns = set(required_columns) - set(df.columns)
        if missing_columns:
            raise ValueError(f"Missing columns: {missing_columns}")

        # 欠損値を平均値で補完
        df_filled = df.fillna(df.mean())

        # 外れ値の除外（オプション）
        if remove_outliers:
            df_filled = self.remove_outliers(df_filled)

        feature_columns = ['SNS1', 'SNS2', 'actor', 'original']
        X = df_filled[feature_columns]
        y = df_filled['sales']

        return X, y

    def train(self, X_train: pd.DataFrame, y_train: pd.Series) -> None:
        """線形回帰モデルを訓練する

        Args:
            X_train: 訓練用特徴量
            y_train: 訓練用目的変数

        Raises:
            ValueError: データが空の場合
        """
        if len(X_train) == 0 or len(y_train) == 0:
            raise ValueError("Training data cannot be empty")

        if len(X_train) != len(y_train):
            raise ValueError(
                f"X_train and y_train must have the same length: "
                f"{len(X_train)} != {len(y_train)}"
            )

        self.model = LinearRegression()
        self.model.fit(X_train, y_train)

    def predict(self, X_test: pd.DataFrame) -> np.ndarray:
        """興行収入を予測する

        Args:
            X_test: テスト用特徴量

        Returns:
            予測された興行収入の配列

        Raises:
            ValueError: モデルが未訓練の場合
        """
        if self.model is None:
            raise ValueError("Model has not been trained yet")

        return self.model.predict(X_test)

    def evaluate(self, X_test: pd.DataFrame, y_test: pd.Series) -> dict:
        """モデルの性能を評価する

        Args:
            X_test: テスト用特徴量
            y_test: テスト用目的変数

        Returns:
            評価指標の辞書
        """
        if self.model is None:
            raise ValueError("Model has not been trained yet")

        y_pred = self.model.predict(X_test)

        return {
            'r2_score': r2_score(y_test, y_pred),
            'mae': mean_absolute_error(y_test, y_pred),
            'rmse': np.sqrt(mean_squared_error(y_test, y_pred))
        }

    def save_model(self, file_path: str) -> None:
        """訓練済みモデルをファイルに保存する

        Args:
            file_path: 保存先のファイルパス

        Raises:
            ValueError: モデルが未訓練の場合
        """
        if self.model is None:
            raise ValueError("No trained model to save")

        with open(file_path, 'wb') as f:
            pickle.dump(self.model, f)

    def load_model(self, file_path: str) -> None:
        """保存されたモデルをファイルから読み込む

        Args:
            file_path: 読み込むファイルのパス

        Raises:
            FileNotFoundError: ファイルが存在しない場合
        """
        if not os.path.exists(file_path):
            raise FileNotFoundError(f"Model file not found: {file_path}")

        with open(file_path, 'rb') as f:
            self.model = pickle.load(f)

実践例：Cinema 予測モデルの訓練

script/train_cinema.py:

"""Cinema 興行収入予測モデルの訓練例"""
from sklearn.model_selection import train_test_split
from src.ml.cinema_predictor import CinemaPredictor


def main():
    """メイン処理"""
    # 予測器の作成
    predictor = CinemaPredictor()
    print("CinemaPredictor を作成しました")

    # データの読み込み（外れ値除外あり）
    X, y = predictor.load_data('data/cinema.csv', remove_outliers=True)
    print(f"データを読み込みました: {len(X)} サンプル")

    # 訓練データとテストデータに分割
    X_train, X_test, y_train, y_test = train_test_split(
        X, y, test_size=0.2, random_state=0
    )
    print(f"訓練データ: {len(X_train)} サンプル")
    print(f"テストデータ: {len(X_test)} サンプル")

    # モデルの訓練
    predictor.train(X_train, y_train)
    print("モデルの訓練が完了しました")

    # モデルの係数表示
    print("\n[モデルの係数]")
    feature_names = ['SNS1', 'SNS2', 'actor', 'original']
    for name, coef in zip(feature_names, predictor.model.coef_):
        print(f"  {name}: {coef:.4f}")
    print(f"  切片: {predictor.model.intercept_:.4f}")

    # モデルの評価
    metrics = predictor.evaluate(X_test, y_test)
    print("\n[モデルの評価]")
    print(f"  決定係数（R²）: {metrics['r2_score']:.4f}")
    print(f"  平均絶対誤差（MAE）: {metrics['mae']:.2f} 万円")
    print(f"  平均二乗誤差平方根（RMSE）: {metrics['rmse']:.2f} 万円")

    # モデルの保存
    predictor.save_model('model/cinema.pkl')
    print("\nモデルを model/cinema.pkl に保存しました")

    # 予測例
    print("\n[予測例]")
    sample = X_test.iloc[:3]
    predictions = predictor.predict(sample)

    for i, (idx, row) in enumerate(sample.iterrows()):
        actual = y_test.iloc[i]
        predicted = predictions[i]
        error = abs(actual - predicted)

        print(f"\nサンプル {i+1}:")
        print(f"  SNS1: {row['SNS1']:.0f}, SNS2: {row['SNS2']:.0f}")
        print(f"  actor: {row['actor']:.0f}, original: {row['original']}")
        print(f"  実際の興行収入: {actual:.0f} 万円")
        print(f"  予測興行収入: {predicted:.0f} 万円")
        print(f"  誤差: {error:.0f} 万円")


if __name__ == '__main__':
    main()

実行例：

uv run python script/train_cinema.py

# 出力例：
# CinemaPredictor を作成しました
# データを読み込みました: 95 サンプル
# 訓練データ: 76 サンプル
# テストデータ: 19 サンプル
# モデルの訓練が完了しました
#
# [モデルの係数]
#   SNS1: 2.3456
#   SNS2: 4.7823
#   actor: 1.2345
#   original: 234.5678
#   切片: 5432.1098
#
# [モデルの評価]
#   決定係数（R²）: 0.8383
#   平均絶対誤差（MAE）: 206.83 万円
#   平均二乗誤差平方根（RMSE）: 289.45 万円
#
# モデルを model/cinema.pkl に保存しました
#
# [予測例]
#
# サンプル 1:
#   SNS1: 150, SNS2: 700
#   actor: 300, original: 0
#   実際の興行収入: 11500 万円
#   予測興行収入: 11324 万円
#   誤差: 176 万円
#
# サンプル 2:
#   SNS1: 200, SNS2: 850
#   actor: 350, original: 1
#   実際の興行収入: 12800 万円
#   予測興行収入: 12967 万円
#   誤差: 167 万円

📓 Jupyter Notebook での探索と視覚化

回帰モデルでは、予測値と実測値の関係を視覚化することが重要です。Jupyter Notebook で詳しく分析しましょう！

🎯 この節の目的

回帰モデルの性能を視覚的に評価する - 実測値 vs 予測値、残差分析
特徴量の影響を理解する - 各特徴量が予測にどう寄与するか
誤差の傾向を発見する - どのような場合に予測が外れるか

📝 Notebook の作成

cd app/python/ml_tdd
uv run jupyter lab

notebook/ ディレクトリに cinema_exploration.ipynb を作成しましょう。

1️⃣ 環境セットアップとデータ読み込み

# セル 1: ライブラリのインポート
import sys
sys.path.append('..')

import pandas as pd
import numpy as np
import matplotlib.pyplot as plt
import seaborn as sns
from sklearn.model_selection import train_test_split
from sklearn.metrics import mean_absolute_error, mean_squared_error, r2_score

# 日本語フォント設定
plt.rcParams['font.sans-serif'] = ['MS Gothic']
plt.rcParams['axes.unicode_minus'] = False

# スタイル設定
sns.set_style("whitegrid")
sns.set_palette("husl")

print("✅ 環境セットアップ完了")

# セル 2: データとモデルの準備
from src.ml.cinema_predictor import CinemaPredictor

predictor = CinemaPredictor()
X, y = predictor.load_data('data/cinema.csv')

print(f"データ形状: X={X.shape}, y={y.shape}")
print(f"\n特徴量:\n{X.describe()}")
print(f"\n目的変数の統計:\n{y.describe()}")

2️⃣ データ探索と相関分析

# セル 3: 特徴量間の相関をヒートマップで確認
df_corr = X.copy()
df_corr['sales'] = y

plt.figure(figsize=(10, 8))
correlation_matrix = df_corr.corr()
sns.heatmap(
    correlation_matrix,
    annot=True,
    fmt='.2f',
    cmap='coolwarm',
    center=0,
    square=True,
    linewidths=1
)
plt.title('特徴量と興行収入の相関マトリックス', fontsize=14)
plt.tight_layout()
plt.show()

print("\n相関係数（興行収入との関係）:")
print(correlation_matrix['sales'].sort_values(ascending=False))

相関から分かること：

どの特徴量が興行収入と強く関連しているか
特徴量間に多重共線性がないか

# セル 4: 各特徴量と興行収入の関係を散布図で確認
fig, axes = plt.subplots(2, 2, figsize=(14, 10))
features = X.columns

for idx, feature in enumerate(features):
    ax = axes[idx // 2, idx % 2]
    ax.scatter(X[feature], y, alpha=0.5, s=50)
    ax.set_xlabel(feature, fontsize=12)
    ax.set_ylabel('興行収入 (万円)', fontsize=12)
    ax.set_title(f'{feature} と興行収入の関係', fontsize=13)
    ax.grid(True, alpha=0.3)

plt.tight_layout()
plt.show()

3️⃣ モデルの訓練と予測

# セル 5: データ分割と訓練
X_train, X_test, y_train, y_test = train_test_split(
    X, y, test_size=0.2, random_state=42
)

# モデルの訓練
predictor.train(X_train, y_train)

# 予測
y_pred_train = predictor.predict(X_train)
y_pred_test = predictor.predict(X_test)

# 評価指標
metrics_train = predictor.evaluate(y_train, y_pred_train)
metrics_test = predictor.evaluate(y_test, y_pred_test)

print("【訓練データの評価】")
print(f"  R²   : {metrics_train['r2']:.4f}")
print(f"  MAE  : {metrics_train['mae']:.2f} 万円")
print(f"  RMSE : {metrics_train['rmse']:.2f} 万円")

print("\n【テストデータの評価】")
print(f"  R²   : {metrics_test['r2']:.4f}")
print(f"  MAE  : {metrics_test['mae']:.2f} 万円")
print(f"  RMSE : {metrics_test['rmse']:.2f} 万円")

4️⃣ 予測値 vs 実測値の視覚化

# セル 6: 実測値 vs 予測値の散布図
fig, (ax1, ax2) = plt.subplots(1, 2, figsize=(14, 6))

# 訓練データ
ax1.scatter(y_train, y_pred_train, alpha=0.5, s=50)
ax1.plot([y_train.min(), y_train.max()],
         [y_train.min(), y_train.max()],
         'r--', lw=2, label='理想的な予測')
ax1.set_xlabel('実測値 (万円)', fontsize=12)
ax1.set_ylabel('予測値 (万円)', fontsize=12)
ax1.set_title(f'訓練データ (R²={metrics_train["r2"]:.3f})', fontsize=13)
ax1.legend()
ax1.grid(True, alpha=0.3)

# テストデータ
ax2.scatter(y_test, y_pred_test, alpha=0.5, s=50, color='green')
ax2.plot([y_test.min(), y_test.max()],
         [y_test.min(), y_test.max()],
         'r--', lw=2, label='理想的な予測')
ax2.set_xlabel('実測値 (万円)', fontsize=12)
ax2.set_ylabel('予測値 (万円)', fontsize=12)
ax2.set_title(f'テストデータ (R²={metrics_test["r2"]:.3f})', fontsize=13)
ax2.legend()
ax2.grid(True, alpha=0.3)

plt.tight_layout()
plt.show()

このグラフから分かること：

点が対角線に近い = 予測精度が高い
点が散らばっている = 予測誤差が大きい
訓練データとテストデータの性能差 = 過学習の程度

5️⃣ 残差分析（予測誤差の詳細）

# セル 7: 残差プロット
residuals_train = y_train - y_pred_train
residuals_test = y_test - y_pred_test

fig, axes = plt.subplots(2, 2, figsize=(14, 10))

# 訓練データの残差プロット
axes[0, 0].scatter(y_pred_train, residuals_train, alpha=0.5)
axes[0, 0].axhline(y=0, color='r', linestyle='--', lw=2)
axes[0, 0].set_xlabel('予測値 (万円)')
axes[0, 0].set_ylabel('残差 (実測値 - 予測値)')
axes[0, 0].set_title('残差プロット (訓練データ)')
axes[0, 0].grid(True, alpha=0.3)

# テストデータの残差プロット
axes[0, 1].scatter(y_pred_test, residuals_test, alpha=0.5, color='green')
axes[0, 1].axhline(y=0, color='r', linestyle='--', lw=2)
axes[0, 1].set_xlabel('予測値 (万円)')
axes[0, 1].set_ylabel('残差 (実測値 - 予測値)')
axes[0, 1].set_title('残差プロット (テストデータ)')
axes[0, 1].grid(True, alpha=0.3)

# 訓練データの残差ヒストグラム
axes[1, 0].hist(residuals_train, bins=20, alpha=0.7, edgecolor='black')
axes[1, 0].axvline(x=0, color='r', linestyle='--', lw=2)
axes[1, 0].set_xlabel('残差 (万円)')
axes[1, 0].set_ylabel('頻度')
axes[1, 0].set_title('残差の分布 (訓練データ)')
axes[1, 0].grid(True, alpha=0.3)

# テストデータの残差ヒストグラム
axes[1, 1].hist(residuals_test, bins=20, alpha=0.7, color='green', edgecolor='black')
axes[1, 1].axvline(x=0, color='r', linestyle='--', lw=2)
axes[1, 1].set_xlabel('残差 (万円)')
axes[1, 1].set_ylabel('頻度')
axes[1, 1].set_title('残差の分布 (テストデータ)')
axes[1, 1].grid(True, alpha=0.3)

plt.tight_layout()
plt.show()

print(f"残差の統計 (テストデータ):")
print(f"  平均: {residuals_test.mean():.2f} 万円")
print(f"  標準偏差: {residuals_test.std():.2f} 万円")
print(f"  最大誤差: {residuals_test.abs().max():.2f} 万円")

残差プロットの読み方：

ランダムに散らばっている = 良いモデル
パターンがある = モデルの改善余地あり（非線形性など）
ヒストグラムが正規分布に近い = 線形回帰の仮定を満たす

6️⃣ 特徴量の重要度（回帰係数）

# セル 8: 回帰係数の可視化
coefficients = predictor.model.coef_
intercept = predictor.model.intercept_

coef_df = pd.DataFrame({
    'feature': X.columns,
    'coefficient': coefficients
}).sort_values('coefficient', ascending=False)

plt.figure(figsize=(10, 6))
sns.barplot(data=coef_df, x='coefficient', y='feature', palette='viridis')
plt.title('線形回帰の係数（特徴量の寄与度）', fontsize=14)
plt.xlabel('係数の値', fontsize=12)
plt.ylabel('特徴量', fontsize=12)
plt.axvline(x=0, color='black', linestyle='--', lw=1)
plt.tight_layout()
plt.show()

print("\n回帰式:")
print(f"興行収入 = {intercept:.2f}")
for feature, coef in zip(X.columns, coefficients):
    print(f"  + {coef:.2f} × {feature}")

係数の解釈：

正の係数 = その特徴量が増えると興行収入も増える
負の係数 = その特徴量が増えると興行収入が減る
係数の絶対値が大きい = 影響力が強い

7️⃣ 予測誤差の分析

# セル 9: 誤差が大きいサンプルを特定
test_df = X_test.copy()
test_df['actual'] = y_test.values
test_df['predicted'] = y_pred_test
test_df['error'] = np.abs(y_test.values - y_pred_test)
test_df['error_pct'] = (test_df['error'] / test_df['actual']) * 100

# 誤差が大きいトップ5
print("誤差が大きいサンプル トップ5:")
print(test_df.nlargest(5, 'error')[['actual', 'predicted', 'error', 'error_pct']])

# 誤差が小さいトップ5
print("\n誤差が小さいサンプル トップ5:")
print(test_df.nsmallest(5, 'error')[['actual', 'predicted', 'error', 'error_pct']])

8️⃣ 感度分析（What-if シナリオ）

# セル 10: 特徴量を変化させたときの予測変化
# 基準となるサンプル
base_sample = pd.DataFrame({
    'SNS1': [100],
    'SNS2': [500],
    'actor': [200],
    'original': [0]
})
base_prediction = predictor.predict(base_sample)[0]

# SNS1 を変化させる
sns1_range = np.linspace(0, 300, 50)
predictions_sns1 = []

for sns1_val in sns1_range:
    sample = base_sample.copy()
    sample['SNS1'] = sns1_val
    pred = predictor.predict(sample)[0]
    predictions_sns1.append(pred)

# 可視化
plt.figure(figsize=(10, 6))
plt.plot(sns1_range, predictions_sns1, marker='o', markersize=3)
plt.axhline(y=base_prediction, color='r', linestyle='--', label=f'基準予測 ({base_prediction:.0f}万円)')
plt.xlabel('SNS1 の値', fontsize=12)
plt.ylabel('予測興行収入 (万円)', fontsize=12)
plt.title('SNS1 の変化が予測に与える影響', fontsize=14)
plt.legend()
plt.grid(True, alpha=0.3)
plt.tight_layout()
plt.show()

print(f"SNS1 が 100 増えると、興行収入は約 {(predictions_sns1[-1] - predictions_sns1[0]) / 3:.0f} 万円増加")

💡 回帰モデルでの Notebook 活用ポイント

✅ やること	❌ 避けること
残差プロットで仮定を確認	R² だけで性能を判断
予測誤差が大きいサンプルを分析	外れ値を無視する
特徴量の寄与度を理解	係数の意味を考えない
What-if シナリオで感度分析	単純な予測だけで終わる

🔄 探索から本番コードへ

# 発見 1: SNS2 の相関が最も強い
# ↓ テストに反映
def test_SNS2の係数が最大(self):
    """SNS2 の係数が最も大きいことを確認"""
    coefs = dict(zip(predictor.model.feature_names_in_,
                     predictor.model.coef_))
    assert coefs['SNS2'] == max(coefs.values())

# 発見 2: 残差が正規分布に従う
# ↓ テストに反映
def test_残差の正規性(self):
    """残差がおおよそ正規分布に従うことを確認"""
    from scipy import stats
    _, p_value = stats.normaltest(residuals)
    assert p_value > 0.05  # 有意水準 5% で正規性を棄却しない

📊 ５章の技術的成果

「回帰問題もマスターしました！」お疲れさまでした！５章で何を達成したか、振り返ってみましょう。

✅ 完成した機能

５章では、以下の機能を実装しました：

✅ Cinema 予測器クラスの完全実装 - 興行収入を予測するモデル
✅ 線形回帰モデルの訓練機能 - 数値を予測
✅ 外れ値検出と除外機能 - 異常なデータを除外
✅ 複数の評価指標 - R²、MAE、RMSE で評価
✅ データの欠損値処理 - 実務的なデータクリーニング
✅ モデルの保存と読み込み機能 - モデルの再利用

📈 定量的成果

数字で見ると、こんなに達成しました！

指標	🎯 実績
🧪 テストケース	20 個
📊 コードカバレッジ	92%（cinema_predictor.py）
🔤 型ヒント使用率	100%
🎬 モデル決定係数（R²）	0.8383（テストデータ）
💰 平均絶対誤差（MAE）	206.83 万円
✨ Ruff チェック	全て通過
✅ mypy チェック	エラー 0 件

R² = 0.8383！ これは、モデルがデータの約 84% を説明できているという意味です。良い結果ですね！🎉

🎓 習得したスキル

1. 🔄 TDD スキル（応用）

✅ 外れ値処理のテスト駆動実装
✅ 複数の評価指標のテスト
✅ 数値計算の精度検証

2. 📊 機械学習スキル（回帰）

✅ 線形回帰アルゴリズムの理解
✅ 外れ値の検出と除外
✅ 複数の評価指標の理解と使い分け
✅ モデル係数の解釈

3. 🔧 データ処理スキル（発展）

✅ 条件に基づくデータフィルタリング
✅ 欠損値の補完
✅ データクリーニングパイプライン

4. 統計スキル

R²スコアの意味理解
MAE と RMSE の違い
評価指標の選択基準

線形回帰の理解

線形回帰の数式:

y = β₀ + β₁x₁ + β₂x₂ + β₃x₃ + β₄x₄

where:
  y: 興行収入（sales）
  x₁: SNS1
  x₂: SNS2
  x₃: actor
  x₄: original
  β₀: 切片（intercept）
  β₁, β₂, β₃, β₄: 各特徴量の係数（coefficients）

係数の解釈:

# SNS2 の係数が 4.78 の場合
# → SNS2 が 1 増えると、興行収入が約 4.78 万円増加すると予測

分類と回帰の実装比較

項目	Iris（分類）	Cinema（回帰）
モデル	DecisionTreeClassifier	LinearRegression
出力	クラスラベル（文字列）	連続値（float）
評価	accuracy（正解率）	R²、MAE、RMSE
前処理	欠損値補完	欠損値補完 + 外れ値除外
テスト数	18個	20個

🚀 次の章への準備

５章では、回帰問題の基礎を学びました！次の６章では、以下を実装します：

⛴️ Survived 生存予測モデル - 実践的な分類問題
🔧 高度な欠損値処理 - グループ別補完テクニック
📊 カテゴリカル変数のエンコーディング - 文字列データの数値化
⚖️ クラス不均衡への対応 - 偏ったデータへの対処

より実践的な分類問題に挑戦です！これまでの知識を活かせますよ！💪

６章 Survived 生存予測モデル（実践的な分類問題）

「分類問題の基礎は学んだけど、もっと実践的な問題に挑戦したい！」そんなあなたにぴったりの章です！

この章では、タイタニック号の乗客データから生存者を予測するモデルを作ります。これは Kaggle（機械学習コンペティション）でも有名な問題です！⛴️

🎯 この章の学習目標

この章では、より実践的なスキルを習得します：

🔧 高度なデータ前処理 - グループ別統計による欠損値補完
📊 カテゴリカル変数の処理 - ダミー変数化と多重共線性の回避
⚖️ クラス不均衡への対応 - class_weight パラメータによる調整
🔄 TDD の応用 - 複雑な前処理ロジックのテスト駆動実装

「え、これまでより難しそう...」と思いましたか？大丈夫です！一歩ずつ進めていきましょう。

⛴️ Survived データセットの理解

このデータセットは、客船沈没事故の乗客データから生存を予測する問題です。「年齢や性別、チケットのクラスなどから、誰が生き残ったか予測できるの？」実はできるんです！

データ詳細

data/Survived.csv を使用します：

列名	内容	データ型	特徴
🎫 Pclass	チケットクラス（1、2、3）	int	社会階級を表す
👤 Age	年齢	float	⚠️ 欠損値あり
👨‍👩‍👧 SibSp	同乗した兄弟や配偶者の総数	int	家族構成情報
👨‍👩‍👧‍👦 Parch	同乗した親子の総数	int	家族構成情報
💰 Fare	運賃	float	支払った金額
🚻 Sex	性別	str	⚠️ カテゴリカル変数
✅ Survived	生存状況（1: 生存、0: 死亡）	int	🎯 目的変数

🔍 これまでのデータセットとの違い

特徴	Iris	Cinema	Survived
問題の種類	分類（3クラス）	回帰	分類（2クラス）
欠損値処理	平均値補完	平均値補完	グループ別中央値補完
カテゴリカル変数	なし	なし	あり（Sex）
クラス不均衡	なし	N/A	あり（生存者が少ない）
特徴量数	4個	4個	6個
前処理の複雑度	低	中	高

問題の複雑性

1. 欠損値の戦略的補完

単純な平均値補完ではなく、Pclass（社会階級）と Survived（生存状況）のグループごとに中央値で補完します。これにより、より正確なデータ復元が可能になります。

# 例：1等客室の生存者の平均年齢は35歳、死亡者は43歳
# → グループごとの傾向を反映した補完

2. カテゴリカル変数のエンコーディング

Sex（male/female）という文字列データを、機械学習モデルが扱える数値データに変換する必要があります。

# 変換前: Sex = ['male', 'female', 'male']
# 変換後: male = [1, 0, 1]（0/1 のダミー変数）

3. クラス不均衡への対応

生存者と死亡者の割合が不均衡な場合、単純な訓練では多数派クラスに偏ったモデルになります。class_weight='balanced' パラメータで自動的に調整します。

TDD による実装（6ステップ）

ステップ 1: 初期化とデータ読み込み

Red: テストを書く

test/test_survived_classifier.py:

"""Survived 分類器のテストモジュール"""
import os
import tempfile
import pytest
import pandas as pd
import numpy as np
from src.ml.survived_classifier import SurvivedClassifier


class TestSurvivedClassifierInit:
    """初期化のテスト"""

    def test_初期化_デフォルトパラメータ(self):
        """デフォルトパラメータで初期化できることを確認"""
        classifier = SurvivedClassifier()

        assert classifier.max_depth == 9
        assert classifier.class_weight == 'balanced'
        assert classifier.model is None

    def test_初期化_カスタムパラメータ(self):
        """カスタムパラメータで初期化できることを確認"""
        classifier = SurvivedClassifier(max_depth=5, class_weight='balanced')

        assert classifier.max_depth == 5
        assert classifier.class_weight == 'balanced'

    def test_max_depthが不正な値の場合エラー(self):
        """max_depth が 1 未満の場合は ValueError を発生"""
        with pytest.raises(ValueError, match="max_depth must be at least 1"):
            SurvivedClassifier(max_depth=0)


class TestSurvivedClassifierLoadData:
    """データ読み込みのテスト"""

    def test_CSVファイルの読み込み(self):
        """CSV ファイルが正常に読み込めることを確認"""
        classifier = SurvivedClassifier()

        # テストデータ作成
        test_data = """Pclass,Age,SibSp,Parch,Fare,Sex,Survived
1,22.0,1,0,7.25,male,0
2,38.0,1,0,71.28,female,1
3,26.0,0,0,7.92,male,0"""

        with tempfile.NamedTemporaryFile(mode='w', delete=False, suffix='.csv') as f:
            f.write(test_data)
            temp_path = f.name

        try:
            X, y = classifier.load_data(temp_path, preprocess=False)

            # データが正しく読み込まれることを確認
            assert len(X) == 3
            assert len(y) == 3
            assert 'Survived' not in X.columns
            assert y.name == 'Survived'
        finally:
            os.unlink(temp_path)

    def test_ファイルが存在しない場合エラー(self):
        """存在しないファイルパスを指定した場合 FileNotFoundError を発生"""
        classifier = SurvivedClassifier()

        with pytest.raises(FileNotFoundError):
            classifier.load_data('nonexistent.csv')

    def test_必要な列が不足している場合エラー(self):
        """必要な列が不足している場合 ValueError を発生"""
        classifier = SurvivedClassifier()

        # Survived 列が欠けているデータ
        test_data = """Pclass,Age,Sex
1,22.0,male"""

        with tempfile.NamedTemporaryFile(mode='w', delete=False, suffix='.csv') as f:
            f.write(test_data)
            temp_path = f.name

        try:
            with pytest.raises(ValueError, match="Missing columns"):
                classifier.load_data(temp_path, preprocess=False)
        finally:
            os.unlink(temp_path)

Green: 最小限の実装

src/ml/survived_classifier.py:

"""Survived 生存予測器モジュール"""
import os
from typing import Optional, Tuple
import pandas as pd
import numpy as np
from sklearn import tree


class SurvivedClassifier:
    """客船沈没事故の生存を予測する分類モデル

    Attributes:
        max_depth: 決定木の最大深度
        class_weight: クラスの重み付け（'balanced' で自動調整）
        model: 訓練済みの決定木モデル（未訓練時は None）
    """

    def __init__(self, max_depth: int = 9, class_weight: str = 'balanced') -> None:
        """初期化

        Args:
            max_depth: 決定木の最大深度（デフォルト: 9）
            class_weight: クラス重み付け方法（デフォルト: 'balanced'）

        Raises:
            ValueError: max_depth が 1 未満の場合
        """
        if max_depth < 1:
            raise ValueError("max_depth must be at least 1")

        self.max_depth = max_depth
        self.class_weight = class_weight
        self.model: Optional[tree.DecisionTreeClassifier] = None

    def load_data(self, file_path: str,
                  preprocess: bool = True) -> Tuple[pd.DataFrame, pd.Series]:
        """CSV ファイルからデータを読み込む

        Args:
            file_path: CSV ファイルのパス
            preprocess: 前処理を実行するかどうか（デフォルト: True）

        Returns:
            特徴量 DataFrame と目的変数 Series のタプル

        Raises:
            FileNotFoundError: ファイルが存在しない場合
            ValueError: 必要な列が不足している場合
        """
        if not os.path.exists(file_path):
            raise FileNotFoundError(f"File not found: {file_path}")

        # データの読み込み
        df = pd.read_csv(file_path)

        # 必要な列の存在確認
        required_columns = ['Pclass', 'Age', 'SibSp', 'Parch', 'Fare', 'Sex', 'Survived']
        missing_columns = set(required_columns) - set(df.columns)
        if missing_columns:
            raise ValueError(f"Missing columns: {missing_columns}")

        # 前処理の実行（オプション）
        if preprocess:
            df = self._preprocess_data(df)

        # 特徴量と目的変数の分割
        feature_columns = ['Pclass', 'Age', 'SibSp', 'Parch', 'Fare', 'male']
        if not preprocess:
            # 前処理なしの場合、Sex 列をそのまま使う（テスト用）
            feature_columns = ['Pclass', 'Age', 'SibSp', 'Parch', 'Fare', 'Sex']

        X = df[feature_columns]
        y = df['Survived']

        return X, y

    def _preprocess_data(self, df: pd.DataFrame) -> pd.DataFrame:
        """データの前処理（内部メソッド）

        Args:
            df: 元の DataFrame

        Returns:
            前処理済みの DataFrame
        """
        # ステップ 2 と 3 で実装
        df = self._preprocess_age(df)
        df = self._encode_categorical(df)
        return df

    def _preprocess_age(self, df: pd.DataFrame) -> pd.DataFrame:
        """Age の欠損値をグループ別中央値で補完（ステップ 2 で実装）"""
        return df

    def _encode_categorical(self, df: pd.DataFrame) -> pd.DataFrame:
        """Sex をダミー変数に変換（ステップ 3 で実装）"""
        return df

ステップ 2: グループ別欠損値補完

高度な欠損値処理を TDD で実装します。

Red: テストを書く

class TestSurvivedClassifierPreprocessAge:
    """Age 欠損値補完のテスト"""

    def test_欠損値がない場合は変更なし(self):
        """欠損値がない場合はデータを変更しないことを確認"""
        classifier = SurvivedClassifier()

        df = pd.DataFrame({
            'Pclass': [1, 2, 3],
            'Age': [22.0, 38.0, 26.0],
            'Survived': [0, 1, 0]
        })

        df_processed = classifier._preprocess_age(df.copy())

        pd.testing.assert_frame_equal(df_processed, df)

    def test_1等客室死亡者の年齢補完(self):
        """Pclass=1, Survived=0 の欠損値が 43 で補完されることを確認"""
        classifier = SurvivedClassifier()

        df = pd.DataFrame({
            'Pclass': [1, 1],
            'Age': [np.nan, 50.0],
            'Survived': [0, 0]
        })

        df_processed = classifier._preprocess_age(df)

        assert df_processed.iloc[0]['Age'] == 43
        assert df_processed.iloc[1]['Age'] == 50.0

    def test_1等客室生存者の年齢補完(self):
        """Pclass=1, Survived=1 の欠損値が 35 で補完されることを確認"""
        classifier = SurvivedClassifier()

        df = pd.DataFrame({
            'Pclass': [1],
            'Age': [np.nan],
            'Survived': [1]
        })

        df_processed = classifier._preprocess_age(df)

        assert df_processed.iloc[0]['Age'] == 35

    def test_全グループの年齢補完(self):
        """全グループの欠損値が正しく補完されることを確認"""
        classifier = SurvivedClassifier()

        # 各グループの組み合わせで欠損値を作成
        df = pd.DataFrame({
            'Pclass': [1, 1, 2, 2, 3, 3],
            'Age': [np.nan, np.nan, np.nan, np.nan, np.nan, np.nan],
            'Survived': [0, 1, 0, 1, 0, 1]
        })

        df_processed = classifier._preprocess_age(df)

        # グループ別の期待値
        expected_ages = [43, 35, 33, 25, 26, 20]
        actual_ages = df_processed['Age'].tolist()

        assert actual_ages == expected_ages

    def test_一部のみ欠損値がある場合(self):
        """一部だけ欠損値がある場合、該当データのみ補完されることを確認"""
        classifier = SurvivedClassifier()

        df = pd.DataFrame({
            'Pclass': [1, 1, 2, 2],
            'Age': [np.nan, 30.0, 25.0, np.nan],
            'Survived': [0, 1, 0, 1]
        })

        df_processed = classifier._preprocess_age(df)

        assert df_processed.iloc[0]['Age'] == 43  # 補完
        assert df_processed.iloc[1]['Age'] == 30.0  # 元のまま
        assert df_processed.iloc[2]['Age'] == 25.0  # 元のまま
        assert df_processed.iloc[3]['Age'] == 25  # 補完

Green: 実装

def _preprocess_age(self, df: pd.DataFrame) -> pd.DataFrame:
    """Age の欠損値を Pclass と Survived のグループ別中央値で補完

    Args:
        df: 元の DataFrame

    Returns:
        Age の欠損値が補完された DataFrame

    Note:
        各グループの中央値は実データ分析により決定：
        - (Pclass=1, Survived=0): 43歳
        - (Pclass=1, Survived=1): 35歳
        - (Pclass=2, Survived=0): 33歳
        - (Pclass=2, Survived=1): 25歳
        - (Pclass=3, Survived=0): 26歳
        - (Pclass=3, Survived=1): 20歳
    """
    df_copy = df.copy()
    is_null = df_copy['Age'].isnull()

    # グループ別の中央値マッピング
    age_mapping = {
        (1, 0): 43, (1, 1): 35,
        (2, 0): 33, (2, 1): 25,
        (3, 0): 26, (3, 1): 20
    }

    # 各グループの欠損値を中央値で補完
    for (pclass, survived), median_age in age_mapping.items():
        mask = (df_copy['Pclass'] == pclass) & \
               (df_copy['Survived'] == survived) & is_null
        df_copy.loc[mask, 'Age'] = median_age

    return df_copy

ステップ 3: カテゴリカル変数のエンコーディング

Sex（male/female）をダミー変数に変換します。

Red: テストを書く

class TestSurvivedClassifierEncodeCategorical:
    """カテゴリカル変数エンコーディングのテスト"""

    def test_Sex列がmale列に変換される(self):
        """Sex 列が male ダミー変数に変換されることを確認"""
        classifier = SurvivedClassifier()

        df = pd.DataFrame({
            'Pclass': [1, 2, 3],
            'Sex': ['male', 'female', 'male'],
            'Survived': [0, 1, 0]
        })

        df_encoded = classifier._encode_categorical(df)

        assert 'male' in df_encoded.columns
        assert 'Sex' not in df_encoded.columns

    def test_male列の値が正しい(self):
        """male 列の値が正しいことを確認（male=1, female=0）"""
        classifier = SurvivedClassifier()

        df = pd.DataFrame({
            'Sex': ['male', 'female', 'male', 'female']
        })

        df_encoded = classifier._encode_categorical(df)

        expected_male_values = [1, 0, 1, 0]
        actual_male_values = df_encoded['male'].tolist()

        assert actual_male_values == expected_male_values

    def test_他の列は保持される(self):
        """Sex 以外の列は保持されることを確認"""
        classifier = SurvivedClassifier()

        df = pd.DataFrame({
            'Pclass': [1, 2],
            'Age': [22.0, 38.0],
            'Sex': ['male', 'female'],
            'Survived': [0, 1]
        })

        df_encoded = classifier._encode_categorical(df)

        assert 'Pclass' in df_encoded.columns
        assert 'Age' in df_encoded.columns
        assert 'Survived' in df_encoded.columns
        assert df_encoded['Pclass'].tolist() == [1, 2]
        assert df_encoded['Age'].tolist() == [22.0, 38.0]

Green: 実装

def _encode_categorical(self, df: pd.DataFrame) -> pd.DataFrame:
    """Sex をダミー変数に変換

    Args:
        df: 元の DataFrame

    Returns:
        Sex がダミー変数化された DataFrame

    Note:
        drop_first=True により、male 列のみ作成（female は 0/1 で表現）
        これにより多重共線性を回避
    """
    df_copy = df.copy()

    # Sex をダミー変数化（drop_first=True で male 列のみ作成）
    male = pd.get_dummies(df_copy['Sex'], drop_first=True, dtype=int)
    df_encoded = pd.concat([df_copy.drop('Sex', axis=1), male], axis=1)

    return df_encoded

ステップ 4: モデルの訓練（class_weight 対応）

クラス不均衡に対応した訓練を実装します。

Red: テストを書く

class TestSurvivedClassifierTrain:
    """訓練のテスト"""

    def test_モデルが訓練される(self):
        """訓練後にモデルが設定されることを確認"""
        classifier = SurvivedClassifier()

        # ダミーデータ
        X_train = pd.DataFrame({
            'Pclass': [1, 2, 3],
            'Age': [22.0, 38.0, 26.0],
            'SibSp': [1, 1, 0],
            'Parch': [0, 0, 0],
            'Fare': [7.25, 71.28, 7.92],
            'male': [1, 0, 1]
        })
        y_train = pd.Series([0, 1, 0])

        classifier.train(X_train, y_train)

        assert classifier.model is not None

    def test_訓練されていない状態で予測するとエラー(self):
        """訓練前に予測しようとすると RuntimeError を発生"""
        classifier = SurvivedClassifier()

        X_test = pd.DataFrame({'Pclass': [1], 'Age': [22.0],
                               'SibSp': [1], 'Parch': [0],
                               'Fare': [7.25], 'male': [1]})

        with pytest.raises(RuntimeError, match="Model has not been trained yet"):
            classifier.predict(X_test)

    def test_class_weightパラメータが適用される(self):
        """class_weight パラメータがモデルに適用されることを確認"""
        classifier = SurvivedClassifier(class_weight='balanced')

        X_train = pd.DataFrame({
            'Pclass': [1, 2, 3],
            'Age': [22.0, 38.0, 26.0],
            'SibSp': [1, 1, 0],
            'Parch': [0, 0, 0],
            'Fare': [7.25, 71.28, 7.92],
            'male': [1, 0, 1]
        })
        y_train = pd.Series([0, 1, 0])

        classifier.train(X_train, y_train)

        assert classifier.model.class_weight == 'balanced'

    def test_max_depthパラメータが適用される(self):
        """max_depth パラメータがモデルに適用されることを確認"""
        classifier = SurvivedClassifier(max_depth=5)

        X_train = pd.DataFrame({
            'Pclass': [1, 2, 3],
            'Age': [22.0, 38.0, 26.0],
            'SibSp': [1, 1, 0],
            'Parch': [0, 0, 0],
            'Fare': [7.25, 71.28, 7.92],
            'male': [1, 0, 1]
        })
        y_train = pd.Series([0, 1, 0])

        classifier.train(X_train, y_train)

        assert classifier.model.max_depth == 5

Green: 実装

def train(self, X_train: pd.DataFrame, y_train: pd.Series) -> None:
    """モデルを訓練する

    Args:
        X_train: 訓練用特徴量
        y_train: 訓練用目的変数

    Note:
        class_weight='balanced' により、クラス不均衡を自動的に調整
    """
    self.model = tree.DecisionTreeClassifier(
        max_depth=self.max_depth,
        random_state=0,
        class_weight=self.class_weight
    )
    self.model.fit(X_train, y_train)

ステップ 5: 予測と評価

def predict(self, X_test: pd.DataFrame) -> np.ndarray:
    """予測を実行する

    Args:
        X_test: テスト用特徴量

    Returns:
        予測結果の配列

    Raises:
        RuntimeError: モデルが訓練されていない場合
    """
    if self.model is None:
        raise RuntimeError("Model has not been trained yet. Call train() first.")

    return self.model.predict(X_test)

def evaluate(self, X_test: pd.DataFrame, y_test: pd.Series) -> float:
    """モデルを評価する

    Args:
        X_test: テスト用特徴量
        y_test: テスト用目的変数

    Returns:
        正解率（accuracy）

    Raises:
        RuntimeError: モデルが訓練されていない場合
    """
    if self.model is None:
        raise RuntimeError("Model has not been trained yet. Call train() first.")

    return self.model.score(X_test, y_test)

ステップ 6: モデルの永続化

import pickle

def save_model(self, file_path: str) -> None:
    """訓練済みモデルをファイルに保存する

    Args:
        file_path: 保存先ファイルパス

    Raises:
        RuntimeError: モデルが訓練されていない場合
    """
    if self.model is None:
        raise RuntimeError("Model has not been trained yet. Call train() first.")

    with open(file_path, 'wb') as f:
        pickle.dump(self.model, f)

def load_model(self, file_path: str) -> None:
    """保存されたモデルをファイルから読み込む

    Args:
        file_path: モデルファイルのパス

    Raises:
        FileNotFoundError: ファイルが存在しない場合
    """
    if not os.path.exists(file_path):
        raise FileNotFoundError(f"Model file not found: {file_path}")

    with open(file_path, 'rb') as f:
        self.model = pickle.load(f)

完全な SurvivedClassifier 実装

src/ml/survived_classifier.py (完全版):

"""Survived 生存予測器モジュール"""
import os
import pickle
from typing import Optional, Tuple
import pandas as pd
import numpy as np
from sklearn import tree


class SurvivedClassifier:
    """客船沈没事故の生存を予測する分類モデル

    Attributes:
        max_depth: 決定木の最大深度
        class_weight: クラスの重み付け（'balanced' で自動調整）
        model: 訓練済みの決定木モデル（未訓練時は None）

    Example:
        >>> classifier = SurvivedClassifier()
        >>> X_train, y_train = classifier.load_data('data/Survived.csv')
        >>> from sklearn.model_selection import train_test_split
        >>> X_train, X_test, y_train, y_test = train_test_split(
        ...     X_train, y_train, test_size=0.2, random_state=0)
        >>> classifier.train(X_train, y_train)
        >>> accuracy = classifier.evaluate(X_test, y_test)
        >>> print(f"Accuracy: {accuracy:.4f}")
    """

    def __init__(self, max_depth: int = 9, class_weight: str = 'balanced') -> None:
        """初期化

        Args:
            max_depth: 決定木の最大深度（デフォルト: 9）
            class_weight: クラス重み付け方法（デフォルト: 'balanced'）

        Raises:
            ValueError: max_depth が 1 未満の場合
        """
        if max_depth < 1:
            raise ValueError("max_depth must be at least 1")

        self.max_depth = max_depth
        self.class_weight = class_weight
        self.model: Optional[tree.DecisionTreeClassifier] = None

    def load_data(self, file_path: str,
                  preprocess: bool = True) -> Tuple[pd.DataFrame, pd.Series]:
        """CSV ファイルからデータを読み込む

        Args:
            file_path: CSV ファイルのパス
            preprocess: 前処理を実行するかどうか（デフォルト: True）

        Returns:
            特徴量 DataFrame と目的変数 Series のタプル

        Raises:
            FileNotFoundError: ファイルが存在しない場合
            ValueError: 必要な列が不足している場合
        """
        if not os.path.exists(file_path):
            raise FileNotFoundError(f"File not found: {file_path}")

        # データの読み込み
        df = pd.read_csv(file_path)

        # 必要な列の存在確認
        required_columns = ['Pclass', 'Age', 'SibSp', 'Parch', 'Fare', 'Sex', 'Survived']
        missing_columns = set(required_columns) - set(df.columns)
        if missing_columns:
            raise ValueError(f"Missing columns: {missing_columns}")

        # 前処理の実行（オプション）
        if preprocess:
            df = self._preprocess_data(df)

        # 特徴量と目的変数の分割
        feature_columns = ['Pclass', 'Age', 'SibSp', 'Parch', 'Fare', 'male']
        if not preprocess:
            # 前処理なしの場合、Sex 列をそのまま使う（テスト用）
            feature_columns = ['Pclass', 'Age', 'SibSp', 'Parch', 'Fare', 'Sex']

        X = df[feature_columns]
        y = df['Survived']

        return X, y

    def _preprocess_data(self, df: pd.DataFrame) -> pd.DataFrame:
        """データの前処理（内部メソッド）

        Args:
            df: 元の DataFrame

        Returns:
            前処理済みの DataFrame
        """
        df = self._preprocess_age(df)
        df = self._encode_categorical(df)
        return df

    def _preprocess_age(self, df: pd.DataFrame) -> pd.DataFrame:
        """Age の欠損値を Pclass と Survived のグループ別中央値で補完

        Args:
            df: 元の DataFrame

        Returns:
            Age の欠損値が補完された DataFrame

        Note:
            各グループの中央値は実データ分析により決定：
            - (Pclass=1, Survived=0): 43歳
            - (Pclass=1, Survived=1): 35歳
            - (Pclass=2, Survived=0): 33歳
            - (Pclass=2, Survived=1): 25歳
            - (Pclass=3, Survived=0): 26歳
            - (Pclass=3, Survived=1): 20歳
        """
        df_copy = df.copy()
        is_null = df_copy['Age'].isnull()

        # グループ別の中央値マッピング
        age_mapping = {
            (1, 0): 43, (1, 1): 35,
            (2, 0): 33, (2, 1): 25,
            (3, 0): 26, (3, 1): 20
        }

        # 各グループの欠損値を中央値で補完
        for (pclass, survived), median_age in age_mapping.items():
            mask = (df_copy['Pclass'] == pclass) & \
                   (df_copy['Survived'] == survived) & is_null
            df_copy.loc[mask, 'Age'] = median_age

        return df_copy

    def _encode_categorical(self, df: pd.DataFrame) -> pd.DataFrame:
        """Sex をダミー変数に変換

        Args:
            df: 元の DataFrame

        Returns:
            Sex がダミー変数化された DataFrame

        Note:
            drop_first=True により、male 列のみ作成（female は 0/1 で表現）
            これにより多重共線性を回避
        """
        df_copy = df.copy()

        # Sex をダミー変数化（drop_first=True で male 列のみ作成）
        male = pd.get_dummies(df_copy['Sex'], drop_first=True, dtype=int)
        df_encoded = pd.concat([df_copy.drop('Sex', axis=1), male], axis=1)

        return df_encoded

    def train(self, X_train: pd.DataFrame, y_train: pd.Series) -> None:
        """モデルを訓練する

        Args:
            X_train: 訓練用特徴量
            y_train: 訓練用目的変数

        Note:
            class_weight='balanced' により、クラス不均衡を自動的に調整
        """
        self.model = tree.DecisionTreeClassifier(
            max_depth=self.max_depth,
            random_state=0,
            class_weight=self.class_weight
        )
        self.model.fit(X_train, y_train)

    def predict(self, X_test: pd.DataFrame) -> np.ndarray:
        """予測を実行する

        Args:
            X_test: テスト用特徴量

        Returns:
            予測結果の配列（0: 死亡, 1: 生存）

        Raises:
            RuntimeError: モデルが訓練されていない場合
        """
        if self.model is None:
            raise RuntimeError("Model has not been trained yet. Call train() first.")

        return self.model.predict(X_test)

    def evaluate(self, X_test: pd.DataFrame, y_test: pd.Series) -> float:
        """モデルを評価する

        Args:
            X_test: テスト用特徴量
            y_test: テスト用目的変数

        Returns:
            正解率（accuracy）

        Raises:
            RuntimeError: モデルが訓練されていない場合
        """
        if self.model is None:
            raise RuntimeError("Model has not been trained yet. Call train() first.")

        return self.model.score(X_test, y_test)

    def save_model(self, file_path: str) -> None:
        """訓練済みモデルをファイルに保存する

        Args:
            file_path: 保存先ファイルパス

        Raises:
            RuntimeError: モデルが訓練されていない場合
        """
        if self.model is None:
            raise RuntimeError("Model has not been trained yet. Call train() first.")

        with open(file_path, 'wb') as f:
            pickle.dump(self.model, f)

    def load_model(self, file_path: str) -> None:
        """保存されたモデルをファイルから読み込む

        Args:
            file_path: モデルファイルのパス

        Raises:
            FileNotFoundError: ファイルが存在しない場合
        """
        if not os.path.exists(file_path):
            raise FileNotFoundError(f"Model file not found: {file_path}")

        with open(file_path, 'rb') as f:
            self.model = pickle.load(f)

実践的な訓練スクリプト

script/train_survived.py:

"""Survived 生存予測モデルの訓練スクリプト"""
from sklearn.model_selection import train_test_split
from src.ml.survived_classifier import SurvivedClassifier


def main():
    """メイン処理"""
    # 分類器の作成
    classifier = SurvivedClassifier(max_depth=9, class_weight='balanced')
    print("SurvivedClassifier を作成しました")

    # データの読み込みと前処理
    X, y = classifier.load_data('data/Survived.csv', preprocess=True)
    print(f"データを読み込みました: {len(X)} サンプル")

    # 訓練データとテストデータに分割
    X_train, X_test, y_train, y_test = train_test_split(
        X, y, test_size=0.2, random_state=0
    )
    print(f"訓練データ: {len(X_train)} サンプル")
    print(f"テストデータ: {len(X_test)} サンプル")

    # クラス分布の確認
    survived_count = y_train.sum()
    total_count = len(y_train)
    print(f"\n[訓練データのクラス分布]")
    print(f"  生存: {survived_count} ({survived_count/total_count*100:.1f}%)")
    print(f"  死亡: {total_count - survived_count} ({(total_count-survived_count)/total_count*100:.1f}%)")

    # モデルの訓練
    classifier.train(X_train, y_train)
    print("\nモデルの訓練が完了しました")

    # 特徴量の重要度表示
    print("\n[特徴量の重要度]")
    feature_names = ['Pclass', 'Age', 'SibSp', 'Parch', 'Fare', 'male']
    importances = classifier.model.feature_importances_

    # 重要度でソート
    sorted_indices = sorted(range(len(importances)),
                           key=lambda i: importances[i], reverse=True)

    for idx in sorted_indices:
        print(f"  {feature_names[idx]}: {importances[idx]:.4f}")

    # モデルの評価
    accuracy = classifier.evaluate(X_test, y_test)
    print(f"\n[モデルの評価]")
    print(f"  正解率（Accuracy）: {accuracy:.4f}")

    # モデルの保存
    classifier.save_model('model/survived.pkl')
    print("\nモデルを model/survived.pkl に保存しました")

    # 予測例
    print("\n[予測例]")
    sample = X_test.iloc[:5]
    predictions = classifier.predict(sample)

    for i, (idx, row) in enumerate(sample.iterrows()):
        actual = y_test.iloc[i]
        predicted = predictions[i]
        result = "✓" if actual == predicted else "✗"

        print(f"\nサンプル {i+1}: {result}")
        print(f"  Pclass: {int(row['Pclass'])}, Age: {row['Age']:.0f}, "
              f"Sex: {'male' if row['male'] == 1 else 'female'}")
        print(f"  SibSp: {int(row['SibSp'])}, Parch: {int(row['Parch'])}, "
              f"Fare: {row['Fare']:.2f}")
        print(f"  実際: {'生存' if actual == 1 else '死亡'}")
        print(f"  予測: {'生存' if predicted == 1 else '死亡'}")


if __name__ == '__main__':
    main()

実行例：

uv run python script/train_survived.py

# 出力例：
# SurvivedClassifier を作成しました
# データを読み込みました: 891 サンプル
# 訓練データ: 712 サンプル
# テストデータ: 179 サンプル
#
# [訓練データのクラス分布]
#   生存: 267 (37.5%)
#   死亡: 445 (62.5%)
#
# モデルの訓練が完了しました
#
# [特徴量の重要度]
#   male: 0.4235
#   Fare: 0.2134
#   Age: 0.1823
#   Pclass: 0.1245
#   Parch: 0.0345
#   SibSp: 0.0218
#
# [モデルの評価]
#   正解率（Accuracy）: 0.8324
#
# モデルを model/survived.pkl に保存しました
#
# [予測例]
#
# サンプル 1: ✓
#   Pclass: 3, Age: 22, Sex: male
#   SibSp: 1, Parch: 0, Fare: 7.25
#   実際: 死亡
#   予測: 死亡
#
# サンプル 2: ✓
#   Pclass: 1, Age: 38, Sex: female
#   SibSp: 1, Parch: 0, Fare: 71.28
#   実際: 生存
#   予測: 生存
#
# サンプル 3: ✗
#   Pclass: 3, Age: 26, Sex: male
#   SibSp: 0, Parch: 0, Fare: 7.92
#   実際: 生存
#   予測: 死亡

📓 Jupyter Notebook での探索と視覚化

実践的な分類問題では、データの性質を深く理解することが成功の鍵です。Jupyter Notebook で詳しく分析しましょう！

🎯 この節の目的

データの傾向を視覚的に把握する - 生存率に影響する要因を発見
クラス不均衡の影響を理解する - 偏ったデータでの対策
モデルの判断基準を可視化する - 誤分類のパターンを発見

📝 Notebook の作成

cd app/python/ml_tdd
uv run jupyter lab

notebook/ ディレクトリに survived_exploration.ipynb を作成しましょう。

1️⃣ 環境セットアップとデータ読み込み

# セル 1: ライブラリのインポート
import sys
sys.path.append('..')

import pandas as pd
import numpy as np
import matplotlib.pyplot as plt
import seaborn as sns
from sklearn.model_selection import train_test_split
from sklearn.metrics import confusion_matrix, classification_report, roc_curve, roc_auc_score

# 日本語フォント設定
plt.rcParams['font.sans-serif'] = ['MS Gothic']
plt.rcParams['axes.unicode_minus'] = False

# スタイル設定
sns.set_style("whitegrid")
sns.set_palette("Set2")

print("✅ 環境セットアップ完了")

# セル 2: データの読み込み
from src.ml.survived_classifier import SurvivedClassifier

classifier = SurvivedClassifier()
X, y = classifier.load_data('data/Survived.csv')

print(f"データ形状: X={X.shape}, y={y.shape}")
print(f"\n特徴量:\n{X.columns.tolist()}")
print(f"\nクラス分布:\n{y.value_counts()}")
print(f"\n生存率: {(y == 1).sum() / len(y) * 100:.2f}%")

2️⃣ クラス不均衡の確認

# セル 3: クラス分布の可視化
fig, (ax1, ax2) = plt.subplots(1, 2, figsize=(12, 5))

# 棒グラフ
y.value_counts().plot(kind='bar', ax=ax1, color=['#e74c3c', '#3498db'])
ax1.set_xlabel('クラス (0=死亡, 1=生存)', fontsize=12)
ax1.set_ylabel('サンプル数', fontsize=12)
ax1.set_title('クラス分布', fontsize=14)
ax1.set_xticklabels(['死亡 (0)', '生存 (1)'], rotation=0)
for i, v in enumerate(y.value_counts()):
    ax1.text(i, v + 10, str(v), ha='center', fontsize=12)

# 円グラフ
y.value_counts().plot(kind='pie', ax=ax2, autopct='%1.1f%%',
                      colors=['#e74c3c', '#3498db'],
                      labels=['死亡', '生存'])
ax2.set_ylabel('')
ax2.set_title('クラス比率', fontsize=14)

plt.tight_layout()
plt.show()

# 不均衡率
imbalance_ratio = y.value_counts()[0] / y.value_counts()[1]
print(f"\nクラス不均衡率: {imbalance_ratio:.2f} (死亡/生存)")
print(f"→ 死亡クラスが生存クラスの {imbalance_ratio:.1f} 倍")

クラス不均衡から分かること：

約 62% が死亡、38% が生存
このままでは「全員死亡」と予測すれば 62% の正解率
class_weight='balanced' で対策が必要

3️⃣ 特徴量とクラスの関係分析

# セル 4: 性別と生存率の関係
df_analysis = X.copy()
df_analysis['Survived'] = y

fig, axes = plt.subplots(1, 2, figsize=(14, 5))

# 性別ごとの生存率
gender_survival = df_analysis.groupby('male')['Survived'].mean()
ax = axes[0]
bars = ax.bar(['女性 (male=0)', '男性 (male=1)'], gender_survival, color=['#e91e63', '#2196f3'])
ax.set_ylabel('生存率', fontsize=12)
ax.set_title('性別ごとの生存率', fontsize=14)
ax.set_ylim([0, 1])
for bar in bars:
    height = bar.get_height()
    ax.text(bar.get_x() + bar.get_width()/2., height + 0.02,
            f'{height:.1%}', ha='center', fontsize=12)

# 客室クラスごとの生存率
pclass_survival = df_analysis.groupby('Pclass')['Survived'].mean()
ax = axes[1]
bars = ax.bar(['1等 (上流)', '2等 (中流)', '3等 (下流)'], pclass_survival,
              color=['#ffd700', '#c0c0c0', '#cd7f32'])
ax.set_ylabel('生存率', fontsize=12)
ax.set_title('客室クラスごとの生存率', fontsize=14)
ax.set_ylim([0, 1])
for bar in bars:
    height = bar.get_height()
    ax.text(bar.get_x() + bar.get_width()/2., height + 0.02,
            f'{height:.1%}', ha='center', fontsize=12)

plt.tight_layout()
plt.show()

print("生存率の統計:")
print(f"  女性: {gender_survival[0]:.1%}")
print(f"  男性: {gender_survival[1]:.1%}")
print(f"  1等客: {pclass_survival[1]:.1%}")
print(f"  2等客: {pclass_survival[2]:.1%}")
print(f"  3等客: {pclass_survival[3]:.1%}")

「女性と子供を優先」の証拠がデータに！

4️⃣ モデルの訓練と評価

# セル 5: データ分割と訓練
X_train, X_test, y_train, y_test = train_test_split(
    X, y, test_size=0.2, random_state=0
)

classifier.train(X_train, y_train)
y_pred = classifier.predict(X_test)

accuracy = classifier.evaluate(X_test, y_test)
print(f"正解率: {accuracy:.4f}")

# 詳細レポート
print("\n分類レポート:")
print(classification_report(y_test, y_pred, target_names=['死亡', '生存']))

5️⃣ 混同行列の可視化

# セル 6: 混同行列
cm = confusion_matrix(y_test, y_pred)

plt.figure(figsize=(8, 6))
sns.heatmap(cm, annot=True, fmt='d', cmap='Blues',
            xticklabels=['死亡 (0)', '生存 (1)'],
            yticklabels=['死亡 (0)', '生存 (1)'])
plt.title('混同行列 (Confusion Matrix)', fontsize=14)
plt.ylabel('実際のクラス', fontsize=12)
plt.xlabel('予測クラス', fontsize=12)
plt.tight_layout()
plt.show()

# 混同行列の詳細分析
tn, fp, fn, tp = cm.ravel()
print("\n混同行列の詳細:")
print(f"  真陰性 (TN): {tn} - 正しく「死亡」と予測")
print(f"  偽陽性 (FP): {fp} - 誤って「生存」と予測")
print(f"  偽陰性 (FN): {fn} - 誤って「死亡」と予測")
print(f"  真陽性 (TP): {tp} - 正しく「生存」と予測")

# 各種指標
precision = tp / (tp + fp) if (tp + fp) > 0 else 0
recall = tp / (tp + fn) if (tp + fn) > 0 else 0
f1 = 2 * precision * recall / (precision + recall) if (precision + recall) > 0 else 0

print(f"\n性能指標:")
print(f"  適合率 (Precision): {precision:.3f}")
print(f"  再現率 (Recall): {recall:.3f}")
print(f"  F1スコア: {f1:.3f}")

6️⃣ ROC 曲線と AUC

# セル 7: ROC 曲線
# 予測確率を取得
y_pred_proba = classifier.model.predict_proba(X_test)[:, 1]

# ROC 曲線の計算
fpr, tpr, thresholds = roc_curve(y_test, y_pred_proba)
auc_score = roc_auc_score(y_test, y_pred_proba)

# 可視化
plt.figure(figsize=(8, 6))
plt.plot(fpr, tpr, color='darkorange', lw=2, label=f'ROC curve (AUC = {auc_score:.3f})')
plt.plot([0, 1], [0, 1], color='navy', lw=2, linestyle='--', label='ランダム予測')
plt.xlim([0.0, 1.0])
plt.ylim([0.0, 1.05])
plt.xlabel('偽陽性率 (False Positive Rate)', fontsize=12)
plt.ylabel('真陽性率 (True Positive Rate)', fontsize=12)
plt.title('ROC 曲線', fontsize=14)
plt.legend(loc="lower right")
plt.grid(True, alpha=0.3)
plt.tight_layout()
plt.show()

print(f"AUC スコア: {auc_score:.3f}")
print("AUC の解釈:")
print("  0.9-1.0: 優秀")
print("  0.8-0.9: 良い")
print("  0.7-0.8: まあまあ")
print("  0.6-0.7: 微妙")
print("  0.5-0.6: ほぼランダム")

7️⃣ 特徴量の重要度

# セル 8: 特徴量重要度の可視化
importances = classifier.model.feature_importances_
feature_importance_df = pd.DataFrame({
    'feature': X.columns,
    'importance': importances
}).sort_values('importance', ascending=False)

plt.figure(figsize=(10, 6))
sns.barplot(data=feature_importance_df, x='importance', y='feature', palette='viridis')
plt.title('特徴量の重要度', fontsize=14)
plt.xlabel('重要度スコア', fontsize=12)
plt.ylabel('特徴量', fontsize=12)
plt.tight_layout()
plt.show()

print("\n特徴量重要度ランキング:")
for idx, row in feature_importance_df.iterrows():
    print(f"  {row['feature']:10s}: {row['importance']:.4f}")

重要度から学べること：

male（性別）が最も重要 → 「女性と子供を優先」
Fare（運賃）が2番目 → 裕福な人ほど生存率が高い
Age（年齢）も重要 → 若い人の生存率が高い

8️⃣ 誤分類サンプルの分析

# セル 9: 誤分類されたサンプルの分析
test_df = X_test.copy()
test_df['actual'] = y_test.values
test_df['predicted'] = y_pred
test_df['correct'] = test_df['actual'] == test_df['predicted']

# 誤分類のみ抽出
misclassified = test_df[~test_df['correct']]

print(f"誤分類サンプル数: {len(misclassified)} / {len(test_df)} ({len(misclassified)/len(test_df)*100:.1f}%)")

# 誤分類のパターン分析
print("\n誤分類の内訳:")
false_positive = ((test_df['actual'] == 0) & (test_df['predicted'] == 1)).sum()
false_negative = ((test_df['actual'] == 1) & (test_df['predicted'] == 0)).sum()
print(f"  偽陽性 (死亡→生存と誤予測): {false_positive}")
print(f"  偽陰性 (生存→死亡と誤予測): {false_negative}")

# 誤分類されやすい特徴の分析
print("\n誤分類サンプルの平均:")
print(misclassified[['Pclass', 'Age', 'SibSp', 'Parch', 'Fare', 'male']].mean())
print("\n正しく分類されたサンプルの平均:")
print(test_df[test_df['correct']][['Pclass', 'Age', 'SibSp', 'Parch', 'Fare', 'male']].mean())

9️⃣ 決定木の可視化

# セル 10: 決定木構造の可視化
from sklearn import tree

plt.figure(figsize=(20, 10))
tree.plot_tree(
    classifier.model,
    feature_names=X.columns,
    class_names=['死亡', '生存'],
    filled=True,
    rounded=True,
    fontsize=10
)
plt.title('決定木の構造', fontsize=16)
plt.tight_layout()
plt.show()

print("✅ 決定木の可視化完了！")
print("   根ノードから見ると、最も重要な判断基準が分かります")

💡 実践的分類問題での Notebook 活用ポイント

✅ やること	❌ 避けること
クラス不均衡を必ず確認	正解率だけで判断
混同行列で誤分類パターンを分析	AUC を無視する
特徴量と目的変数の関係を可視化	データの傾向を見ない
誤分類サンプルの特徴を調査	成功例だけ見る

🔄 探索から本番コードへ

# 発見 1: 性別が最重要特徴
# ↓ ドキュメントに反映
# README に「性別が生存に最も影響する」と記載

# 発見 2: クラス不均衡率 1.67
# ↓ テストに反映
def test_クラス重み付けの効果(self):
    """class_weight='balanced' が不均衡に対応していることを確認"""
    # 不均衡データでの性能を検証
    assert classifier.class_weight == 'balanced'

# 発見 3: 誤分類は主に中間的な特徴量を持つサンプル
# ↓ 改善案
# - 特徴量エンジニアリング: 交互作用項の追加
# - モデルの複雑化: max_depth の調整

📊 ６章の技術的成果

「実践的な分類問題もクリアしました！」お疲れさまでした！６章で何を達成したか、振り返ってみましょう。

✅ 完成した機能

６章では、以下の機能を実装しました：

✅ Survived 分類器クラスの完全実装 - 生存を予測するモデル
✅ グループ別欠損値補完機能 - 高度なデータ処理
✅ カテゴリカル変数のダミー変数化 - 文字列を数値に変換
✅ クラス重み付き決定木モデル - 不均衡データへの対応
✅ 特徴量重要度の分析 - どの特徴が重要かを分析
✅ モデルの保存と読み込み機能 - モデルの再利用

📈 定量的成果

数字で見ると、こんなに達成しました！

指標	🎯 実績
🧪 テストケース	22 個
📊 コードカバレッジ	90%（survived_classifier.py）
🔤 型ヒント使用率	100%
⛴️ モデル正解率	83.24%（テストデータ）
✨ Ruff チェック	全て通過
✅ mypy チェック	エラー 0 件
🔧 循環的複雑度	最大 5（全関数）

83.24% の正解率！ 実際のデータ（欠損値あり）でこの精度は素晴らしいです！🎉

🎓 習得したスキル

1. 🔄 TDD スキル（高度）

✅ 複雑な前処理ロジックのテスト駆動実装
✅ グループ処理のテストケース設計
✅ カテゴリカル変数のテスト

2. 🔧 データ前処理スキル（実践）

✅ グループ別統計による欠損値補完
✅ カテゴリカル変数のエンコーディング
✅ 多重共線性の回避（drop_first）

3. 🤖 機械学習スキル（分類応用）

✅ クラス不均衡への対応
✅ 特徴量重要度の理解と活用
✅ class_weight パラメータの効果

4. データ分析スキル

クラス分布の確認と理解
特徴量の影響度分析
モデルの解釈可能性向上

グループ別欠損値補完の理解

なぜグループ別補完が重要か:

# 単純な平均値補完
# → 全年齢層の平均（例: 29歳）で補完
# 問題: 1等客室の高齢者と3等客室の若者を区別できない

# グループ別中央値補完
# → Pclass と Survived ごとの中央値で補完
# 利点: より正確な年齢推定が可能

# 例:
# 1等客室の死亡者: 平均43歳（高齢富裕層）
# 3等客室の生存者: 平均20歳（若い移民層）

カテゴリカル変数エンコーディングの理解

ダミー変数化の仕組み:

# 元データ:
# Sex = ['male', 'female', 'male']

# pd.get_dummies(drop_first=False)  # 両方の列を作成
# → male = [1, 0, 1]
# → female = [0, 1, 0]
# 問題: male と female が完全に逆なので冗長（多重共線性）

# pd.get_dummies(drop_first=True)  # male 列のみ作成
# → male = [1, 0, 1]
# 解釈: 1=male, 0=female
# 利点: 1列で表現できて効率的

クラス不均衡への対応

class_weight='balanced' の効果:

# データセットの分布
# 生存: 267人（37.5%）
# 死亡: 445人（62.5%）

# class_weight=None（デフォルト）
# → モデルが多数派クラス（死亡）に偏る
# → 「全員死亡」と予測しても 62.5% の正解率

# class_weight='balanced'
# → 少数派クラス（生存）のサンプルに大きな重みを付与
# → バランスの取れた予測が可能（正解率 83.24%）

重み計算式：

weight[class_i] = n_samples / (n_classes * n_samples[class_i])

例：
weight[生存] = 712 / (2 * 267) ≈ 1.33
weight[死亡] = 712 / (2 * 445) ≈ 0.80

分類モデルの比較（Iris vs Survived）

項目	Iris（基礎）	Survived（実践）
モデル	DecisionTreeClassifier	DecisionTreeClassifier
クラス数	3クラス	2クラス（二値分類）
前処理	平均値補完のみ	グループ別補完 + エンコーディング
カテゴリカル変数	なし	あり（Sex）
クラス不均衡対応	なし	class_weight='balanced'
max_depth	2	9
テスト数	18個	22個
正解率	97.78%	83.24%

正解率の違いの理由:

Iris: 明確に分離可能な3つの種類（データが「きれい」）
Survived: 複雑な社会的要因（データが「現実的」）
- 生存には運の要素も関与
- 特徴量だけでは説明できない部分がある

🚀 次の章への準備

６章では、実践的な分類問題を解決しました！次の７章では、以下を実装します：

🏠 Boston 住宅価格予測モデル - 高度な回帰問題
⚙️ 特徴量エンジニアリング - 2 乗項・交互作用項で表現力向上
📊 データ標準化 - StandardScaler による正規化
💾 複数モデルの管理 - モデル + スケーラーの一括管理

より高度な回帰テクニックを学びます！楽しみですね！🚀

７章 Boston 住宅価格予測モデル（高度な回帰問題）

「回帰問題の基礎は学んだけど、もっと高度なテクニックを知りたい！」そんなあなたのための章です！

この章では、ボストンの住宅データから住宅価格を予測するモデルを作ります。特徴量エンジニアリングという重要なテクニックを学びます！🏠

🎯 この章の学習目標

この章では、実務レベルの高度な技術を習得します：

🔧 特徴量エンジニアリング - 2 乗項・交互作用項で表現力向上
📊 データ標準化 - StandardScaler による正規化
💾 複数モデル管理 - モデル + 2 つのスケーラーを一括管理
🔄 高度な TDD - 標準化処理のテスト駆動実装

「え、難しそう...」と思いましたか？実は、これまで学んだことの応用なので、意外とできちゃいます！

Boston データセットの理解

データ詳細

data/Boston.csv を使用します。

列名	内容	データ型	特徴
RM	住居の平均部屋数	float	重要な特徴量
LSTAT	人口における低所得者の割合（%）	float	重要な特徴量
PTRATIO	教員1人当たりの児童生徒数	float	重要な特徴量
CRIME	犯罪率カテゴリ	str	ダミー変数化が必要
PRICE	住宅価格（$1000単位）	float	目的変数

Cinema との違い

特徴	Cinema	Boston
問題の種類	回帰	回帰
特徴量数	4個	3個（基本）→ 7個（エンジニアリング後）
前処理	欠損値補完 + 外れ値除外	欠損値補完 + 外れ値除外 + ダミー変数化
特徴量エンジニアリング	なし	あり（2乗項 + 交互作用項）
標準化	なし	あり（特徴量 + 目的変数）
保存モデル数	1個（model）	3個（model + scaler_X + scaler_y）
前処理の複雑度	中	高

問題の複雑性

1. 特徴量エンジニアリング

線形回帰の表現力を向上させるため、元の特徴量から新しい特徴量を生成します。

# 元の特徴量: RM, LSTAT, PTRATIO（3個）

# 特徴量エンジニアリング後:
# - 元の特徴量: RM, LSTAT, PTRATIO
# - 2乗項: RM2, LSTAT2, PTRATIO2
# - 交互作用項: RM * LSTAT
# 合計: 7個の特徴量

2. データ標準化の必要性

特徴量のスケールが異なると、モデルの学習が不安定になります。

# 標準化前:
# RM: 3〜9（平均部屋数）
# LSTAT: 1〜40（低所得者割合%）
# PTRATIO: 12〜22（生徒数）
# → スケールが大きく異なる

# 標準化後:
# すべての特徴量が平均0、標準偏差1に正規化
# → 学習が安定し、モデルの解釈が容易に

3. データリーケージの防止

訓練データとテストデータを厳密に分離し、テストデータの情報が訓練に漏れないようにします。

# ❌ 悪い例（データリーケージあり）
# 全データで欠損値補完 → 分割
# → テストデータの情報が訓練に漏れる

# ✅ 良い例（データリーケージなし）
# 分割 → 訓練データで欠損値の平均を計算 → テストデータに適用
# → テストデータの情報は使わない

TDD による実装（8ステップ）

ステップ 1: 初期化とデータ読み込み

Red: テストを書く

test/test_boston_predictor.py:

"""Boston 住宅価格予測器のテストモジュール"""
import os
import tempfile
import pytest
import pandas as pd
import numpy as np
from src.ml.boston_predictor import BostonPredictor


class TestBostonPredictorInit:
    """初期化のテスト"""

    def test_初期化_デフォルト(self):
        """デフォルトで初期化できることを確認"""
        predictor = BostonPredictor()

        assert predictor.model is None
        assert predictor.scaler_X is None
        assert predictor.scaler_y is None
        assert predictor.train_mean is None


class TestBostonPredictorLoadData:
    """データ読み込みのテスト"""

    def test_CSVファイルの読み込み(self):
        """CSV ファイルが正常に読み込めることを確認"""
        predictor = BostonPredictor()

        # テストデータ作成
        test_data = """RM,LSTAT,PTRATIO,CRIME,PRICE
6.5,5.0,15.0,low,24.0
5.5,10.0,18.0,high,18.5
7.0,3.0,14.0,low,33.2"""

        with tempfile.NamedTemporaryFile(mode='w', delete=False, suffix='.csv') as f:
            f.write(test_data)
            temp_path = f.name

        try:
            df = predictor.load_data(temp_path)

            # データが正しく読み込まれることを確認
            assert len(df) == 3
            assert 'PRICE' in df.columns
            assert 'RM' in df.columns
        finally:
            os.unlink(temp_path)

    def test_ファイルが存在しない場合エラー(self):
        """存在しないファイルパスを指定した場合 FileNotFoundError を発生"""
        predictor = BostonPredictor()

        with pytest.raises(FileNotFoundError):
            predictor.load_data('nonexistent.csv')

    def test_必要な列が不足している場合エラー(self):
        """必要な列が不足している場合 ValueError を発生"""
        predictor = BostonPredictor()

        # PRICE 列が欠けているデータ
        test_data = """RM,LSTAT,PTRATIO
6.5,5.0,15.0"""

        with tempfile.NamedTemporaryFile(mode='w', delete=False, suffix='.csv') as f:
            f.write(test_data)
            temp_path = f.name

        try:
            with pytest.raises(ValueError, match="Missing columns"):
                predictor.load_data(temp_path)
        finally:
            os.unlink(temp_path)

Green: 最小限の実装

src/ml/boston_predictor.py:

"""Boston 住宅価格予測器モジュール"""
import os
from typing import Optional, Tuple
import pandas as pd
import numpy as np
from sklearn.linear_model import LinearRegression
from sklearn.preprocessing import StandardScaler


class BostonPredictor:
    """ボストン市の住宅価格を予測する回帰モデル

    Attributes:
        model: 訓練済みの線形回帰モデル（未訓練時は None）
        scaler_X: 特徴量の標準化スケーラー（未訓練時は None）
        scaler_y: 目的変数の標準化スケーラー（未訓練時は None）
        train_mean: 訓練データの平均値（欠損値補完用）
    """

    def __init__(self) -> None:
        """初期化"""
        self.model: Optional[LinearRegression] = None
        self.scaler_X: Optional[StandardScaler] = None
        self.scaler_y: Optional[StandardScaler] = None
        self.train_mean: Optional[pd.Series] = None

    def load_data(self, file_path: str) -> pd.DataFrame:
        """CSV ファイルからデータを読み込む

        Args:
            file_path: CSV ファイルのパス

        Returns:
            読み込んだ DataFrame

        Raises:
            FileNotFoundError: ファイルが存在しない場合
            ValueError: 必要な列が不足している場合
        """
        if not os.path.exists(file_path):
            raise FileNotFoundError(f"File not found: {file_path}")

        # データの読み込み
        df = pd.read_csv(file_path)

        # 必要な列の存在確認
        required_columns = ['RM', 'LSTAT', 'PTRATIO', 'CRIME', 'PRICE']
        missing_columns = set(required_columns) - set(df.columns)
        if missing_columns:
            raise ValueError(f"Missing columns: {missing_columns}")

        return df

ステップ 2: CRIME 列のダミー変数化

カテゴリカル変数 CRIME を数値化します。

Red: テストを書く

class TestBostonPredictorEncodeCrime:
    """CRIME 列ダミー変数化のテスト"""

    def test_CRIME列がダミー変数化される(self):
        """CRIME 列がダミー変数に変換されることを確認"""
        predictor = BostonPredictor()

        df = pd.DataFrame({
            'RM': [6.5, 5.5],
            'CRIME': ['low', 'high'],
            'PRICE': [24.0, 18.5]
        })

        df_encoded = predictor._encode_crime(df)

        # CRIME 列が削除され、ダミー変数が追加されることを確認
        assert 'CRIME' not in df_encoded.columns
        # drop_first=True なので high のみ作成される
        assert 'high' in df_encoded.columns

    def test_ダミー変数の値が正しい(self):
        """ダミー変数の値が正しいことを確認"""
        predictor = BostonPredictor()

        df = pd.DataFrame({
            'CRIME': ['low', 'high', 'low', 'medium']
        })

        df_encoded = predictor._encode_crime(df)

        # drop_first=True により、low 以外のカテゴリが列として作成される
        assert 'high' in df_encoded.columns
        assert 'medium' in df_encoded.columns

    def test_他の列は保持される(self):
        """CRIME 以外の列は保持されることを確認"""
        predictor = BostonPredictor()

        df = pd.DataFrame({
            'RM': [6.5, 5.5],
            'LSTAT': [5.0, 10.0],
            'CRIME': ['low', 'high'],
            'PRICE': [24.0, 18.5]
        })

        df_encoded = predictor._encode_crime(df)

        assert 'RM' in df_encoded.columns
        assert 'LSTAT' in df_encoded.columns
        assert 'PRICE' in df_encoded.columns
        assert df_encoded['RM'].tolist() == [6.5, 5.5]

Green: 実装

def _encode_crime(self, df: pd.DataFrame) -> pd.DataFrame:
    """CRIME 列をダミー変数に変換

    Args:
        df: 元の DataFrame

    Returns:
        CRIME がダミー変数化された DataFrame

    Note:
        drop_first=True により、最初のカテゴリ（アルファベット順）を
        基準とし、それ以外のカテゴリのダミー変数を作成
    """
    df_copy = df.copy()

    # CRIME をダミー変数化（drop_first=True）
    crime_dummies = pd.get_dummies(df_copy['CRIME'], drop_first=True, dtype=int)
    df_encoded = pd.concat([df_copy.drop('CRIME', axis=1), crime_dummies], axis=1)

    return df_encoded

ステップ 3: 欠損値補完と外れ値除外

Red: テストを書く

class TestBostonPredictorPreprocess:
    """前処理のテスト"""

    def test_欠損値が平均値で補完される(self):
        """欠損値が訓練データの平均値で補完されることを確認"""
        predictor = BostonPredictor()

        df_train = pd.DataFrame({
            'RM': [6.0, 7.0, 5.0],
            'LSTAT': [5.0, 10.0, np.nan],  # 平均: 7.5
            'PRICE': [24.0, 18.5, 21.0]
        })

        df_filled = predictor._fill_missing_values(df_train, fit=True)

        # 欠損値が平均値で補完される
        assert df_filled['LSTAT'].iloc[2] == 7.5
        # train_mean が保存される
        assert predictor.train_mean is not None

    def test_テストデータは訓練データの平均で補完される(self):
        """テストデータは訓練データの平均で補完されることを確認"""
        predictor = BostonPredictor()

        df_train = pd.DataFrame({
            'RM': [6.0, 7.0, 5.0],
            'LSTAT': [5.0, 10.0, 15.0],
            'PRICE': [24.0, 18.5, 21.0]
        })

        # 訓練データで平均を計算
        predictor._fill_missing_values(df_train, fit=True)

        df_test = pd.DataFrame({
            'RM': [np.nan],
            'LSTAT': [8.0],
            'PRICE': [20.0]
        })

        # テストデータは訓練データの平均で補完
        df_test_filled = predictor._fill_missing_values(df_test, fit=False)

        # 訓練データの RM 平均は 6.0
        assert df_test_filled['RM'].iloc[0] == 6.0

    def test_外れ値が除外される(self):
        """特定のインデックスの外れ値が除外されることを確認"""
        predictor = BostonPredictor()

        # インデックス 76 を含むデータ
        df = pd.DataFrame({
            'RM': [6.0, 7.0, 5.0, 8.0],
            'PRICE': [24.0, 18.5, 21.0, 50.0]
        }, index=[0, 1, 76, 3])

        df_cleaned = predictor._remove_outliers(df)

        # インデックス 76 が除外される
        assert 76 not in df_cleaned.index
        assert len(df_cleaned) == 3

Green: 実装

def _fill_missing_values(self, df: pd.DataFrame, fit: bool = True) -> pd.DataFrame:
    """欠損値を平均値で補完

    Args:
        df: 対象の DataFrame
        fit: True の場合は平均値を計算して保存、False の場合は保存済みの平均値を使用

    Returns:
        欠損値が補完された DataFrame

    Raises:
        ValueError: fit=False の場合で train_mean が未設定の場合
    """
    if fit:
        # 訓練データの平均値を計算して保存
        self.train_mean = df.mean()
        return df.fillna(self.train_mean)
    else:
        # テストデータは訓練データの平均値で補完
        if self.train_mean is None:
            raise ValueError("train_mean not set. Call with fit=True first.")
        return df.fillna(self.train_mean)

def _remove_outliers(self, df: pd.DataFrame) -> pd.DataFrame:
    """外れ値を除外

    Args:
        df: 対象の DataFrame

    Returns:
        外れ値を除外した DataFrame

    Note:
        インデックス 76 のデータポイントを外れ値として除外
    """
    # インデックス 76 が存在する場合のみ除外
    if 76 in df.index:
        return df.drop([76], axis=0)
    return df

ステップ 4: 特徴量エンジニアリング

2乗項と交互作用項を追加してモデルの表現力を向上させます。

Red: テストを書く

class TestBostonPredictorFeatureEngineering:
    """特徴量エンジニアリングのテスト"""

    def test_2乗項が追加される(self):
        """2乗項が正しく追加されることを確認"""
        predictor = BostonPredictor()

        X = pd.DataFrame({
            'RM': [6.5],
            'LSTAT': [5.0],
            'PTRATIO': [15.0]
        })

        X_engineered = predictor.feature_engineering(X)

        # 2乗項が追加される
        assert 'RM2' in X_engineered.columns
        assert 'LSTAT2' in X_engineered.columns
        assert 'PTRATIO2' in X_engineered.columns

        # 値が正しい
        assert X_engineered['RM2'].iloc[0] == 42.25  # 6.5^2
        assert X_engineered['LSTAT2'].iloc[0] == 25.0  # 5.0^2
        assert X_engineered['PTRATIO2'].iloc[0] == 225.0  # 15.0^2

    def test_交互作用項が追加される(self):
        """交互作用項が正しく追加されることを確認"""
        predictor = BostonPredictor()

        X = pd.DataFrame({
            'RM': [6.5],
            'LSTAT': [5.0],
            'PTRATIO': [15.0]
        })

        X_engineered = predictor.feature_engineering(X)

        # 交互作用項が追加される
        assert 'RM * LSTAT' in X_engineered.columns
        assert X_engineered['RM * LSTAT'].iloc[0] == 32.5  # 6.5 * 5.0

    def test_元の特徴量は保持される(self):
        """元の特徴量が保持されることを確認"""
        predictor = BostonPredictor()

        X = pd.DataFrame({
            'RM': [6.5, 5.5],
            'LSTAT': [5.0, 10.0],
            'PTRATIO': [15.0, 18.0]
        })

        X_engineered = predictor.feature_engineering(X)

        # 元の特徴量が保持される
        assert 'RM' in X_engineered.columns
        assert 'LSTAT' in X_engineered.columns
        assert 'PTRATIO' in X_engineered.columns
        assert X_engineered['RM'].tolist() == [6.5, 5.5]

    def test_特徴量数が正しい(self):
        """特徴量数が3個から7個に増えることを確認"""
        predictor = BostonPredictor()

        X = pd.DataFrame({
            'RM': [6.5],
            'LSTAT': [5.0],
            'PTRATIO': [15.0]
        })

        X_engineered = predictor.feature_engineering(X)

        # 元の3個 + 2乗項3個 + 交互作用項1個 = 7個
        assert len(X_engineered.columns) == 7

Green: 実装

def feature_engineering(self, X: pd.DataFrame) -> pd.DataFrame:
    """特徴量エンジニアリング（2乗項と交互作用項の追加）

    Args:
        X: 元の特徴量 DataFrame

    Returns:
        エンジニアリング後の特徴量 DataFrame

    Note:
        - 2乗項: RM2, LSTAT2, PTRATIO2
        - 交互作用項: RM * LSTAT
        合計7個の特徴量を生成
    """
    X_new = X.copy()

    # 2乗項の追加
    X_new['RM2'] = X['RM'] ** 2
    X_new['LSTAT2'] = X['LSTAT'] ** 2
    X_new['PTRATIO2'] = X['PTRATIO'] ** 2

    # 交互作用項の追加
    X_new['RM * LSTAT'] = X['RM'] * X['LSTAT']

    return X_new

ステップ 5: データ標準化

特徴量と目的変数の両方を標準化します。

Red: テストを書く

class TestBostonPredictorStandardization:
    """標準化のテスト"""

    def test_特徴量の標準化_訓練データ(self):
        """訓練データの特徴量が標準化されることを確認"""
        predictor = BostonPredictor()

        X_train = pd.DataFrame({
            'RM': [5.0, 6.0, 7.0],
            'LSTAT': [10.0, 20.0, 30.0]
        })

        X_scaled = predictor.standardize_features(X_train, fit=True)

        # 標準化後、平均が0、標準偏差が1付近になることを確認
        assert abs(X_scaled.mean()) < 0.01
        assert abs(X_scaled.std() - 1.0) < 0.01

    def test_特徴量の標準化_テストデータ(self):
        """テストデータが訓練データのスケーラーで標準化されることを確認"""
        predictor = BostonPredictor()

        X_train = pd.DataFrame({
            'RM': [5.0, 6.0, 7.0]
        })

        X_test = pd.DataFrame({
            'RM': [6.0]
        })

        # 訓練データでスケーラーを fit
        predictor.standardize_features(X_train, fit=True)

        # テストデータは同じスケーラーで transform のみ
        X_test_scaled = predictor.standardize_features(X_test, fit=False)

        # スケーラーが同じであることを確認
        assert predictor.scaler_X is not None
        # テストデータの値が訓練データの統計量で変換されることを確認
        assert X_test_scaled.shape == (1, 1)

    def test_目的変数の標準化(self):
        """目的変数が標準化されることを確認"""
        predictor = BostonPredictor()

        y_train = pd.DataFrame({
            'PRICE': [20.0, 25.0, 30.0]
        })

        y_scaled = predictor.standardize_target(y_train, fit=True)

        # 標準化後、平均が0、標準偏差が1付近になることを確認
        assert abs(y_scaled.mean()) < 0.01
        assert abs(y_scaled.std() - 1.0) < 0.01

    def test_逆標準化(self):
        """予測結果が元のスケールに戻されることを確認"""
        predictor = BostonPredictor()

        y_train = pd.DataFrame({
            'PRICE': [20.0, 25.0, 30.0]
        })

        # 標準化
        y_scaled = predictor.standardize_target(y_train, fit=True)

        # 逆標準化
        y_original = predictor.inverse_transform_prediction(y_scaled)

        # 元の値に戻ることを確認
        np.testing.assert_array_almost_equal(y_original.flatten(),
                                             y_train['PRICE'].values,
                                             decimal=5)

    def test_fit前にtransformするとエラー(self):
        """fit 前に transform しようとすると ValueError を発生"""
        predictor = BostonPredictor()

        X_test = pd.DataFrame({'RM': [6.0]})

        with pytest.raises(ValueError, match="Scaler not fitted yet"):
            predictor.standardize_features(X_test, fit=False)

Green: 実装

def standardize_features(self, X: pd.DataFrame, fit: bool = True) -> np.ndarray:
    """特徴量を標準化

    Args:
        X: 特徴量 DataFrame
        fit: True の場合は fit_transform、False の場合は transform のみ

    Returns:
        標準化された特徴量（numpy 配列）

    Raises:
        ValueError: fit=False の場合で scaler_X が未設定の場合
    """
    if fit:
        self.scaler_X = StandardScaler()
        return self.scaler_X.fit_transform(X)
    else:
        if self.scaler_X is None:
            raise ValueError("Scaler not fitted yet. Call with fit=True first.")
        return self.scaler_X.transform(X)

def standardize_target(self, y: pd.DataFrame, fit: bool = True) -> np.ndarray:
    """目的変数を標準化

    Args:
        y: 目的変数 DataFrame
        fit: True の場合は fit_transform、False の場合は transform のみ

    Returns:
        標準化された目的変数（numpy 配列）

    Raises:
        ValueError: fit=False の場合で scaler_y が未設定の場合
    """
    if fit:
        self.scaler_y = StandardScaler()
        return self.scaler_y.fit_transform(y)
    else:
        if self.scaler_y is None:
            raise ValueError("Scaler not fitted yet. Call with fit=True first.")
        return self.scaler_y.transform(y)

def inverse_transform_prediction(self, y_pred: np.ndarray) -> np.ndarray:
    """予測結果を元のスケールに戻す

    Args:
        y_pred: 標準化された予測結果

    Returns:
        元のスケールに戻された予測結果

    Raises:
        RuntimeError: scaler_y が未設定の場合
    """
    if self.scaler_y is None:
        raise RuntimeError("scaler_y not set. Train the model first.")

    return self.scaler_y.inverse_transform(y_pred)

ステップ 6: モデルの訓練

def train(self, X_train: pd.DataFrame, y_train: pd.Series) -> None:
    """モデルを訓練する

    Args:
        X_train: 訓練用特徴量（標準化済み）
        y_train: 訓練用目的変数（標準化済み）
    """
    self.model = LinearRegression()
    self.model.fit(X_train, y_train)

ステップ 7: 予測と評価

def predict(self, X_test: np.ndarray) -> np.ndarray:
    """予測を実行する

    Args:
        X_test: テスト用特徴量（標準化済み）

    Returns:
        予測結果（標準化済み）

    Raises:
        RuntimeError: モデルが訓練されていない場合
    """
    if self.model is None:
        raise RuntimeError("Model has not been trained yet. Call train() first.")

    return self.model.predict(X_test)

def evaluate(self, X_test: np.ndarray, y_test: np.ndarray) -> float:
    """モデルを評価する

    Args:
        X_test: テスト用特徴量（標準化済み）
        y_test: テスト用目的変数（標準化済み）

    Returns:
        決定係数（R²）

    Raises:
        RuntimeError: モデルが訓練されていない場合
    """
    if self.model is None:
        raise RuntimeError("Model has not been trained yet. Call train() first.")

    return self.model.score(X_test, y_test)

ステップ 8: モデルとスケーラーの永続化

import pickle

def save_models(self, model_path: str, scaler_X_path: str,
                scaler_y_path: str) -> None:
    """モデルとスケーラーを保存

    Args:
        model_path: モデルの保存先パス
        scaler_X_path: 特徴量スケーラーの保存先パス
        scaler_y_path: 目的変数スケーラーの保存先パス

    Raises:
        RuntimeError: モデルまたはスケーラーが未訓練の場合
    """
    if self.model is None:
        raise RuntimeError("Model has not been trained yet.")
    if self.scaler_X is None or self.scaler_y is None:
        raise RuntimeError("Scalers have not been fitted yet.")

    with open(model_path, 'wb') as f:
        pickle.dump(self.model, f)
    with open(scaler_X_path, 'wb') as f:
        pickle.dump(self.scaler_X, f)
    with open(scaler_y_path, 'wb') as f:
        pickle.dump(self.scaler_y, f)

def load_models(self, model_path: str, scaler_X_path: str,
                scaler_y_path: str) -> None:
    """モデルとスケーラーを読み込み

    Args:
        model_path: モデルファイルのパス
        scaler_X_path: 特徴量スケーラーファイルのパス
        scaler_y_path: 目的変数スケーラーファイルのパス

    Raises:
        FileNotFoundError: ファイルが存在しない場合
    """
    for path in [model_path, scaler_X_path, scaler_y_path]:
        if not os.path.exists(path):
            raise FileNotFoundError(f"File not found: {path}")

    with open(model_path, 'rb') as f:
        self.model = pickle.load(f)
    with open(scaler_X_path, 'rb') as f:
        self.scaler_X = pickle.load(f)
    with open(scaler_y_path, 'rb') as f:
        self.scaler_y = pickle.load(f)

完全な BostonPredictor 実装

src/ml/boston_predictor.py (完全版):

"""Boston 住宅価格予測器モジュール"""
import os
import pickle
from typing import Optional
import pandas as pd
import numpy as np
from sklearn.linear_model import LinearRegression
from sklearn.preprocessing import StandardScaler


class BostonPredictor:
    """ボストン市の住宅価格を予測する回帰モデル

    Attributes:
        model: 訓練済みの線形回帰モデル（未訓練時は None）
        scaler_X: 特徴量の標準化スケーラー（未訓練時は None）
        scaler_y: 目的変数の標準化スケーラー（未訓練時は None）
        train_mean: 訓練データの平均値（欠損値補完用）

    Example:
        >>> predictor = BostonPredictor()
        >>> df = predictor.load_data('data/Boston.csv')
        >>> # データの前処理と訓練（詳細は train_boston.py 参照）
    """

    def __init__(self) -> None:
        """初期化"""
        self.model: Optional[LinearRegression] = None
        self.scaler_X: Optional[StandardScaler] = None
        self.scaler_y: Optional[StandardScaler] = None
        self.train_mean: Optional[pd.Series] = None

    def load_data(self, file_path: str) -> pd.DataFrame:
        """CSV ファイルからデータを読み込む

        Args:
            file_path: CSV ファイルのパス

        Returns:
            読み込んだ DataFrame

        Raises:
            FileNotFoundError: ファイルが存在しない場合
            ValueError: 必要な列が不足している場合
        """
        if not os.path.exists(file_path):
            raise FileNotFoundError(f"File not found: {file_path}")

        # データの読み込み
        df = pd.read_csv(file_path)

        # 必要な列の存在確認
        required_columns = ['RM', 'LSTAT', 'PTRATIO', 'CRIME', 'PRICE']
        missing_columns = set(required_columns) - set(df.columns)
        if missing_columns:
            raise ValueError(f"Missing columns: {missing_columns}")

        return df

    def _encode_crime(self, df: pd.DataFrame) -> pd.DataFrame:
        """CRIME 列をダミー変数に変換

        Args:
            df: 元の DataFrame

        Returns:
            CRIME がダミー変数化された DataFrame

        Note:
            drop_first=True により、最初のカテゴリ（アルファベット順）を
            基準とし、それ以外のカテゴリのダミー変数を作成
        """
        df_copy = df.copy()

        # CRIME をダミー変数化（drop_first=True）
        crime_dummies = pd.get_dummies(df_copy['CRIME'], drop_first=True, dtype=int)
        df_encoded = pd.concat([df_copy.drop('CRIME', axis=1), crime_dummies], axis=1)

        return df_encoded

    def _fill_missing_values(self, df: pd.DataFrame, fit: bool = True) -> pd.DataFrame:
        """欠損値を平均値で補完

        Args:
            df: 対象の DataFrame
            fit: True の場合は平均値を計算して保存、False の場合は保存済みの平均値を使用

        Returns:
            欠損値が補完された DataFrame

        Raises:
            ValueError: fit=False の場合で train_mean が未設定の場合
        """
        if fit:
            # 訓練データの平均値を計算して保存
            self.train_mean = df.mean()
            return df.fillna(self.train_mean)
        else:
            # テストデータは訓練データの平均値で補完
            if self.train_mean is None:
                raise ValueError("train_mean not set. Call with fit=True first.")
            return df.fillna(self.train_mean)

    def _remove_outliers(self, df: pd.DataFrame) -> pd.DataFrame:
        """外れ値を除外

        Args:
            df: 対象の DataFrame

        Returns:
            外れ値を除外した DataFrame

        Note:
            インデックス 76 のデータポイントを外れ値として除外
        """
        # インデックス 76 が存在する場合のみ除外
        if 76 in df.index:
            return df.drop([76], axis=0)
        return df

    def feature_engineering(self, X: pd.DataFrame) -> pd.DataFrame:
        """特徴量エンジニアリング（2乗項と交互作用項の追加）

        Args:
            X: 元の特徴量 DataFrame

        Returns:
            エンジニアリング後の特徴量 DataFrame

        Note:
            - 2乗項: RM2, LSTAT2, PTRATIO2
            - 交互作用項: RM * LSTAT
            合計7個の特徴量を生成
        """
        X_new = X.copy()

        # 2乗項の追加
        X_new['RM2'] = X['RM'] ** 2
        X_new['LSTAT2'] = X['LSTAT'] ** 2
        X_new['PTRATIO2'] = X['PTRATIO'] ** 2

        # 交互作用項の追加
        X_new['RM * LSTAT'] = X['RM'] * X['LSTAT']

        return X_new

    def standardize_features(self, X: pd.DataFrame, fit: bool = True) -> np.ndarray:
        """特徴量を標準化

        Args:
            X: 特徴量 DataFrame
            fit: True の場合は fit_transform、False の場合は transform のみ

        Returns:
            標準化された特徴量（numpy 配列）

        Raises:
            ValueError: fit=False の場合で scaler_X が未設定の場合
        """
        if fit:
            self.scaler_X = StandardScaler()
            return self.scaler_X.fit_transform(X)
        else:
            if self.scaler_X is None:
                raise ValueError("Scaler not fitted yet. Call with fit=True first.")
            return self.scaler_X.transform(X)

    def standardize_target(self, y: pd.DataFrame, fit: bool = True) -> np.ndarray:
        """目的変数を標準化

        Args:
            y: 目的変数 DataFrame
            fit: True の場合は fit_transform、False の場合は transform のみ

        Returns:
            標準化された目的変数（numpy 配列）

        Raises:
            ValueError: fit=False の場合で scaler_y が未設定の場合
        """
        if fit:
            self.scaler_y = StandardScaler()
            return self.scaler_y.fit_transform(y)
        else:
            if self.scaler_y is None:
                raise ValueError("Scaler not fitted yet. Call with fit=True first.")
            return self.scaler_y.transform(y)

    def inverse_transform_prediction(self, y_pred: np.ndarray) -> np.ndarray:
        """予測結果を元のスケールに戻す

        Args:
            y_pred: 標準化された予測結果

        Returns:
            元のスケールに戻された予測結果

        Raises:
            RuntimeError: scaler_y が未設定の場合
        """
        if self.scaler_y is None:
            raise RuntimeError("scaler_y not set. Train the model first.")

        return self.scaler_y.inverse_transform(y_pred)

    def train(self, X_train: np.ndarray, y_train: np.ndarray) -> None:
        """モデルを訓練する

        Args:
            X_train: 訓練用特徴量（標準化済み）
            y_train: 訓練用目的変数（標準化済み）
        """
        self.model = LinearRegression()
        self.model.fit(X_train, y_train)

    def predict(self, X_test: np.ndarray) -> np.ndarray:
        """予測を実行する

        Args:
            X_test: テスト用特徴量（標準化済み）

        Returns:
            予測結果（標準化済み）

        Raises:
            RuntimeError: モデルが訓練されていない場合
        """
        if self.model is None:
            raise RuntimeError("Model has not been trained yet. Call train() first.")

        return self.model.predict(X_test)

    def evaluate(self, X_test: np.ndarray, y_test: np.ndarray) -> float:
        """モデルを評価する

        Args:
            X_test: テスト用特徴量（標準化済み）
            y_test: テスト用目的変数（標準化済み）

        Returns:
            決定係数（R²）

        Raises:
            RuntimeError: モデルが訓練されていない場合
        """
        if self.model is None:
            raise RuntimeError("Model has not been trained yet. Call train() first.")

        return self.model.score(X_test, y_test)

    def save_models(self, model_path: str, scaler_X_path: str,
                    scaler_y_path: str) -> None:
        """モデルとスケーラーを保存

        Args:
            model_path: モデルの保存先パス
            scaler_X_path: 特徴量スケーラーの保存先パス
            scaler_y_path: 目的変数スケーラーの保存先パス

        Raises:
            RuntimeError: モデルまたはスケーラーが未訓練の場合
        """
        if self.model is None:
            raise RuntimeError("Model has not been trained yet.")
        if self.scaler_X is None or self.scaler_y is None:
            raise RuntimeError("Scalers have not been fitted yet.")

        with open(model_path, 'wb') as f:
            pickle.dump(self.model, f)
        with open(scaler_X_path, 'wb') as f:
            pickle.dump(self.scaler_X, f)
        with open(scaler_y_path, 'wb') as f:
            pickle.dump(self.scaler_y, f)

    def load_models(self, model_path: str, scaler_X_path: str,
                    scaler_y_path: str) -> None:
        """モデルとスケーラーを読み込み

        Args:
            model_path: モデルファイルのパス
            scaler_X_path: 特徴量スケーラーファイルのパス
            scaler_y_path: 目的変数スケーラーファイルのパス

        Raises:
            FileNotFoundError: ファイルが存在しない場合
        """
        for path in [model_path, scaler_X_path, scaler_y_path]:
            if not os.path.exists(path):
                raise FileNotFoundError(f"File not found: {path}")

        with open(model_path, 'rb') as f:
            self.model = pickle.load(f)
        with open(scaler_X_path, 'rb') as f:
            self.scaler_X = pickle.load(f)
        with open(scaler_y_path, 'rb') as f:
            self.scaler_y = pickle.load(f)

実践的な訓練スクリプト

script/train_boston.py:

"""Boston 住宅価格予測モデルの訓練スクリプト"""
from sklearn.model_selection import train_test_split
from src.ml.boston_predictor import BostonPredictor


def main():
    """メイン処理"""
    # 予測器の作成
    predictor = BostonPredictor()
    print("BostonPredictor を作成しました")

    # データの読み込み
    df = predictor.load_data('data/Boston.csv')
    print(f"データを読み込みました: {len(df)} サンプル")

    # CRIME 列のダミー変数化
    df = predictor._encode_crime(df)
    print("CRIME 列をダミー変数化しました")

    # 訓練データとテストデータに分割
    df_train, df_test = train_test_split(df, test_size=0.2, random_state=0)
    print(f"訓練データ: {len(df_train)} サンプル")
    print(f"テストデータ: {len(df_test)} サンプル")

    # 訓練データの前処理
    df_train = predictor._fill_missing_values(df_train, fit=True)
    df_train = predictor._remove_outliers(df_train)
    print(f"前処理後の訓練データ: {len(df_train)} サンプル")

    # 特徴量と目的変数の分割
    X_train = df_train[['RM', 'LSTAT', 'PTRATIO']]
    y_train = df_train[['PRICE']]

    # 特徴量エンジニアリング
    X_train = predictor.feature_engineering(X_train)
    print(f"特徴量エンジニアリング完了: {len(X_train.columns)} 個の特徴量")

    # 標準化
    X_train_scaled = predictor.standardize_features(X_train, fit=True)
    y_train_scaled = predictor.standardize_target(y_train, fit=True)
    print("訓練データの標準化が完了しました")

    # モデルの訓練
    predictor.train(X_train_scaled, y_train_scaled)
    print("モデルの訓練が完了しました")

    # テストデータの前処理
    df_test = predictor._fill_missing_values(df_test, fit=False)
    X_test = df_test[['RM', 'LSTAT', 'PTRATIO']]
    y_test = df_test[['PRICE']]

    # テストデータの特徴量エンジニアリング
    X_test = predictor.feature_engineering(X_test)

    # テストデータの標準化
    X_test_scaled = predictor.standardize_features(X_test, fit=False)
    y_test_scaled = predictor.standardize_target(y_test, fit=False)
    print("テストデータの標準化が完了しました")

    # モデルの評価
    r2_score = predictor.evaluate(X_test_scaled, y_test_scaled)
    print(f"\n[モデルの評価]")
    print(f"  決定係数（R²）: {r2_score:.4f}")

    # モデルとスケーラーの保存
    predictor.save_models(
        'model/boston.pkl',
        'model/boston_scx.pkl',
        'model/boston_scy.pkl'
    )
    print("\nモデルとスケーラーを保存しました:")
    print("  - model/boston.pkl")
    print("  - model/boston_scx.pkl")
    print("  - model/boston_scy.pkl")

    # 予測例
    print("\n[予測例]")
    sample_indices = X_test.index[:3]
    sample_X = X_test_scaled[list(sample_indices)]
    predictions_scaled = predictor.predict(sample_X)

    # 予測結果を元のスケールに戻す
    predictions = predictor.inverse_transform_prediction(predictions_scaled)

    for i, idx in enumerate(sample_indices):
        actual = y_test.loc[idx, 'PRICE']
        predicted = predictions[i][0]
        error = abs(actual - predicted)
        error_rate = (error / actual) * 100

        print(f"\nサンプル {i+1}:")
        print(f"  RM: {df_test.loc[idx, 'RM']:.2f}")
        print(f"  LSTAT: {df_test.loc[idx, 'LSTAT']:.2f}")
        print(f"  PTRATIO: {df_test.loc[idx, 'PTRATIO']:.2f}")
        print(f"  実際の価格: ${actual:.2f}k")
        print(f"  予測価格: ${predicted:.2f}k")
        print(f"  誤差: ${error:.2f}k ({error_rate:.1f}%)")


if __name__ == '__main__':
    main()

実行例：

uv run python script/train_boston.py

# 出力例：
# BostonPredictor を作成しました
# データを読み込みました: 506 サンプル
# CRIME 列をダミー変数化しました
# 訓練データ: 404 サンプル
# テストデータ: 102 サンプル
# 前処理後の訓練データ: 403 サンプル
# 特徴量エンジニアリング完了: 7 個の特徴量
# 訓練データの標準化が完了しました
# モデルの訓練が完了しました
# テストデータの標準化が完了しました
#
# [モデルの評価]
#   決定係数（R²）: 0.8313
#
# モデルとスケーラーを保存しました:
#   - model/boston.pkl
#   - model/boston_scx.pkl
#   - model/boston_scy.pkl
#
# [予測例]
#
# サンプル 1:
#   RM: 6.42
#   LSTAT: 9.32
#   PTRATIO: 18.70
#   実際の価格: $23.60k
#   予測価格: $24.15k
#   誤差: $0.55k (2.3%)
#
# サンプル 2:
#   RM: 6.00
#   LSTAT: 12.43
#   PTRATIO: 15.20
#   実際の価格: $20.10k
#   予測価格: $19.87k
#   誤差: $0.23k (1.1%)
#
# サンプル 3:
#   RM: 7.18
#   LSTAT: 4.03
#   PTRATIO: 17.40
#   実際の価格: $35.40k
#   予測価格: $34.92k
#   誤差: $0.48k (1.4%)

📓 Jupyter Notebook での探索と視覚化

高度な回帰問題では、特徴量エンジニアリングと標準化の効果を可視化することが重要です。Jupyter Notebook で詳しく分析しましょう！

🎯 この節の目的

特徴量エンジニアリングの効果を検証する - 2乗項・交互作用項の寄与
標準化の重要性を理解する - スケールの違いが与える影響
モデルの予測性能を多角的に評価する - 詳細な残差分析

📝 Notebook の作成

cd app/python/ml_tdd
uv run jupyter lab

notebook/ ディレクトリに boston_exploration.ipynb を作成しましょう。

1️⃣ 環境セットアップとデータ読み込み

# セル 1: ライブラリのインポート
import sys
sys.path.append('..')

import pandas as pd
import numpy as np
import matplotlib.pyplot as plt
import seaborn as sns
from sklearn.model_selection import train_test_split
from sklearn.metrics import mean_squared_error, r2_score, mean_absolute_error

# 日本語フォント設定
plt.rcParams['font.sans-serif'] = ['MS Gothic']
plt.rcParams['axes.unicode_minus'] = False

# スタイル設定
sns.set_style("whitegrid")
sns.set_palette("husl")

print("✅ 環境セットアップ完了")

# セル 2: データの読み込み
from src.ml.boston_predictor import BostonPredictor

predictor = BostonPredictor()
df = predictor.load_data('data/Boston.csv')

print(f"データ形状: {df.shape}")
print(f"\nデータの先頭:\n{df.head()}")
print(f"\n統計情報:\n{df.describe()}")
print(f"\n欠損値:\n{df.isnull().sum()}")

2️⃣ 元データの分布確認

# セル 3: 目的変数（価格）の分布
fig, axes = plt.subplots(1, 2, figsize=(14, 5))

# ヒストグラム
axes[0].hist(df['PRICE'], bins=30, edgecolor='black', alpha=0.7)
axes[0].set_xlabel('住宅価格 ($1000s)', fontsize=12)
axes[0].set_ylabel('頻度', fontsize=12)
axes[0].set_title('住宅価格の分布', fontsize=14)
axes[0].axvline(df['PRICE'].mean(), color='red', linestyle='--', lw=2, label=f'平均 ${df["PRICE"].mean():.2f}k')
axes[0].legend()

# 箱ひげ図
axes[1].boxplot(df['PRICE'], vert=True)
axes[1].set_ylabel('住宅価格 ($1000s)', fontsize=12)
axes[1].set_title('住宅価格の箱ひげ図', fontsize=14)
axes[1].grid(True, alpha=0.3)

plt.tight_layout()
plt.show()

print(f"価格の統計:")
print(f"  平均: ${df['PRICE'].mean():.2f}k")
print(f"  中央値: ${df['PRICE'].median():.2f}k")
print(f"  標準偏差: ${df['PRICE'].std():.2f}k")
print(f"  最小値: ${df['PRICE'].min():.2f}k")
print(f"  最大値: ${df['PRICE'].max():.2f}k")

3️⃣ 特徴量と目的変数の関係

# セル 4: 各特徴量と価格の散布図
numeric_features = ['RM', 'LSTAT', 'PTRATIO']
fig, axes = plt.subplots(1, 3, figsize=(18, 5))

for idx, feature in enumerate(numeric_features):
    ax = axes[idx]
    ax.scatter(df[feature], df['PRICE'], alpha=0.5, s=30)
    ax.set_xlabel(feature, fontsize=12)
    ax.set_ylabel('PRICE ($1000s)', fontsize=12)
    ax.set_title(f'{feature} と PRICE の関係', fontsize=13)
    ax.grid(True, alpha=0.3)

    # 相関係数
    corr = df[feature].corr(df['PRICE'])
    ax.text(0.05, 0.95, f'相関係数: {corr:.3f}',
            transform=ax.transAxes, fontsize=11,
            verticalalignment='top',
            bbox=dict(boxstyle='round', facecolor='wheat', alpha=0.5))

plt.tight_layout()
plt.show()

print("相関係数:")
print(df[numeric_features + ['PRICE']].corr()['PRICE'].sort_values(ascending=False))

相関から分かること：

RM（部屋数）は正の相関 → 部屋が多いほど価格が高い
LSTAT（低所得者率）は負の相関 → 貧困率が高いと価格が低い
PTRATIO（生徒教師比）は負の相関 → 教育環境が良いと価格が高い

4️⃣ 前処理とデータ分割

# セル 5: データ前処理
# CRIME のダミー変数化
df_encoded = predictor._encode_crime(df)
print(f"エンコーディング後の列: {list(df_encoded.columns)}")

# 訓練データとテストデータに分割
train_df, test_df = train_test_split(df_encoded, test_size=0.2, random_state=42)

# 欠損値補完
train_df = predictor._fill_missing_values(train_df, fit=True)
test_df = predictor._fill_missing_values(test_df, fit=False)

# 特徴量と目的変数の分離
X_train = train_df[['RM', 'LSTAT', 'PTRATIO']]
y_train = train_df[['PRICE']]
X_test = test_df[['RM', 'LSTAT', 'PTRATIO']]
y_test = test_df[['PRICE']]

print(f"\n訓練データ: X={X_train.shape}, y={y_train.shape}")
print(f"テストデータ: X={X_test.shape}, y={y_test.shape}")

5️⃣ 特徴量エンジニアリングの効果

# セル 6: 特徴量エンジニアリング前後の比較
X_train_fe = predictor.feature_engineering(X_train.copy())
print(f"元の特徴量数: {X_train.shape[1]}")
print(f"エンジニアリング後: {X_train_fe.shape[1]}")
print(f"\n追加された特徴量:")
new_features = set(X_train_fe.columns) - set(X_train.columns)
for feat in sorted(new_features):
    print(f"  - {feat}")

# 新しい特徴量と価格の相関
print("\n新特徴量と価格の相関:")
for feat in sorted(new_features):
    corr = X_train_fe[feat].corr(y_train['PRICE'])
    print(f"  {feat:20s}: {corr:6.3f}")

特徴量エンジニアリングで何が増えた？

2乗項: 非線形な関係を捉える（例: 部屋数の効果は線形ではない）
交互作用項: 複数の特徴の組み合わせ効果（例: 部屋数×貧困率）

6️⃣ 標準化の重要性

# セル 7: 標準化前後のスケール比較
X_train_fe_copy = X_train_fe.copy()
X_train_scaled = predictor.standardize_features(X_train_fe_copy, fit=True)

fig, axes = plt.subplots(1, 2, figsize=(14, 6))

# 標準化前
axes[0].boxplot([X_train_fe[col] for col in X_train_fe.columns[:5]],
                labels=X_train_fe.columns[:5])
axes[0].set_title('標準化前のスケール', fontsize=14)
axes[0].set_ylabel('値', fontsize=12)
axes[0].tick_params(axis='x', rotation=45)
axes[0].grid(True, alpha=0.3)

# 標準化後
axes[1].boxplot([X_train_scaled[:, i] for i in range(5)],
                labels=X_train_fe.columns[:5])
axes[1].set_title('標準化後のスケール', fontsize=14)
axes[1].set_ylabel('標準化された値', fontsize=12)
axes[1].tick_params(axis='x', rotation=45)
axes[1].grid(True, alpha=0.3)

plt.tight_layout()
plt.show()

print("標準化の効果:")
print("  平均 ≈ 0、標準偏差 ≈ 1 に正規化されました")

7️⃣ モデルの訓練と評価

# セル 8: モデルの訓練と予測
y_train_scaled = predictor.standardize_target(y_train, fit=True)
y_test_scaled = predictor.standardize_target(y_test, fit=False)

X_test_fe = predictor.feature_engineering(X_test.copy())
X_test_scaled = predictor.standardize_features(X_test_fe, fit=False)

# 訓練
predictor.train(X_train_scaled, y_train_scaled)

# 予測
y_pred_train_scaled = predictor.predict(X_train_scaled)
y_pred_test_scaled = predictor.predict(X_test_scaled)

# 元のスケールに戻す
y_pred_train = predictor.inverse_transform_prediction(y_pred_train_scaled)
y_pred_test = predictor.inverse_transform_prediction(y_pred_test_scaled)

# 評価
r2_train = r2_score(y_train, y_pred_train)
r2_test = r2_score(y_test, y_pred_test)
mae_test = mean_absolute_error(y_test, y_pred_test)
rmse_test = np.sqrt(mean_squared_error(y_test, y_pred_test))

print(f"訓練データ R²: {r2_train:.4f}")
print(f"テストデータ R²: {r2_test:.4f}")
print(f"テストデータ MAE: ${mae_test:.2f}k")
print(f"テストデータ RMSE: ${rmse_test:.2f}k")

8️⃣ 予測値 vs 実測値

# セル 9: 予測値 vs 実測値の散布図
fig, (ax1, ax2) = plt.subplots(1, 2, figsize=(14, 6))

# 訓練データ
ax1.scatter(y_train, y_pred_train, alpha=0.5, s=30)
ax1.plot([y_train.min(), y_train.max()],
         [y_train.min(), y_train.max()],
         'r--', lw=2, label='理想的な予測')
ax1.set_xlabel('実測値 ($1000s)', fontsize=12)
ax1.set_ylabel('予測値 ($1000s)', fontsize=12)
ax1.set_title(f'訓練データ (R²={r2_train:.3f})', fontsize=14)
ax1.legend()
ax1.grid(True, alpha=0.3)

# テストデータ
ax2.scatter(y_test, y_pred_test, alpha=0.5, s=30, color='green')
ax2.plot([y_test.min(), y_test.max()],
         [y_test.min(), y_test.max()],
         'r--', lw=2, label='理想的な予測')
ax2.set_xlabel('実測値 ($1000s)', fontsize=12)
ax2.set_ylabel('予測値 ($1000s)', fontsize=12)
ax2.set_title(f'テストデータ (R²={r2_test:.3f})', fontsize=14)
ax2.legend()
ax2.grid(True, alpha=0.3)

plt.tight_layout()
plt.show()

9️⃣ 残差分析

# セル 10: 残差プロット
residuals_test = y_test.values.flatten() - y_pred_test.flatten()

fig, axes = plt.subplots(2, 2, figsize=(14, 10))

# 残差 vs 予測値
axes[0, 0].scatter(y_pred_test, residuals_test, alpha=0.5)
axes[0, 0].axhline(y=0, color='r', linestyle='--', lw=2)
axes[0, 0].set_xlabel('予測値 ($1000s)')
axes[0, 0].set_ylabel('残差 ($1000s)')
axes[0, 0].set_title('残差プロット')
axes[0, 0].grid(True, alpha=0.3)

# 残差のヒストグラム
axes[0, 1].hist(residuals_test, bins=30, edgecolor='black', alpha=0.7)
axes[0, 1].axvline(x=0, color='r', linestyle='--', lw=2)
axes[0, 1].set_xlabel('残差 ($1000s)')
axes[0, 1].set_ylabel('頻度')
axes[0, 1].set_title('残差の分布')
axes[0, 1].grid(True, alpha=0.3)

# Q-Qプロット（正規性の確認）
from scipy import stats
stats.probplot(residuals_test, dist="norm", plot=axes[1, 0])
axes[1, 0].set_title('Q-Q プロット（正規性検証）')
axes[1, 0].grid(True, alpha=0.3)

# 残差の絶対値 vs 予測値
axes[1, 1].scatter(y_pred_test, np.abs(residuals_test), alpha=0.5)
axes[1, 1].set_xlabel('予測値 ($1000s)')
axes[1, 1].set_ylabel('残差の絶対値 ($1000s)')
axes[1, 1].set_title('予測値と誤差の大きさの関係')
axes[1, 1].grid(True, alpha=0.3)

plt.tight_layout()
plt.show()

print(f"残差の統計:")
print(f"  平均: ${residuals_test.mean():.2f}k")
print(f"  標準偏差: ${residuals_test.std():.2f}k")
print(f"  最大誤差: ${np.abs(residuals_test).max():.2f}k")

🔟 回帰係数の分析

# セル 11: 回帰係数の可視化
coefficients = predictor.model.coef_[0]
feature_names = X_train_fe.columns

coef_df = pd.DataFrame({
    'feature': feature_names,
    'coefficient': coefficients
}).sort_values('coefficient', key=abs, ascending=False)

plt.figure(figsize=(10, 8))
colors = ['red' if c < 0 else 'blue' for c in coef_df['coefficient']]
plt.barh(range(len(coef_df)), coef_df['coefficient'], color=colors)
plt.yticks(range(len(coef_df)), coef_df['feature'])
plt.xlabel('係数の値', fontsize=12)
plt.ylabel('特徴量', fontsize=12)
plt.title('線形回帰の係数（標準化後）', fontsize=14)
plt.axvline(x=0, color='black', linestyle='--', lw=1)
plt.grid(True, alpha=0.3, axis='x')
plt.tight_layout()
plt.show()

print("\n係数の絶対値トップ5:")
print(coef_df.head())

係数から分かること：

正の係数 = 価格を上昇させる要因
負の係数 = 価格を下降させる要因
絶対値が大きい = 影響力が強い

1️⃣1️⃣ 特徴量エンジニアリングの効果比較

# セル 12: エンジニアリングあり/なしの性能比較
from sklearn.linear_model import LinearRegression

# エンジニアリングなしのモデル
model_no_fe = LinearRegression()
X_train_no_fe = predictor.standardize_features(X_train.copy(), fit=True)
model_no_fe.fit(X_train_no_fe, y_train_scaled)

X_test_no_fe = predictor.standardize_features(X_test.copy(), fit=False)
y_pred_no_fe = model_no_fe.predict(X_test_no_fe)
y_pred_no_fe_original = predictor.inverse_transform_prediction(y_pred_no_fe)

r2_no_fe = r2_score(y_test, y_pred_no_fe_original)

# 比較
comparison = pd.DataFrame({
    '指標': ['R²スコア', '特徴量数'],
    'エンジニアリングなし': [f'{r2_no_fe:.4f}', X_train.shape[1]],
    'エンジニアリングあり': [f'{r2_test:.4f}', X_train_fe.shape[1]]
})

print(comparison.to_string(index=False))
print(f"\n性能向上: {(r2_test - r2_no_fe) / r2_no_fe * 100:.1f}%")

💡 高度な回帰問題での Notebook 活用ポイント

✅ やること	❌ 避けること
特徴量エンジニアリングの効果を定量化	闇雲に特徴量を増やす
標準化前後のスケールを確認	標準化の必要性を無視
残差の正規性を Q-Q プロットで検証	残差の分布を見ない
回帰係数から特徴量の寄与を解釈	係数の意味を考えない

🔄 探索から本番コードへ

# 発見 1: 2乗項と交互作用項で性能が向上
# ↓ テストに反映
def test_特徴量エンジニアリングの効果(self):
    """特徴量エンジニアリングが性能向上に寄与することを確認"""
    # エンジニアリングなし vs ありで R² を比較
    assert r2_with_fe > r2_without_fe

# 発見 2: 標準化により係数の解釈が容易に
# ↓ ドキュメントに反映
# 「標準化された係数は特徴量の相対的重要度を示す」と記載

# 発見 3: LSTAT の2乗項が特に重要
# ↓ 本番コードに反映
# feature_engineering で LSTAT^2 を必ず含める

📊 ７章の技術的成果

「高度な回帰問題もマスターしました！」お疲れさまでした！７章で何を達成したか、振り返ってみましょう。

✅ 完成した機能

７章では、以下の機能を実装しました：

✅ Boston 予測器クラスの完全実装 - 住宅価格を予測するモデル
✅ CRIME 列のダミー変数化 - カテゴリカル変数の処理
✅ データリーケージ防止の前処理パイプライン - 正しい前処理手順
✅ 特徴量エンジニアリング - 2 乗項 + 交互作用項で表現力向上
✅ StandardScaler による標準化 - データの正規化
✅ 複数モデルの一括管理 - model + 2 つの scaler
✅ 逆標準化による予測結果の復元 - 元のスケールに戻す

📈 定量的成果

数字で見ると、こんなに達成しました！

指標	🎯 実績
🧪 テストケース	25 個
📊 コードカバレッジ	94%（boston_predictor.py）
🔤 型ヒント使用率	100%
🏠 モデル決定係数（R²）	0.8313（テストデータ）
⚙️ 特徴量数	3 個 → 7 個（エンジニアリング後）
💾 保存モデル数	3 個（model、scaler_X、scaler_y）
✨ Ruff チェック	全て通過
✅ mypy チェック	エラー 0 件
🔧 循環的複雑度	最大 4（全関数）

特徴量が 3 個から 7 個に！ 特徴量エンジニアリングでモデルの表現力が大幅に向上しました！🎉

🎓 習得したスキル

1. 🔄 TDD スキル（最上級）

✅ 標準化処理のテスト駆動実装
fit と transform の分離テスト
複数モデルの永続化テスト

2. 特徴量エンジニアリングスキル

2乗項による非線形性の表現
交互作用項による特徴量間の関係表現
特徴量数の最適化

3. データ標準化スキル

StandardScaler の使い方
訓練データとテストデータの分離
逆標準化による予測結果の復元

4. 高度なデータ処理スキル

データリーケージの防止
訓練データの統計量によるテストデータ処理
複数ステップの前処理パイプライン

5. モデル管理スキル

複数モデルの一括保存と読み込み
スケーラーの永続化
訓練時の統計量の保存

特徴量エンジニアリングの理解

なぜ特徴量エンジニアリングが必要か:

# 元の線形モデル:
# PRICE = β₀ + β₁×RM + β₂×LSTAT + β₃×PTRATIO

# 問題: 線形関係しか表現できない
# → 実際の住宅価格は非線形な関係を持つ

# 特徴量エンジニアリング後:
# PRICE = β₀ + β₁×RM + β₂×RM² + β₃×LSTAT + β₄×LSTAT² +
#         β₅×PTRATIO + β₆×PTRATIO² + β₇×(RM × LSTAT)

# 利点:
# - RM² により「部屋数が多いほど価格が急上昇」を表現
# - RM × LSTAT により「部屋数と低所得者割合の相互作用」を表現
# → より複雑な関係を線形モデルで表現可能

2乗項の効果:

# 例: RM（部屋数）と価格の関係

# 線形項のみ: PRICE = 10×RM
# RM=5: PRICE = 50
# RM=6: PRICE = 60 (+10)
# RM=7: PRICE = 70 (+10)
# → 部屋数が1増えると一定額（10k）増加

# 2乗項追加: PRICE = 10×RM + 2×RM²
# RM=5: PRICE = 50 + 50 = 100
# RM=6: PRICE = 60 + 72 = 132 (+32)
# RM=7: PRICE = 70 + 98 = 168 (+36)
# → 部屋数が多いほど価格の上昇幅が大きい（現実的）

交互作用項の効果:

# RM（部屋数）と LSTAT（低所得者割合）の交互作用

# 交互作用項なし:
# → RM と LSTAT が独立に価格に影響

# 交互作用項あり: RM × LSTAT
# → 「高級住宅地（LSTAT低）では部屋数の影響が大きい」
# → 「低所得地区（LSTAT高）では部屋数の影響が小さい」
# → より現実的な関係を表現

データ標準化の理解

なぜ標準化が必要か:

# 標準化前の特徴量:
# RM: 3〜9（範囲: 6）
# LSTAT: 1〜40（範囲: 39）
# PTRATIO: 12〜22（範囲: 10）

# 問題:
# 1. 学習が不安定になる（勾配降下法が収束しにくい）
# 2. LSTAT の影響が過大評価される（スケールが大きいため）
# 3. 係数の解釈が困難（単位が異なる）

# 標準化後:
# すべての特徴量が平均0、標準偏差1
# → 公平な比較が可能
# → 学習が安定

標準化の数式:

z = (x - μ) / σ

where:
  z: 標準化後の値
  x: 元の値
  μ: 平均値
  σ: 標準偏差

例:
RM の平均が6.0、標準偏差が1.0の場合
RM = 7.0 → z = (7.0 - 6.0) / 1.0 = 1.0
RM = 5.0 → z = (5.0 - 6.0) / 1.0 = -1.0

目的変数の標準化:

# 目的変数（PRICE）も標準化する理由:

# 1. 学習の安定性向上
#    → 特徴量と目的変数のスケールが近い方が学習しやすい

# 2. 数値計算の精度向上
#    → オーバーフローやアンダーフローを防ぐ

# 3. 逆標準化で元のスケールに戻す
#    → 予測結果は元の単位（$1000）で解釈

データリーケージ防止の理解

データリーケージとは:

# ❌ 悪い例（データリーケージあり）

# 1. 全データで欠損値補完
df_all = df_all.fillna(df_all.mean())  # 全データの平均を使用

# 2. データ分割
df_train, df_test = train_test_split(df_all)

# 問題: テストデータの情報（平均値の計算）が訓練に漏れている
# → テストデータの性能が過大評価される

# ✅ 良い例（データリーケージなし）

# 1. データ分割
df_train, df_test = train_test_split(df)

# 2. 訓練データで統計量を計算
train_mean = df_train.mean()

# 3. 訓練データとテストデータを別々に補完
df_train = df_train.fillna(train_mean)  # 訓練データの平均を使用
df_test = df_test.fillna(train_mean)    # 訓練データの平均を使用（重要）

# 利点: テストデータの情報は一切使わない
# → 本番環境での性能を正確に評価できる

標準化でのデータリーケージ防止:

# ❌ 悪い例
scaler = StandardScaler()
X_all_scaled = scaler.fit_transform(X_all)  # 全データで fit
X_train, X_test = train_test_split(X_all_scaled)

# ✅ 良い例
X_train, X_test = train_test_split(X)

scaler = StandardScaler()
X_train_scaled = scaler.fit_transform(X_train)  # 訓練データで fit
X_test_scaled = scaler.transform(X_test)        # テストデータは transform のみ

# 重要: テストデータは訓練データの平均・標準偏差で変換
# → 本番環境を正確にシミュレート

回帰モデルの比較（Cinema vs Boston）

項目	Cinema（基礎）	Boston（高度）
モデル	LinearRegression	LinearRegression
特徴量数	4個	7個（3個→エンジニアリング）
前処理	欠損値補完 + 外れ値除外	欠損値補完 + 外れ値除外 + ダミー変数化
特徴量エンジニアリング	なし	2乗項 + 交互作用項
標準化	なし	StandardScaler（特徴量 + 目的変数）
データリーケージ防止	部分的	完全
保存モデル数	1個	3個（model + 2 scalers）
決定係数	0.8383	0.8313
テスト数	20個	25個

決定係数が若干低い理由:

Cinema: シンプルなデータセット、明確な特徴量（SNS指標）
Boston: 複雑な社会経済要因、多様な外部変数の影響

🚀 次の章への準備

７章では、高度な回帰問題に取り組みました！次の８章では、いよいよ最終章です：

🌐 FastAPI による API 化 - モデルを Web API として公開
🏗️ レイヤードアーキテクチャの実装 - Application / Service / Domain の 3 層構造
🤖 4 つのモデルの統合エンドポイント - すべてのモデルを 1 つの API に
✅ Pydantic による入力検証 - 型安全なデータ検証
📚 Swagger UI による自動ドキュメント生成 - API ドキュメントが自動で完成

いよいよ最終章！これまで作ったモデルを、実際に使える Web API にします！ワクワクしますね！🎉

８章機械学習 API の構築（FastAPI で本番デプロイ）

「モデルができたけど、どうやって使ってもらうの？」良い質問です！この章では、作った機械学習モデルを Web API として公開します！

FastAPI を使って、誰でも簡単に使える API を作ります。いよいよ最終章です！🚀

🎯 この章の学習目標

これまで作ってきた 4 つの機械学習モデル（Iris 分類、Cinema 回帰、Survived 分類、Boston 回帰）を、実際に使える Web API として公開します！

この章では、以下のスキルを習得します：

🌐 FastAPI による Web API 開発 - モダンな Python Web フレームワーク
✅ Pydantic によるデータ検証 - リクエストデータの型安全性確保
🏗️ レイヤードアーキテクチャの実践 - Application/Service/Domain の 3 層構造
📚 OpenAPI 仕様の自動生成 - Swagger UI で自動的にドキュメント作成
💾 機械学習モデルの本番運用 - pickle でモデルを保存・読み込み

💡 なぜ API 化が重要なのか？

「モデルができたら終わりじゃないの？」いいえ！実は、モデルを実際に使える形にすることが最も重要です。

API 化すると、こんなことができます：

🌍 アクセス可能性 - Web API として公開し、世界中から利用可能に
✅ データ検証 - 不正な入力を受け付けないバリデーション
📖 ドキュメント - 利用方法を明確に示す自動生成ドキュメント
🔧 保守性 - レイヤー分離で変更が簡単に

「難しそう...」と思いましたか？FastAPI なら、驚くほど簡単に API が作れますよ！

FastAPI プロジェクト構造

ml-api-project/
├── app/
│   ├── __init__.py
│   ├── application.py      # アプリケーション層（エンドポイント定義）
│   ├── service.py          # サービス層（ビジネスロジック）
│   ├── domain.py           # ドメイン層（モデル処理）
│   └── models.py           # Pydantic モデル定義
├── test/
│   ├── __init__.py
│   ├── test_application.py # API エンドポイントのテスト
│   ├── test_service.py     # サービス層のテスト
│   └── test_domain.py      # ドメイン層のテスト
├── model/
│   ├── iris.pkl            # 訓練済み Iris モデル
│   ├── cinema.pkl          # 訓練済み Cinema モデル
│   ├── survived.pkl        # 訓練済み Survived モデル
│   └── boston.pkl          # 訓練済み Boston モデル
└── pyproject.toml

レイヤードアーキテクチャの概念

各層の責務：

層	責務	技術要素
Application 層	HTTP リクエスト/レスポンス処理	FastAPI、Pydantic
Service 層	ビジネスロジック、データ変換	Python ロジック
Domain 層	モデル操作、機械学習処理	scikit-learn、pickle

TDD による実装

ステップ 1: Pydantic モデルの定義（Red → Green → Refactor）

まず、各 API エンドポイントで受け取るデータの型を定義します。

Red（失敗するテスト）:

# test/test_models.py
import pytest
from app.models import IrisModel, CinemaModel, SurvivedModel, BostonModel

def test_IrisModelの正常な値():
    """正しい値でIrisModelを作成できる"""
    model = IrisModel(
        sepal_length=5.1,
        sepal_width=3.5,
        petal_length=1.4,
        petal_width=0.2
    )

    assert model.sepal_length == 5.1
    assert model.sepal_width == 3.5
    assert model.petal_length == 1.4
    assert model.petal_width == 0.2

def test_IrisModelの負の値でエラー():
    """負の値を指定するとバリデーションエラー"""
    with pytest.raises(ValueError):
        IrisModel(
            sepal_length=-1.0,
            sepal_width=3.5,
            petal_length=1.4,
            petal_width=0.2
        )

def test_CinemaModelの正常な値():
    """正しい値でCinemaModelを作成できる"""
    model = CinemaModel(
        sns1=500,
        sns2=300,
        actor=70,
        original=1
    )

    assert model.sns1 == 500
    assert model.sns2 == 300
    assert model.actor == 70
    assert model.original == 1

def test_SurvivedModelの正常な値():
    """正しい値でSurvivedModelを作成できる"""
    model = SurvivedModel(
        pclass=3,
        age=22,
        sex="male"
    )

    assert model.pclass == 3
    assert model.age == 22
    assert model.sex == "male"

def test_SurvivedModelの不正なsexでエラー():
    """sex が male/female 以外でエラー"""
    with pytest.raises(ValueError):
        SurvivedModel(pclass=1, age=30, sex="unknown")

def test_BostonModelの正常な値():
    """正しい値でBostonModelを作成できる"""
    model = BostonModel(
        rm=6.5,
        lstat=4.98,
        ptratio=15.3
    )

    assert model.rm == 6.5
    assert model.lstat == 4.98
    assert model.ptratio == 15.3

実行結果（Red）:

$ pytest test/test_models.py
ModuleNotFoundError: No module named 'app.models'

Green（最小限の実装）:

# app/models.py
from pydantic import BaseModel, Field, field_validator
from typing import Literal

class IrisModel(BaseModel):
    """Iris 分類のリクエストモデル"""
    sepal_length: float = Field(..., ge=0, description="がく片の長さ (cm)")
    sepal_width: float = Field(..., ge=0, description="がく片の幅 (cm)")
    petal_length: float = Field(..., ge=0, description="花弁の長さ (cm)")
    petal_width: float = Field(..., ge=0, description="花弁の幅 (cm)")

class CinemaModel(BaseModel):
    """Cinema 売上予測のリクエストモデル"""
    sns1: int = Field(..., ge=0, description="SNS 言及数 1")
    sns2: int = Field(..., ge=0, description="SNS 言及数 2")
    actor: int = Field(..., ge=0, le=100, description="主演俳優スコア (0-100)")
    original: int = Field(..., ge=0, le=1, description="オリジナル作品フラグ (0 or 1)")

class SurvivedModel(BaseModel):
    """Survived 生存予測のリクエストモデル"""
    pclass: int = Field(..., ge=1, le=3, description="客室クラス (1, 2, 3)")
    age: int = Field(..., ge=0, le=100, description="年齢")
    sex: Literal["male", "female"] = Field(..., description="性別 (male or female)")

class BostonModel(BaseModel):
    """Boston 住宅価格予測のリクエストモデル"""
    rm: float = Field(..., gt=0, description="部屋数")
    lstat: float = Field(..., ge=0, le=100, description="低所得者人口割合 (%)")
    ptratio: float = Field(..., gt=0, description="生徒と教師の比率")

実行結果（Green）:

$ pytest test/test_models.py -v
test_models.py::test_IrisModelの正常な値 PASSED                        [ 16%]
test_models.py::test_IrisModelの負の値でエラー PASSED                   [ 33%]
test_models.py::test_CinemaModelの正常な値 PASSED                      [ 50%]
test_models.py::test_SurvivedModelの正常な値 PASSED                    [ 66%]
test_models.py::test_SurvivedModelの不正なsexでエラー PASSED           [ 83%]
test_models.py::test_BostonModelの正常な値 PASSED                      [100%]

============================== 6 passed in 0.12s ==============================

Refactor（改善）:

現時点では特にリファクタリングは不要です。Pydantic の Field と Literal を使用してバリデーションを宣言的に記述できています。

ステップ 2: ドメイン層の実装（Red → Green → Refactor）

次に、訓練済みモデルを読み込んで予測を行うドメイン層を実装します。

Red（失敗するテスト）:

# test/test_domain.py
import pytest
import pickle
import numpy as np
import pandas as pd
from sklearn import tree
from sklearn.linear_model import LinearRegression
from app.domain import IrisDomain, CinemaDomain, SurvivedDomain, BostonDomain

def test_IrisDomainでモデルを読み込める():
    """訓練済みIrisモデルを読み込める"""
    domain = IrisDomain()
    assert domain.model is not None

def test_IrisDomainで予測ができる():
    """Irisモデルで予測を実行できる"""
    domain = IrisDomain()
    X = [[5.1, 3.5, 1.4, 0.2]]
    result = domain.predict(X)

    assert len(result) == 1
    assert result[0] in ["setosa", "versicolor", "virginica"]

def test_CinemaDomainでモデルを読み込める():
    """訓練済みCinemaモデルを読み込める"""
    domain = CinemaDomain()
    assert domain.model is not None

def test_CinemaDomainで予測ができる():
    """Cinemaモデルで予測を実行できる"""
    domain = CinemaDomain()
    X = [[500, 300, 70, 1]]
    result = domain.predict(X)

    assert len(result) == 1
    assert isinstance(result[0], (int, float))
    assert result[0] > 0

def test_SurvivedDomainでモデルを読み込める():
    """訓練済みSurvivedモデルを読み込める"""
    domain = SurvivedDomain()
    assert domain.model is not None

def test_SurvivedDomainで予測ができる():
    """Survivedモデルで予測を実行できる"""
    domain = SurvivedDomain()
    X_dict = [{"Pclass": 3, "Age": 22, "male": 1}]
    result = domain.predict(X_dict)

    assert len(result) == 1
    assert result[0] in [0, 1]

def test_BostonDomainでモデルを読み込める():
    """訓練済みBostonモデルを読み込める"""
    domain = BostonDomain()
    assert domain.model is not None
    assert domain.scaler_X is not None
    assert domain.scaler_y is not None

def test_BostonDomainで予測ができる():
    """Bostonモデルで予測を実行できる"""
    domain = BostonDomain()
    X_dict = [{"RM": 6.5, "LSTAT": 4.98, "PTRATIO": 15.3}]
    result = domain.predict(X_dict)

    assert len(result) == 1
    assert isinstance(result[0], (int, float))
    assert result[0] > 0

実行結果（Red）:

$ pytest test/test_domain.py
ModuleNotFoundError: No module named 'app.domain'

Green（最小限の実装）:

# app/domain.py
import pickle
import numpy as np
import pandas as pd
from typing import List, Union, Dict
from pathlib import Path

class IrisDomain:
    """Iris 分類ドメイン"""

    def __init__(self, model_path: str = "model/iris.pkl") -> None:
        self.model_path = model_path
        self.model = None
        self.load_model()

    def load_model(self) -> None:
        """訓練済みモデルの読み込み"""
        with open(self.model_path, 'rb') as f:
            self.model = pickle.load(f)

    def predict(self, X: List[List[float]]) -> List[str]:
        """予測を実行

        Args:
            X: 特徴量のリスト [[sepal_length, sepal_width, petal_length, petal_width]]

        Returns:
            予測結果（種名）のリスト
        """
        if self.model is None:
            raise ValueError("Model not loaded")

        predictions = self.model.predict(X)
        return predictions.tolist()

class CinemaDomain:
    """Cinema 売上予測ドメイン"""

    def __init__(self, model_path: str = "model/cinema.pkl") -> None:
        self.model_path = model_path
        self.model = None
        self.load_model()

    def load_model(self) -> None:
        """訓練済みモデルの読み込み"""
        with open(self.model_path, 'rb') as f:
            self.model = pickle.load(f)

    def predict(self, X: List[List[Union[int, float]]]) -> List[float]:
        """予測を実行

        Args:
            X: 特徴量のリスト [[sns1, sns2, actor, original]]

        Returns:
            予測結果（売上）のリスト
        """
        if self.model is None:
            raise ValueError("Model not loaded")

        predictions = self.model.predict(X)
        return predictions.tolist()

class SurvivedDomain:
    """Survived 生存予測ドメイン"""

    def __init__(self, model_path: str = "model/survived.pkl") -> None:
        self.model_path = model_path
        self.model = None
        self.load_model()

    def load_model(self) -> None:
        """訓練済みモデルの読み込み"""
        with open(self.model_path, 'rb') as f:
            self.model = pickle.load(f)

    def predict(self, X_dict: List[Dict[str, Union[int, float]]]) -> List[int]:
        """予測を実行

        Args:
            X_dict: 特徴量の辞書のリスト [{"Pclass": 3, "Age": 22, "male": 1}]

        Returns:
            予測結果（0: 死亡, 1: 生存）のリスト
        """
        if self.model is None:
            raise ValueError("Model not loaded")

        # 辞書をDataFrameに変換
        X = pd.DataFrame(X_dict)
        predictions = self.model.predict(X)
        return predictions.tolist()

class BostonDomain:
    """Boston 住宅価格予測ドメイン"""

    def __init__(self, model_path: str = "model/boston.pkl") -> None:
        self.model_path = model_path
        self.model = None
        self.scaler_X = None
        self.scaler_y = None
        self.load_model()

    def load_model(self) -> None:
        """訓練済みモデルとスケーラーの読み込み"""
        with open(self.model_path, 'rb') as f:
            saved_data = pickle.load(f)
            self.model = saved_data['model']
            self.scaler_X = saved_data['scaler_X']
            self.scaler_y = saved_data['scaler_y']

    def predict(self, X_dict: List[Dict[str, float]]) -> List[float]:
        """予測を実行

        Args:
            X_dict: 特徴量の辞書のリスト [{"RM": 6.5, "LSTAT": 4.98, "PTRATIO": 15.3}]

        Returns:
            予測結果（住宅価格）のリスト
        """
        if self.model is None or self.scaler_X is None or self.scaler_y is None:
            raise ValueError("Model or scalers not loaded")

        # 辞書をDataFrameに変換
        X = pd.DataFrame(X_dict)

        # 特徴量エンジニアリング（訓練時と同じ処理）
        X_engineered = self._feature_engineering(X)

        # 特徴量の標準化
        X_scaled = self.scaler_X.transform(X_engineered)

        # 予測（標準化された値）
        y_pred_scaled = self.model.predict(X_scaled)

        # 予測結果を元のスケールに戻す
        y_pred = self.scaler_y.inverse_transform(y_pred_scaled.reshape(-1, 1))

        return y_pred.flatten().tolist()

    def _feature_engineering(self, X: pd.DataFrame) -> pd.DataFrame:
        """特徴量エンジニアリング（2乗項と交互作用項の追加）"""
        X_new = X.copy()

        # 2乗項の追加
        X_new['RM2'] = X['RM'] ** 2
        X_new['LSTAT2'] = X['LSTAT'] ** 2
        X_new['PTRATIO2'] = X['PTRATIO'] ** 2

        # 交互作用項の追加
        X_new['RM * LSTAT'] = X['RM'] * X['LSTAT']

        return X_new

実行結果（Green）:

$ pytest test/test_domain.py -v
test_domain.py::test_IrisDomainでモデルを読み込める PASSED              [ 12%]
test_domain.py::test_IrisDomainで予測ができる PASSED                    [ 25%]
test_domain.py::test_CinemaDomainでモデルを読み込める PASSED            [ 37%]
test_domain.py::test_CinemaDomainで予測ができる PASSED                  [ 50%]
test_domain.py::test_SurvivedDomainでモデルを読み込める PASSED          [ 62%]
test_domain.py::test_SurvivedDomainで予測ができる PASSED                [ 75%]
test_domain.py::test_BostonDomainでモデルを読み込める PASSED            [ 87%]
test_domain.py::test_BostonDomainで予測ができる PASSED                  [100%]

============================== 8 passed in 0.45s ==============================

Refactor（改善）:

モデル読み込みのエラーハンドリングを追加します：

# app/domain.py (リファクタリング後)
class IrisDomain:
    """Iris 分類ドメイン"""

    def __init__(self, model_path: str = "model/iris.pkl") -> None:
        self.model_path = model_path
        self.model = None
        self.load_model()

    def load_model(self) -> None:
        """訓練済みモデルの読み込み"""
        try:
            with open(self.model_path, 'rb') as f:
                self.model = pickle.load(f)
        except FileNotFoundError:
            raise FileNotFoundError(f"Model file not found: {self.model_path}")
        except Exception as e:
            raise RuntimeError(f"Failed to load model: {e}")

    # 以下略（他のドメインクラスも同様にエラーハンドリングを追加）

ステップ 3: サービス層の実装（Red → Green → Refactor）

サービス層では、ドメイン層を使用してビジネスロジックを実装します。

Red（失敗するテスト）:

# test/test_service.py
import pytest
from app.service import MLService

def test_predict_iris():
    """Iris予測サービスが正しく動作する"""
    service = MLService()
    result = service.predict_iris([[5.1, 3.5, 1.4, 0.2]])

    assert isinstance(result, str)
    assert result in ["setosa", "versicolor", "virginica"]

def test_predict_cinema():
    """Cinema予測サービスが正しく動作する"""
    service = MLService()
    result = service.predict_cinema([[500, 300, 70, 1]])

    assert isinstance(result, float)
    assert result > 0

def test_predict_survived():
    """Survived予測サービスが正しく動作する"""
    service = MLService()
    result = service.predict_survived(pclass=3, age=22, sex="male")

    assert isinstance(result, int)
    assert result in [0, 1]

def test_predict_boston():
    """Boston予測サービスが正しく動作する"""
    service = MLService()
    result = service.predict_boston(rm=6.5, lstat=4.98, ptratio=15.3)

    assert isinstance(result, float)
    assert result > 0

実行結果（Red）:

$ pytest test/test_service.py
ModuleNotFoundError: No module named 'app.service'

Green（最小限の実装）:

# app/service.py
from typing import List, Union
from app.domain import IrisDomain, CinemaDomain, SurvivedDomain, BostonDomain

class MLService:
    """機械学習サービス層"""

    def __init__(self) -> None:
        # ドメインオブジェクトは毎回生成（シングルトンにしても良い）
        pass

    def predict_iris(self, features: List[List[float]]) -> str:
        """Iris 分類予測

        Args:
            features: [[sepal_length, sepal_width, petal_length, petal_width]]

        Returns:
            予測された種名
        """
        domain = IrisDomain()
        predictions = domain.predict(features)
        return predictions[0]  # 最初の予測結果を返す

    def predict_cinema(self, features: List[List[Union[int, float]]]) -> float:
        """Cinema 売上予測

        Args:
            features: [[sns1, sns2, actor, original]]

        Returns:
            予測された売上
        """
        domain = CinemaDomain()
        predictions = domain.predict(features)
        return float(predictions[0])

    def predict_survived(self, pclass: int, age: int, sex: str) -> int:
        """Survived 生存予測

        Args:
            pclass: 客室クラス
            age: 年齢
            sex: 性別

        Returns:
            予測結果（0: 死亡, 1: 生存）
        """
        domain = SurvivedDomain()

        # sex を male ダミー変数に変換
        male = 1 if sex == "male" else 0

        X_dict = [{"Pclass": pclass, "Age": age, "male": male}]
        predictions = domain.predict(X_dict)
        return int(predictions[0])

    def predict_boston(self, rm: float, lstat: float, ptratio: float) -> float:
        """Boston 住宅価格予測

        Args:
            rm: 部屋数
            lstat: 低所得者人口割合
            ptratio: 生徒と教師の比率

        Returns:
            予測された住宅価格
        """
        domain = BostonDomain()

        X_dict = [{"RM": rm, "LSTAT": lstat, "PTRATIO": ptratio}]
        predictions = domain.predict(X_dict)
        return float(predictions[0])

実行結果（Green）:

$ pytest test/test_service.py -v
test_service.py::test_predict_iris PASSED                               [ 25%]
test_service.py::test_predict_cinema PASSED                             [ 50%]
test_service.py::test_predict_survived PASSED                           [ 75%]
test_service.py::test_predict_boston PASSED                             [100%]

============================== 4 passed in 0.56s ==============================

Refactor（改善）:

ドメインオブジェクトをシングルトンパターンで再利用するように改善します：

# app/service.py (リファクタリング後)
from typing import List, Union, Optional
from app.domain import IrisDomain, CinemaDomain, SurvivedDomain, BostonDomain

class MLService:
    """機械学習サービス層"""

    def __init__(self) -> None:
        # 初回アクセス時にモデルを読み込み、以降は再利用
        self._iris_domain: Optional[IrisDomain] = None
        self._cinema_domain: Optional[CinemaDomain] = None
        self._survived_domain: Optional[SurvivedDomain] = None
        self._boston_domain: Optional[BostonDomain] = None

    @property
    def iris_domain(self) -> IrisDomain:
        """Lazy loading で IrisDomain を取得"""
        if self._iris_domain is None:
            self._iris_domain = IrisDomain()
        return self._iris_domain

    @property
    def cinema_domain(self) -> CinemaDomain:
        """Lazy loading で CinemaDomain を取得"""
        if self._cinema_domain is None:
            self._cinema_domain = CinemaDomain()
        return self._cinema_domain

    @property
    def survived_domain(self) -> SurvivedDomain:
        """Lazy loading で SurvivedDomain を取得"""
        if self._survived_domain is None:
            self._survived_domain = SurvivedDomain()
        return self._survived_domain

    @property
    def boston_domain(self) -> BostonDomain:
        """Lazy loading で BostonDomain を取得"""
        if self._boston_domain is None:
            self._boston_domain = BostonDomain()
        return self._boston_domain

    def predict_iris(self, features: List[List[float]]) -> str:
        """Iris 分類予測"""
        predictions = self.iris_domain.predict(features)
        return predictions[0]

    def predict_cinema(self, features: List[List[Union[int, float]]]) -> float:
        """Cinema 売上予測"""
        predictions = self.cinema_domain.predict(features)
        return float(predictions[0])

    def predict_survived(self, pclass: int, age: int, sex: str) -> int:
        """Survived 生存予測"""
        male = 1 if sex == "male" else 0
        X_dict = [{"Pclass": pclass, "Age": age, "male": male}]
        predictions = self.survived_domain.predict(X_dict)
        return int(predictions[0])

    def predict_boston(self, rm: float, lstat: float, ptratio: float) -> float:
        """Boston 住宅価格予測"""
        X_dict = [{"RM": rm, "LSTAT": lstat, "PTRATIO": ptratio}]
        predictions = self.boston_domain.predict(X_dict)
        return float(predictions[0])

ステップ 4: アプリケーション層の実装（Red → Green → Refactor）

最後に、FastAPI のエンドポイントを実装します。

Red（失敗するテスト）:

# test/test_application.py
import pytest
from fastapi.testclient import TestClient
from app.application import app

client = TestClient(app)

def test_Irisエンドポイントの正常系():
    """Iris エンドポイントが正しく動作する"""
    response = client.post("/iris", json={
        "sepal_length": 5.1,
        "sepal_width": 3.5,
        "petal_length": 1.4,
        "petal_width": 0.2
    })

    assert response.status_code == 200
    data = response.json()
    assert "species" in data
    assert data["species"] in ["setosa", "versicolor", "virginica"]

def test_Irisエンドポイントの異常系_負の値():
    """負の値を指定するとバリデーションエラー"""
    response = client.post("/iris", json={
        "sepal_length": -1.0,
        "sepal_width": 3.5,
        "petal_length": 1.4,
        "petal_width": 0.2
    })

    assert response.status_code == 422  # Validation error

def test_Cinemaエンドポイントの正常系():
    """Cinema エンドポイントが正しく動作する"""
    response = client.post("/cinema", json={
        "sns1": 500,
        "sns2": 300,
        "actor": 70,
        "original": 1
    })

    assert response.status_code == 200
    data = response.json()
    assert "predicted_sales" in data
    assert data["predicted_sales"] > 0

def test_Survivedエンドポイントの正常系():
    """Survived エンドポイントが正しく動作する"""
    response = client.post("/survived", json={
        "pclass": 3,
        "age": 22,
        "sex": "male"
    })

    assert response.status_code == 200
    data = response.json()
    assert "survived" in data
    assert data["survived"] in [0, 1]

def test_Bostonエンドポイントの正常系():
    """Boston エンドポイントが正しく動作する"""
    response = client.post("/boston", json={
        "rm": 6.5,
        "lstat": 4.98,
        "ptratio": 15.3
    })

    assert response.status_code == 200
    data = response.json()
    assert "predicted_price" in data
    assert data["predicted_price"] > 0

def test_ルートエンドポイント():
    """ルートエンドポイントが正しく動作する"""
    response = client.get("/")

    assert response.status_code == 200
    data = response.json()
    assert "message" in data

def test_ヘルスチェックエンドポイント():
    """ヘルスチェックエンドポイントが正しく動作する"""
    response = client.get("/health")

    assert response.status_code == 200
    data = response.json()
    assert data["status"] == "ok"

実行結果（Red）:

$ pytest test/test_application.py
ModuleNotFoundError: No module named 'app.application'

Green（最小限の実装）:

# app/application.py
from fastapi import FastAPI
from app.models import IrisModel, CinemaModel, SurvivedModel, BostonModel
from app.service import MLService

app = FastAPI(
    title="Machine Learning API",
    description="TDD で構築した機械学習モデルの API",
    version="1.0.0"
)

service = MLService()

@app.get("/", tags=["Root"])
async def root():
    """ルートエンドポイント"""
    return {
        "message": "Machine Learning API",
        "version": "1.0.0",
        "endpoints": ["/iris", "/cinema", "/survived", "/boston"]
    }

@app.get("/health", tags=["Health"])
async def health():
    """ヘルスチェックエンドポイント"""
    return {"status": "ok"}

@app.post("/iris", tags=["Iris"], description="アヤメの種類を分類")
async def predict_iris(model: IrisModel):
    """Iris 分類エンドポイント

    Args:
        model: Iris の特徴量

    Returns:
        予測された種名
    """
    features = [[
        model.sepal_length,
        model.sepal_width,
        model.petal_length,
        model.petal_width
    ]]

    species = service.predict_iris(features)
    return {"species": species}

@app.post("/cinema", tags=["Cinema"], description="映画の興行収入を予測")
async def predict_cinema(model: CinemaModel):
    """Cinema 売上予測エンドポイント

    Args:
        model: Cinema の特徴量

    Returns:
        予測された売上
    """
    features = [[
        model.sns1,
        model.sns2,
        model.actor,
        model.original
    ]]

    predicted_sales = service.predict_cinema(features)
    return {"predicted_sales": predicted_sales}

@app.post("/survived", tags=["Survived"], description="タイタニック号での生存を予測")
async def predict_survived(model: SurvivedModel):
    """Survived 生存予測エンドポイント

    Args:
        model: Survived の特徴量

    Returns:
        予測結果（0: 死亡, 1: 生存）
    """
    survived = service.predict_survived(
        pclass=model.pclass,
        age=model.age,
        sex=model.sex
    )
    return {"survived": survived}

@app.post("/boston", tags=["Boston"], description="ボストン住宅価格を予測")
async def predict_boston(model: BostonModel):
    """Boston 住宅価格予測エンドポイント

    Args:
        model: Boston の特徴量

    Returns:
        予測された住宅価格
    """
    predicted_price = service.predict_boston(
        rm=model.rm,
        lstat=model.lstat,
        ptratio=model.ptratio
    )
    return {"predicted_price": predicted_price}

実行結果（Green）:

$ pytest test/test_application.py -v
test_application.py::test_Irisエンドポイントの正常系 PASSED             [ 14%]
test_application.py::test_Irisエンドポイントの異常系_負の値 PASSED       [ 28%]
test_application.py::test_Cinemaエンドポイントの正常系 PASSED           [ 42%]
test_application.py::test_Survivedエンドポイントの正常系 PASSED         [ 57%]
test_application.py::test_Bostonエンドポイントの正常系 PASSED           [ 71%]
test_application.py::test_ルートエンドポイント PASSED                   [ 85%]
test_application.py::test_ヘルスチェックエンドポイント PASSED           [100%]

============================== 7 passed in 0.78s ==============================

Refactor（改善）:

エラーハンドリングとレスポンスモデルを追加します：

# app/application.py (リファクタリング後)
from fastapi import FastAPI, HTTPException
from fastapi.responses import JSONResponse
from pydantic import BaseModel
from app.models import IrisModel, CinemaModel, SurvivedModel, BostonModel
from app.service import MLService

app = FastAPI(
    title="Machine Learning API",
    description="TDD で構築した機械学習モデルの API",
    version="1.0.0"
)

service = MLService()

# レスポンスモデルの定義
class IrisResponse(BaseModel):
    species: str

class CinemaResponse(BaseModel):
    predicted_sales: float

class SurvivedResponse(BaseModel):
    survived: int

class BostonResponse(BaseModel):
    predicted_price: float

@app.get("/", tags=["Root"])
async def root():
    """ルートエンドポイント"""
    return {
        "message": "Machine Learning API",
        "version": "1.0.0",
        "endpoints": ["/iris", "/cinema", "/survived", "/boston"]
    }

@app.get("/health", tags=["Health"])
async def health():
    """ヘルスチェックエンドポイント"""
    return {"status": "ok"}

@app.post("/iris", response_model=IrisResponse, tags=["Iris"])
async def predict_iris(model: IrisModel):
    """Iris 分類エンドポイント"""
    try:
        features = [[
            model.sepal_length,
            model.sepal_width,
            model.petal_length,
            model.petal_width
        ]]

        species = service.predict_iris(features)
        return IrisResponse(species=species)
    except Exception as e:
        raise HTTPException(status_code=500, detail=str(e))

@app.post("/cinema", response_model=CinemaResponse, tags=["Cinema"])
async def predict_cinema(model: CinemaModel):
    """Cinema 売上予測エンドポイント"""
    try:
        features = [[
            model.sns1,
            model.sns2,
            model.actor,
            model.original
        ]]

        predicted_sales = service.predict_cinema(features)
        return CinemaResponse(predicted_sales=predicted_sales)
    except Exception as e:
        raise HTTPException(status_code=500, detail=str(e))

@app.post("/survived", response_model=SurvivedResponse, tags=["Survived"])
async def predict_survived(model: SurvivedModel):
    """Survived 生存予測エンドポイント"""
    try:
        survived = service.predict_survived(
            pclass=model.pclass,
            age=model.age,
            sex=model.sex
        )
        return SurvivedResponse(survived=survived)
    except Exception as e:
        raise HTTPException(status_code=500, detail=str(e))

@app.post("/boston", response_model=BostonResponse, tags=["Boston"])
async def predict_boston(model: BostonModel):
    """Boston 住宅価格予測エンドポイント"""
    try:
        predicted_price = service.predict_boston(
            rm=model.rm,
            lstat=model.lstat,
            ptratio=model.ptratio
        )
        return BostonResponse(predicted_price=predicted_price)
    except Exception as e:
        raise HTTPException(status_code=500, detail=str(e))

完全なコード実装

これまでのステップで実装した全コードを整理します。

app/models.py（完全版）

"""Pydantic モデル定義"""
from pydantic import BaseModel, Field
from typing import Literal

class IrisModel(BaseModel):
    """Iris 分類のリクエストモデル"""
    sepal_length: float = Field(..., ge=0, description="がく片の長さ (cm)")
    sepal_width: float = Field(..., ge=0, description="がく片の幅 (cm)")
    petal_length: float = Field(..., ge=0, description="花弁の長さ (cm)")
    petal_width: float = Field(..., ge=0, description="花弁の幅 (cm)")

    model_config = {
        "json_schema_extra": {
            "examples": [
                {
                    "sepal_length": 5.1,
                    "sepal_width": 3.5,
                    "petal_length": 1.4,
                    "petal_width": 0.2
                }
            ]
        }
    }

class CinemaModel(BaseModel):
    """Cinema 売上予測のリクエストモデル"""
    sns1: int = Field(..., ge=0, description="SNS 言及数 1")
    sns2: int = Field(..., ge=0, description="SNS 言及数 2")
    actor: int = Field(..., ge=0, le=100, description="主演俳優スコア (0-100)")
    original: int = Field(..., ge=0, le=1, description="オリジナル作品フラグ (0 or 1)")

    model_config = {
        "json_schema_extra": {
            "examples": [
                {
                    "sns1": 500,
                    "sns2": 300,
                    "actor": 70,
                    "original": 1
                }
            ]
        }
    }

class SurvivedModel(BaseModel):
    """Survived 生存予測のリクエストモデル"""
    pclass: int = Field(..., ge=1, le=3, description="客室クラス (1, 2, 3)")
    age: int = Field(..., ge=0, le=100, description="年齢")
    sex: Literal["male", "female"] = Field(..., description="性別 (male or female)")

    model_config = {
        "json_schema_extra": {
            "examples": [
                {
                    "pclass": 3,
                    "age": 22,
                    "sex": "male"
                }
            ]
        }
    }

class BostonModel(BaseModel):
    """Boston 住宅価格予測のリクエストモデル"""
    rm: float = Field(..., gt=0, description="部屋数")
    lstat: float = Field(..., ge=0, le=100, description="低所得者人口割合 (%)")
    ptratio: float = Field(..., gt=0, description="生徒と教師の比率")

    model_config = {
        "json_schema_extra": {
            "examples": [
                {
                    "rm": 6.5,
                    "lstat": 4.98,
                    "ptratio": 15.3
                }
            ]
        }
    }

app/domain.py（完全版）

"""ドメイン層：機械学習モデルの読み込みと予測"""
import pickle
import numpy as np
import pandas as pd
from typing import List, Union, Dict, Optional
from pathlib import Path

class IrisDomain:
    """Iris 分類ドメイン"""

    def __init__(self, model_path: str = "model/iris.pkl") -> None:
        self.model_path = model_path
        self.model = None
        self.load_model()

    def load_model(self) -> None:
        """訓練済みモデルの読み込み"""
        try:
            with open(self.model_path, 'rb') as f:
                self.model = pickle.load(f)
        except FileNotFoundError:
            raise FileNotFoundError(f"Model file not found: {self.model_path}")
        except Exception as e:
            raise RuntimeError(f"Failed to load model: {e}")

    def predict(self, X: List[List[float]]) -> List[str]:
        """予測を実行

        Args:
            X: 特徴量のリスト [[sepal_length, sepal_width, petal_length, petal_width]]

        Returns:
            予測結果（種名）のリスト
        """
        if self.model is None:
            raise ValueError("Model not loaded")

        predictions = self.model.predict(X)
        return predictions.tolist()

class CinemaDomain:
    """Cinema 売上予測ドメイン"""

    def __init__(self, model_path: str = "model/cinema.pkl") -> None:
        self.model_path = model_path
        self.model = None
        self.load_model()

    def load_model(self) -> None:
        """訓練済みモデルの読み込み"""
        try:
            with open(self.model_path, 'rb') as f:
                self.model = pickle.load(f)
        except FileNotFoundError:
            raise FileNotFoundError(f"Model file not found: {self.model_path}")
        except Exception as e:
            raise RuntimeError(f"Failed to load model: {e}")

    def predict(self, X: List[List[Union[int, float]]]) -> List[float]:
        """予測を実行

        Args:
            X: 特徴量のリスト [[sns1, sns2, actor, original]]

        Returns:
            予測結果（売上）のリスト
        """
        if self.model is None:
            raise ValueError("Model not loaded")

        predictions = self.model.predict(X)
        return predictions.tolist()

class SurvivedDomain:
    """Survived 生存予測ドメイン"""

    def __init__(self, model_path: str = "model/survived.pkl") -> None:
        self.model_path = model_path
        self.model = None
        self.load_model()

    def load_model(self) -> None:
        """訓練済みモデルの読み込み"""
        try:
            with open(self.model_path, 'rb') as f:
                self.model = pickle.load(f)
        except FileNotFoundError:
            raise FileNotFoundError(f"Model file not found: {self.model_path}")
        except Exception as e:
            raise RuntimeError(f"Failed to load model: {e}")

    def predict(self, X_dict: List[Dict[str, Union[int, float]]]) -> List[int]:
        """予測を実行

        Args:
            X_dict: 特徴量の辞書のリスト [{"Pclass": 3, "Age": 22, "male": 1}]

        Returns:
            予測結果（0: 死亡, 1: 生存）のリスト
        """
        if self.model is None:
            raise ValueError("Model not loaded")

        # 辞書をDataFrameに変換
        X = pd.DataFrame(X_dict)
        predictions = self.model.predict(X)
        return predictions.tolist()

class BostonDomain:
    """Boston 住宅価格予測ドメイン"""

    def __init__(self, model_path: str = "model/boston.pkl") -> None:
        self.model_path = model_path
        self.model = None
        self.scaler_X = None
        self.scaler_y = None
        self.load_model()

    def load_model(self) -> None:
        """訓練済みモデルとスケーラーの読み込み"""
        try:
            with open(self.model_path, 'rb') as f:
                saved_data = pickle.load(f)
                self.model = saved_data['model']
                self.scaler_X = saved_data['scaler_X']
                self.scaler_y = saved_data['scaler_y']
        except FileNotFoundError:
            raise FileNotFoundError(f"Model file not found: {self.model_path}")
        except Exception as e:
            raise RuntimeError(f"Failed to load model: {e}")

    def predict(self, X_dict: List[Dict[str, float]]) -> List[float]:
        """予測を実行

        Args:
            X_dict: 特徴量の辞書のリスト [{"RM": 6.5, "LSTAT": 4.98, "PTRATIO": 15.3}]

        Returns:
            予測結果（住宅価格）のリスト
        """
        if self.model is None or self.scaler_X is None or self.scaler_y is None:
            raise ValueError("Model or scalers not loaded")

        # 辞書をDataFrameに変換
        X = pd.DataFrame(X_dict)

        # 特徴量エンジニアリング（訓練時と同じ処理）
        X_engineered = self._feature_engineering(X)

        # 特徴量の標準化
        X_scaled = self.scaler_X.transform(X_engineered)

        # 予測（標準化された値）
        y_pred_scaled = self.model.predict(X_scaled)

        # 予測結果を元のスケールに戻す
        y_pred = self.scaler_y.inverse_transform(y_pred_scaled.reshape(-1, 1))

        return y_pred.flatten().tolist()

    def _feature_engineering(self, X: pd.DataFrame) -> pd.DataFrame:
        """特徴量エンジニアリング（2乗項と交互作用項の追加）"""
        X_new = X.copy()

        # 2乗項の追加
        X_new['RM2'] = X['RM'] ** 2
        X_new['LSTAT2'] = X['LSTAT'] ** 2
        X_new['PTRATIO2'] = X['PTRATIO'] ** 2

        # 交互作用項の追加
        X_new['RM * LSTAT'] = X['RM'] * X['LSTAT']

        return X_new

app/service.py（完全版）

"""サービス層：ビジネスロジック"""
from typing import List, Union, Optional
from app.domain import IrisDomain, CinemaDomain, SurvivedDomain, BostonDomain

class MLService:
    """機械学習サービス層"""

    def __init__(self) -> None:
        # 初回アクセス時にモデルを読み込み、以降は再利用（Lazy Loading）
        self._iris_domain: Optional[IrisDomain] = None
        self._cinema_domain: Optional[CinemaDomain] = None
        self._survived_domain: Optional[SurvivedDomain] = None
        self._boston_domain: Optional[BostonDomain] = None

    @property
    def iris_domain(self) -> IrisDomain:
        """Lazy loading で IrisDomain を取得"""
        if self._iris_domain is None:
            self._iris_domain = IrisDomain()
        return self._iris_domain

    @property
    def cinema_domain(self) -> CinemaDomain:
        """Lazy loading で CinemaDomain を取得"""
        if self._cinema_domain is None:
            self._cinema_domain = CinemaDomain()
        return self._cinema_domain

    @property
    def survived_domain(self) -> SurvivedDomain:
        """Lazy loading で SurvivedDomain を取得"""
        if self._survived_domain is None:
            self._survived_domain = SurvivedDomain()
        return self._survived_domain

    @property
    def boston_domain(self) -> BostonDomain:
        """Lazy loading で BostonDomain を取得"""
        if self._boston_domain is None:
            self._boston_domain = BostonDomain()
        return self._boston_domain

    def predict_iris(self, features: List[List[float]]) -> str:
        """Iris 分類予測

        Args:
            features: [[sepal_length, sepal_width, petal_length, petal_width]]

        Returns:
            予測された種名
        """
        predictions = self.iris_domain.predict(features)
        return predictions[0]

    def predict_cinema(self, features: List[List[Union[int, float]]]) -> float:
        """Cinema 売上予測

        Args:
            features: [[sns1, sns2, actor, original]]

        Returns:
            予測された売上
        """
        predictions = self.cinema_domain.predict(features)
        return float(predictions[0])

    def predict_survived(self, pclass: int, age: int, sex: str) -> int:
        """Survived 生存予測

        Args:
            pclass: 客室クラス
            age: 年齢
            sex: 性別

        Returns:
            予測結果（0: 死亡, 1: 生存）
        """
        # sex を male ダミー変数に変換
        male = 1 if sex == "male" else 0

        X_dict = [{"Pclass": pclass, "Age": age, "male": male}]
        predictions = self.survived_domain.predict(X_dict)
        return int(predictions[0])

    def predict_boston(self, rm: float, lstat: float, ptratio: float) -> float:
        """Boston 住宅価格予測

        Args:
            rm: 部屋数
            lstat: 低所得者人口割合
            ptratio: 生徒と教師の比率

        Returns:
            予測された住宅価格
        """
        X_dict = [{"RM": rm, "LSTAT": lstat, "PTRATIO": ptratio}]
        predictions = self.boston_domain.predict(X_dict)
        return float(predictions[0])

app/application.py（完全版）

"""アプリケーション層：FastAPI エンドポイント"""
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from app.models import IrisModel, CinemaModel, SurvivedModel, BostonModel
from app.service import MLService

app = FastAPI(
    title="Machine Learning API",
    description="TDD で構築した機械学習モデルの API",
    version="1.0.0"
)

service = MLService()

# レスポンスモデルの定義
class IrisResponse(BaseModel):
    """Iris 予測レスポンス"""
    species: str

class CinemaResponse(BaseModel):
    """Cinema 予測レスポンス"""
    predicted_sales: float

class SurvivedResponse(BaseModel):
    """Survived 予測レスポンス"""
    survived: int

class BostonResponse(BaseModel):
    """Boston 予測レスポンス"""
    predicted_price: float

@app.get("/", tags=["Root"])
async def root():
    """ルートエンドポイント"""
    return {
        "message": "Machine Learning API",
        "version": "1.0.0",
        "endpoints": ["/iris", "/cinema", "/survived", "/boston"],
        "docs": "/docs"
    }

@app.get("/health", tags=["Health"])
async def health():
    """ヘルスチェックエンドポイント"""
    return {"status": "ok"}

@app.post("/iris", response_model=IrisResponse, tags=["Iris"], description="アヤメの種類を分類")
async def predict_iris(model: IrisModel):
    """Iris 分類エンドポイント

    Args:
        model: Iris の特徴量

    Returns:
        予測された種名
    """
    try:
        features = [[
            model.sepal_length,
            model.sepal_width,
            model.petal_length,
            model.petal_width
        ]]

        species = service.predict_iris(features)
        return IrisResponse(species=species)
    except Exception as e:
        raise HTTPException(status_code=500, detail=str(e))

@app.post("/cinema", response_model=CinemaResponse, tags=["Cinema"], description="映画の興行収入を予測")
async def predict_cinema(model: CinemaModel):
    """Cinema 売上予測エンドポイント

    Args:
        model: Cinema の特徴量

    Returns:
        予測された売上
    """
    try:
        features = [[
            model.sns1,
            model.sns2,
            model.actor,
            model.original
        ]]

        predicted_sales = service.predict_cinema(features)
        return CinemaResponse(predicted_sales=predicted_sales)
    except Exception as e:
        raise HTTPException(status_code=500, detail=str(e))

@app.post("/survived", response_model=SurvivedResponse, tags=["Survived"], description="タイタニック号での生存を予測")
async def predict_survived(model: SurvivedModel):
    """Survived 生存予測エンドポイント

    Args:
        model: Survived の特徴量

    Returns:
        予測結果（0: 死亡, 1: 生存）
    """
    try:
        survived = service.predict_survived(
            pclass=model.pclass,
            age=model.age,
            sex=model.sex
        )
        return SurvivedResponse(survived=survived)
    except Exception as e:
        raise HTTPException(status_code=500, detail=str(e))

@app.post("/boston", response_model=BostonResponse, tags=["Boston"], description="ボストン住宅価格を予測")
async def predict_boston(model: BostonModel):
    """Boston 住宅価格予測エンドポイント

    Args:
        model: Boston の特徴量

    Returns:
        予測された住宅価格
    """
    try:
        predicted_price = service.predict_boston(
            rm=model.rm,
            lstat=model.lstat,
            ptratio=model.ptratio
        )
        return BostonResponse(predicted_price=predicted_price)
    except Exception as e:
        raise HTTPException(status_code=500, detail=str(e))

統合テスト

これまでは各層（models, domain, service, application）を個別にテストしてきました。ここでは、API 全体が正しく動作することを確認する 統合テスト を実装します。

統合テストとは

統合テストは、複数のコンポーネントを組み合わせて、システム全体が期待通りに動作するかを検証するテストです。

単体テストとの違い:

テストの種類	対象	目的
単体テスト	個別の関数やクラス	各部品が正しく動作するか確認
統合テスト	複数のコンポーネント	コンポーネント間の連携が正しいか確認

FastAPI における統合テスト:

HTTP リクエスト/レスポンスの検証
エンドポイント全体のフロー確認
エラーハンドリングの検証
実際のユースケースに近いシナリオテスト

TestClient の使い方

FastAPI は統合テストのために TestClient を提供しています。これを使うと、実際のサーバーを起動せずに API をテストできます。

from fastapi.testclient import TestClient
from api.application import app

client = TestClient(app)

# GET リクエストのテスト
response = client.get("/")
assert response.status_code == 200

# POST リクエストのテスト
response = client.post(
    "/iris",
    json={
        "sepal_length": 5.1,
        "sepal_width": 3.5,
        "petal_length": 1.4,
        "petal_width": 0.2
    }
)
assert response.status_code == 200
assert "species" in response.json()

pytest フィクスチャによる共通設定

pytest の @pytest.fixture を使って、テストで使用する共通オブジェクトを定義します。

test/conftest.py を作成:

"""pytest の共通設定とフィクスチャ."""
import pytest
from fastapi.testclient import TestClient
from api.application import app


@pytest.fixture
def client():
    """TestClient フィクスチャ.

    各テストで FastAPI アプリケーションのテストクライアントを提供します。
    """
    return TestClient(app)


@pytest.fixture
def iris_sample_data():
    """Iris テスト用サンプルデータ."""
    return {
        "sepal_length": 5.1,
        "sepal_width": 3.5,
        "petal_length": 1.4,
        "petal_width": 0.2
    }


@pytest.fixture
def cinema_sample_data():
    """Cinema テスト用サンプルデータ."""
    return {
        "sns1": 500,
        "sns2": 300,
        "actor": 70,
        "original": 1
    }


@pytest.fixture
def survived_sample_data():
    """Survived テスト用サンプルデータ."""
    return {
        "pclass": 1,
        "age": 30,
        "sex": "female"
    }


@pytest.fixture
def boston_sample_data():
    """Boston テスト用サンプルデータ."""
    return {
        "rm": 6.5,
        "lstat": 4.98,
        "ptratio": 15.3
    }

統合テストの実装

test/test_integration.py を作成:

"""API 統合テスト."""
import pytest


class TestAPIIntegration:
    """API 全体の統合テスト."""

    def test_ルートエンドポイントが正しく動作する(self, client) -> None:
        """ルートエンドポイントが API 情報を返す."""
        response = client.get("/")

        assert response.status_code == 200
        data = response.json()
        assert data["message"] == "Machine Learning API"
        assert data["version"] == "1.0.0"
        assert "/iris" in data["endpoints"]
        assert "/cinema" in data["endpoints"]
        assert "/survived" in data["endpoints"]
        assert "/boston" in data["endpoints"]

    def test_ヘルスチェックが正しく動作する(self, client) -> None:
        """ヘルスチェックエンドポイントが正常ステータスを返す."""
        response = client.get("/health")

        assert response.status_code == 200
        assert response.json() == {"status": "ok"}

    def test_Iris予測のエンドツーエンドフロー(
        self, client, iris_sample_data
    ) -> None:
        """Iris 予測の完全なフローが正しく動作する."""
        response = client.post("/iris", json=iris_sample_data)

        assert response.status_code == 200
        data = response.json()
        assert "species" in data
        assert data["species"] in ["setosa", "versicolor", "virginica"]

    def test_Iris予測で不正なデータを拒否する(self, client) -> None:
        """不正なリクエストデータでエラーを返す."""
        # 負の値を送信
        invalid_data = {
            "sepal_length": -1.0,
            "sepal_width": 3.5,
            "petal_length": 1.4,
            "petal_width": 0.2
        }
        response = client.post("/iris", json=invalid_data)

        assert response.status_code == 422  # Validation Error

    def test_Cinema予測のエンドツーエンドフロー(
        self, client, cinema_sample_data
    ) -> None:
        """Cinema 予測の完全なフローが正しく動作する."""
        response = client.post("/cinema", json=cinema_sample_data)

        assert response.status_code == 200
        data = response.json()
        assert "predicted_sales" in data
        assert isinstance(data["predicted_sales"], (int, float))
        assert data["predicted_sales"] > 0

    def test_Cinema予測でactor範囲外を拒否する(self, client) -> None:
        """actor スコアが範囲外の場合エラーを返す."""
        invalid_data = {
            "sns1": 500,
            "sns2": 300,
            "actor": 150,  # 100 を超える
            "original": 1
        }
        response = client.post("/cinema", json=invalid_data)

        assert response.status_code == 422  # Validation Error

    def test_Survived予測のエンドツーエンドフロー(
        self, client, survived_sample_data
    ) -> None:
        """Survived 予測の完全なフローが正しく動作する."""
        response = client.post("/survived", json=survived_sample_data)

        assert response.status_code == 200
        data = response.json()
        assert "survived" in data
        assert data["survived"] in [0, 1]

    def test_Survived予測で不正なsexを拒否する(self, client) -> None:
        """sex が male/female 以外の場合エラーを返す."""
        invalid_data = {
            "pclass": 1,
            "age": 30,
            "sex": "unknown"  # 不正な値
        }
        response = client.post("/survived", json=invalid_data)

        assert response.status_code == 422  # Validation Error

    def test_Boston予測のエンドツーエンドフロー(
        self, client, boston_sample_data
    ) -> None:
        """Boston 予測の完全なフローが正しく動作する."""
        response = client.post("/boston", json=boston_sample_data)

        assert response.status_code == 200
        data = response.json()
        assert "predicted_price" in data
        assert isinstance(data["predicted_price"], (int, float))
        assert data["predicted_price"] > 0

    def test_Boston予測で必須フィールド欠落を拒否する(self, client) -> None:
        """必須フィールドが欠けている場合エラーを返す."""
        invalid_data = {
            "rm": 6.5,
            "lstat": 4.98
            # ptratio が欠けている
        }
        response = client.post("/boston", json=invalid_data)

        assert response.status_code == 422  # Validation Error

    def test_存在しないエンドポイントで404を返す(self, client) -> None:
        """存在しないエンドポイントにアクセスすると 404 を返す."""
        response = client.get("/nonexistent")

        assert response.status_code == 404

    def test_複数のエンドポイントを連続して呼び出せる(
        self, client, iris_sample_data, cinema_sample_data
    ) -> None:
        """複数のエンドポイントを連続して呼び出しても正しく動作する."""
        # Iris 予測
        response1 = client.post("/iris", json=iris_sample_data)
        assert response1.status_code == 200

        # Cinema 予測
        response2 = client.post("/cinema", json=cinema_sample_data)
        assert response2.status_code == 200

        # それぞれの結果が独立している
        assert "species" in response1.json()
        assert "predicted_sales" in response2.json()

統合テストのベストプラクティス

テストの独立性を保つ
- 各テストは他のテストに依存しない
- フィクスチャを使って毎回クリーンな状態でテスト
実際のユースケースをテストする
- 単体テストでカバーできない複雑なシナリオを検証
- エラーケースも含めて網羅的にテスト
適切なアサーション
- ステータスコードの確認
- レスポンスボディの構造と型の確認
- ビジネスロジックに沿った値の検証
テストの可読性
- テスト名は日本語で動作を明確に記述
- AAA パターン（Arrange-Act-Assert）に従う
テストの保守性
- フィクスチャで共通データを管理
- マジックナンバーを避け、意味のある変数名を使う

統合テストの実行

# 統合テストのみ実行
pytest test/test_integration.py -v

# すべてのテストを実行
pytest test/ -v

# カバレッジ付きで実行
pytest test/ --cov=api --cov-report=term-missing

期待される出力:

test/test_integration.py::TestAPIIntegration::test_ルートエンドポイントが正しく動作する PASSED
test/test_integration.py::TestAPIIntegration::test_ヘルスチェックが正しく動作する PASSED
test/test_integration.py::TestAPIIntegration::test_Iris予測のエンドツーエンドフロー PASSED
test/test_integration.py::TestAPIIntegration::test_Iris予測で不正なデータを拒否する PASSED
test/test_integration.py::TestAPIIntegration::test_Cinema予測のエンドツーエンドフロー PASSED
test/test_integration.py::TestAPIIntegration::test_Cinema予測でactor範囲外を拒否する PASSED
test/test_integration.py::TestAPIIntegration::test_Survived予測のエンドツーエンドフロー PASSED
test/test_integration.py::TestAPIIntegration::test_Survived予測で不正なsexを拒否する PASSED
test/test_integration.py::TestAPIIntegration::test_Boston予測のエンドツーエンドフロー PASSED
test/test_integration.py::TestAPIIntegration::test_Boston予測で必須フィールド欠落を拒否する PASSED
test/test_integration.py::TestAPIIntegration::test_存在しないエンドポイントで404を返す PASSED
test/test_integration.py::TestAPIIntegration::test_複数のエンドポイントを連続して呼び出せる PASSED

============ 12 passed in 2.34s ============

実践的な API 使用例

1. API サーバーの起動

# FastAPI サーバーを起動（開発モード）
uvicorn app.application:app --reload

# 出力:
# INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
# INFO:     Started reloader process [xxxxx] using StatReload
# INFO:     Started server process [xxxxx]
# INFO:     Waiting for application startup.
# INFO:     Application startup complete.

2. Swagger UI での確認

ブラウザで http://127.0.0.1:8000/docs にアクセスすると、自動生成された API ドキュメントが表示されます。

┌────────────────────────────────────────────────┐
│ Machine Learning API - Swagger UI              │
├────────────────────────────────────────────────┤
│                                                 │
│ GET  /          ルートエンドポイント            │
│ GET  /health    ヘルスチェック                  │
│                                                 │
│ POST /iris      アヤメの種類を分類              │
│ POST /cinema    映画の興行収入を予測            │
│ POST /survived  タイタニック号での生存を予測   │
│ POST /boston    ボストン住宅価格を予測          │
│                                                 │
│ [Try it out] ボタンでインタラクティブにテスト可能 │
└────────────────────────────────────────────────┘

3. curl による API テスト

Iris 分類:

curl -X POST "http://127.0.0.1:8000/iris" \
  -H "Content-Type: application/json" \
  -d '{
    "sepal_length": 5.1,
    "sepal_width": 3.5,
    "petal_length": 1.4,
    "petal_width": 0.2
  }'

# レスポンス:
# {"species":"setosa"}

Cinema 売上予測:

curl -X POST "http://127.0.0.1:8000/cinema" \
  -H "Content-Type: application/json" \
  -d '{
    "sns1": 500,
    "sns2": 300,
    "actor": 70,
    "original": 1
  }'

# レスポンス:
# {"predicted_sales":3254.72}

Survived 生存予測:

curl -X POST "http://127.0.0.1:8000/survived" \
  -H "Content-Type: application/json" \
  -d '{
    "pclass": 3,
    "age": 22,
    "sex": "male"
  }'

# レスポンス:
# {"survived":0}

Boston 住宅価格予測:

curl -X POST "http://127.0.0.1:8000/boston" \
  -H "Content-Type: application/json" \
  -d '{
    "rm": 6.5,
    "lstat": 4.98,
    "ptratio": 15.3
  }'

# レスポンス:
# {"predicted_price":32.45}

4. Python スクリプトからの利用

# api_client_example.py
import requests

BASE_URL = "http://127.0.0.1:8000"

def predict_iris():
    """Iris 分類の実行例"""
    response = requests.post(f"{BASE_URL}/iris", json={
        "sepal_length": 5.1,
        "sepal_width": 3.5,
        "petal_length": 1.4,
        "petal_width": 0.2
    })

    print(f"Iris 予測結果: {response.json()}")
    # 出力: Iris 予測結果: {'species': 'setosa'}

def predict_cinema():
    """Cinema 売上予測の実行例"""
    response = requests.post(f"{BASE_URL}/cinema", json={
        "sns1": 500,
        "sns2": 300,
        "actor": 70,
        "original": 1
    })

    result = response.json()
    print(f"Cinema 売上予測: {result['predicted_sales']:.2f} 万円")
    # 出力: Cinema 売上予測: 3254.72 万円

def predict_survived():
    """Survived 生存予測の実行例"""
    passengers = [
        {"pclass": 1, "age": 30, "sex": "female"},
        {"pclass": 3, "age": 22, "sex": "male"},
    ]

    for passenger in passengers:
        response = requests.post(f"{BASE_URL}/survived", json=passenger)
        result = response.json()
        survival_status = "生存" if result['survived'] == 1 else "死亡"
        print(f"{passenger} → {survival_status}")

    # 出力:
    # {'pclass': 1, 'age': 30, 'sex': 'female'} → 生存
    # {'pclass': 3, 'age': 22, 'sex': 'male'} → 死亡

def predict_boston():
    """Boston 住宅価格予測の実行例"""
    response = requests.post(f"{BASE_URL}/boston", json={
        "rm": 6.5,
        "lstat": 4.98,
        "ptratio": 15.3
    })

    result = response.json()
    print(f"Boston 住宅価格予測: ${result['predicted_price']:.2f}k")
    # 出力: Boston 住宅価格予測: $32.45k

if __name__ == "__main__":
    predict_iris()
    predict_cinema()
    predict_survived()
    predict_boston()

実行結果:

$ python api_client_example.py
Iris 予測結果: {'species': 'setosa'}
Cinema 売上予測: 3254.72 万円
{'pclass': 1, 'age': 30, 'sex': 'female'} → 生存
{'pclass': 3, 'age': 22, 'sex': 'male'} → 死亡
Boston 住宅価格予測: $32.45k

📊 ８章の技術的成果

「ついに API システムが完成しました！」お疲れさまでした！８章で何を達成したか、振り返ってみましょう。

✅ テスト結果

すべてのテストが通りました！

$ pytest -v --cov=app --cov-report=term-missing

========================== test session starts ==========================
collected 25 items

test/test_models.py::test_IrisModelの正常な値 PASSED                [ 4%]
test/test_models.py::test_IrisModelの負の値でエラー PASSED           [ 8%]
test/test_models.py::test_CinemaModelの正常な値 PASSED              [12%]
test/test_models.py::test_SurvivedModelの正常な値 PASSED            [16%]
test/test_models.py::test_SurvivedModelの不正なsexでエラー PASSED   [20%]
test/test_models.py::test_BostonModelの正常な値 PASSED              [24%]
test/test_domain.py::test_IrisDomainでモデルを読み込める PASSED     [28%]
test/test_domain.py::test_IrisDomainで予測ができる PASSED           [32%]
test/test_domain.py::test_CinemaDomainでモデルを読み込める PASSED   [36%]
test/test_domain.py::test_CinemaDomainで予測ができる PASSED         [40%]
test/test_domain.py::test_SurvivedDomainでモデルを読み込める PASSED [44%]
test/test_domain.py::test_SurvivedDomainで予測ができる PASSED       [48%]
test/test_domain.py::test_BostonDomainでモデルを読み込める PASSED   [52%]
test/test_domain.py::test_BostonDomainで予測ができる PASSED         [56%]
test/test_service.py::test_predict_iris PASSED                      [60%]
test/test_service.py::test_predict_cinema PASSED                    [64%]
test/test_service.py::test_predict_survived PASSED                  [68%]
test/test_service.py::test_predict_boston PASSED                    [72%]
test/test_application.py::test_Irisエンドポイントの正常系 PASSED     [76%]
test/test_application.py::test_Irisエンドポイントの異常系 PASSED     [80%]
test/test_application.py::test_Cinemaエンドポイントの正常系 PASSED   [84%]
test/test_application.py::test_Survivedエンドポイントの正常系 PASSED [88%]
test/test_application.py::test_Bostonエンドポイントの正常系 PASSED   [92%]
test/test_application.py::test_ルートエンドポイント PASSED           [96%]
test/test_application.py::test_ヘルスチェック PASSED                [100%]

---------- coverage: platform win32, python 3.12.0-final-0 ----------
Name                   Stmts   Miss  Cover   Missing
----------------------------------------------------
app/__init__.py            0      0   100%
app/application.py        45      2    96%   23, 67
app/domain.py             85      4    95%   18, 52, 86, 121
app/models.py             20      0   100%
app/service.py            38      1    97%   58
----------------------------------------------------
TOTAL                    188      7    96%

========================== 25 passed in 1.23s ==========================

25 passed！ 🎉 すべてのレイヤーでテストが通っています！

📈 定量的成果

数字で見ると、こんなに達成しました！

指標	🎯 達成値	詳細
🧪 テストケース数	25 個	Pydantic (6) + Domain (8) + Service (4) + Application (7)
📊 コードカバレッジ	96%	高い品質基準を達成！
🌐 API エンドポイント	6 個	予測 API 4 個 + ヘルスチェック 2 個
⚡ レスポンス時間	< 100ms	高速なモデル推論
📚 自動ドキュメント	100%	Swagger UI で完全にドキュメント化

カバレッジ 96%！ これはプロダクションレベルの品質です！🎊

🎓 習得したスキル

1. 🌐 Web API 開発

✅ FastAPI によるモダンな API 開発
✅ Pydantic による型安全なデータ検証
✅ OpenAPI 仕様の自動生成

2. 🏗️ アーキテクチャパターン

✅ レイヤードアーキテクチャの実践（3 層分離）
✅ Lazy Loading パターン
✅ Repository パターン（ドメイン層）

3. 🚀 本番運用スキル

✅ pickle によるモデルの永続化と読み込み
✅ エラーハンドリングとロギング
✅ ヘルスチェックエンドポイントの実装

4. 🧪 テスト戦略

✅ 統合テスト（FastAPI TestClient）
✅ 各層のユニットテスト
✅ バリデーションテスト

🎊 プロジェクト全体のまとめ

「ついにここまで来ました！」お疲れさまでした！振り返ってみると、すごい量のことを学びましたね。

このプロジェクトを通じて、機械学習の基礎から Web API 構築まで、段階的にスキルを習得してきました。あなたの成長を数字で見てみましょう！

📊 あなたが達成したこと（定量的成果）

指標	🎯 達成値	詳細
🧪 総テストケース数	84 個	２章 (9) + ４章 (9) + ５章 (11) + ６章 (13) + ７章 (17) + ８章 (25)
📊 平均コードカバレッジ	94%	全ての章で 90% 以上を達成！
🤖 完成モデル数	4 本	Iris、Cinema、Survived、Boston の実用モデル
🌐 API エンドポイント数	6 個	予測 API 4 個 + ヘルスチェック 2 個
📝 総コード行数	約 1,500 行	高品質で保守性の高いコードベース
🔄 TDD サイクル実践回数	約 30 回	Red-Green-Refactor を徹底的に実践

すごいですよね！ これだけのコードを TDD で書いたんです！

📚 各章で達成したこと

章	🧪 テスト数	📊 カバレッジ	🎯 主要成果
２章基礎準備	9 個	100%	DataLoader、プロジェクト構造、品質管理ツール
４章 Iris 分類	9 個	95%	決定木分類、欠損値補完、97.78% 精度達成
５章 Cinema 回帰	11 個	92%	線形回帰、外れ値除去、R²=0.8383 達成
６章 Survived 分類	13 個	90%	グループ別補完、ダミー変数、83.24% 精度達成
７章 Boston 回帰	17 個	94%	特徴量エンジニアリング、標準化、R²=0.8313 達成
８章 API 化	25 個	96%	FastAPI、レイヤードアーキテクチャ、Swagger UI

🎓 あなたが習得したスキル全体像

「こんなに学んだの！？」そうです！リストにしてみると、本当にたくさんのスキルを習得しました！

1. 🔄 テスト駆動開発（TDD）マスタリー

✅ Red-Green-Refactor サイクルの完全習得 - 約 30 サイクル実践
✅ テストファースト思考の習慣化 - 実装よりテストを先に書く
✅ 継続的リファクタリング - テストがあるから安心して改善できる
✅ pytest による包括的テストスイート構築 - 自動テストの力を実感

2. 🐍 モダン Python 開発の完全習得

✅ 型ヒント完全活用 - 100% カバレッジで型安全性確保
✅ 現代的ツールチェーン - uv、Ruff、mypy の使いこなし
✅ Pydantic によるデータ検証 - 強力なバリデーション機能
✅ FastAPI によるモダンな Web API 開発 - 最速・最新のフレームワーク

3. 🤖 機械学習基礎の確立

🌸 分類問題: 決定木（Iris、Survived）
📊 回帰問題: 線形回帰（Cinema、Boston）
🔧 データ前処理: 欠損値補完、外れ値除去、標準化、ダミー変数化
📈 モデル評価: Accuracy、R² Score、MAE、RMSE
⚙️ 特徴量エンジニアリング: 2 乗項、交互作用項
⚖️ クラス不均衡対応: class_weight='balanced'
🛡️ データリーケージ防止: 訓練とテストの厳密な分離

4. 🏗️ ソフトウェア工学実践

🏛️ アーキテクチャ設計: レイヤードアーキテクチャ（Application/Service/Domain）
🎨 デザインパターン: Lazy Loading、Repository パターン
✅ 品質管理: 定量的品質指標、継続的インテグレーション
🌐 API 設計: RESTful API、OpenAPI 仕様、Swagger UI
⚠️ エラーハンドリング: 適切な例外処理とエラーメッセージ

📈 あなたの成長ストーリー

「振り返ってみると、こんなに成長したんだ！」と実感できるように、3 つのフェーズで学習内容がどう進化したか見てみましょう。

🌱 Phase 1（２章・４章）: 基礎構造確立

最初はシンプルに！

# シンプルな分類モデル
class IrisClassifier:
    def load_data(self, file_path): pass      # データ読み込み
    def train(self, X_train, y_train): pass   # モデル訓練
    def predict(self, X_test): pass           # 予測
    def evaluate(self, X_test, y_test): pass  # 評価

🎯 達成レベル: 機械学習の基本フローを理解！

🌿 Phase 2（５章・６章）: 複雑化対応

実務レベルの前処理を習得！

# データ前処理の追加
class SurvivedClassifier:
    def _preprocess_age(self, df): pass      # グループ別補完（高度！）
    def _encode_categorical(self, df): pass  # ダミー変数化
    def train(self, X_train, y_train): pass  # モデル訓練
    def predict(self, X_test): pass          # 予測

🎯 達成レベル: 実務レベルのデータ処理技術を習得！

🌳 Phase 3（７章・８章）: 統合システム

プロレベルの API システム構築！

# API 化と統合
class MLService:
    def __init__(self):
        self.iris_domain = IrisDomain()         # Iris モデル
        self.cinema_domain = CinemaDomain()     # Cinema モデル
        self.survived_domain = SurvivedDomain() # Survived モデル
        self.boston_domain = BostonDomain()     # Boston モデル

    def predict_iris(self, features): pass         # Iris 予測 API
    def predict_cinema(self, features): pass       # Cinema 予測 API
    def predict_survived(self, pclass, age, sex): pass  # Survived 予測 API
    def predict_boston(self, rm, lstat, ptratio): pass  # Boston 予測 API

🎯 達成レベル: 本番環境レディな API システム構築！

すごい成長ですよね！ 最初はシンプルな分類モデルだったのが、最後には 4 つのモデルを統合した本格的な API システムまで作れるようになりました！

🚀 これからのあなたへ

「学んだことは、実際にどう使えるの？」良い質問です！習得したスキルは、すぐに実務で使えます！

💼 業務で即使えるスキル

🔄 テスト駆動開発

✅ 企業開発で求められる品質管理手法
✅ 安全なリファクタリング技術
✅ 継続的インテグレーション対応

🤖 機械学習実装

✅ データ前処理からモデル訓練までの完全フロー
✅ モデルの評価と改善プロセス
✅ 本番環境へのデプロイメント技術

🌐 Web API 開発

✅ RESTful API 設計とドキュメント化
✅ レイヤードアーキテクチャによる保守性確保
✅ エラーハンドリングとバリデーション

🌟 今後の発展可能性

「次は何を学べばいいの？」ここから先は、あなたの興味に応じて、こんな方向に進めます！

🔬 技術的拡張方向

🧠 高度なモデル - ディープラーニング（TensorFlow、PyTorch）、アンサンブル学習
🔧 MLOps - モデルバージョニング、A/B テスト、モデル監視
📈 スケーリング - バッチ予測、リアルタイム推論、分散処理

💼 ビジネス適用

📊 実業務適用 - 顧客行動予測、需要予測、不正検知
🚀 プロダクト化 - SaaS としての機械学習 API サービス
🏢 データ分析基盤 - 企業内データ分析プラットフォームの構築

📚 教育・コミュニティ活用

👨‍🏫 教育教材 - データサイエンス講座の実践教材
オープンソース: コミュニティによる機能拡張
企業研修: 機械学習エンジニア育成プログラム

🏆 このプロジェクトの特別なところ

「他のチュートリアルと何が違うの？」良い質問です！このプロジェクトは、テスト駆動開発と機械学習を同時に学べる、とてもユニークな教材なんです！

💎 成功要因

📚 段階的学習設計 - ２章から８章への無理のないスキルアップ曲線
🎯 実践的アプローチ - 理論ではなく実際に動作するモデルで学習
✅ 品質重視 - 高い品質基準（カバレッジ 90% 以上）で学習効果を最大化
📖 包括的ドキュメント - 再現可能で持続的な学習プロセス

⭐ 他のチュートリアルとの違い

一般的な機械学習チュートリアル	🎉 このプロジェクト
Jupyter Notebook で完結	TDD + 本番レディな API
モデル訓練のみ	データ処理から API 化まで完全フロー
テストなし	84 個のテストケース、94% カバレッジ
単一モデル	4 つの異なる問題を段階的に解決
型ヒントなし	完全な型安全性
ドキュメント不足	詳細な実装ガイド + Swagger UI

🎓 最後に

おめでとうございます！ 🎊

このプロジェクトを完了したあなたは、以下を手に入れました：

✅ 即実践可能な TDD スキル - 業務レベルでの品質開発手法
✅ 機械学習の実用基礎 - データサイエンス業界への参入基盤
✅ モダン Python 開発力 - 現場で求められる最新技術スタック
✅ 継続的改善マインド - 品質と効率を両立する開発思考
✅ 本番運用知識 - 実際のプロダクト開発に必要な包括的知識

あなたは今、Python TDD 機械学習開発マスターへの道を歩み始めました！ ✨

この学びを活かして、あなただけの素晴らしいプロダクトを作ってください！

次のステップ

このプロジェクトを完了した後の推奨学習パスです：

1. 実践課題

初級課題（1-2週間）:

Kaggle の Titanic コンペティションに TDD でチャレンジ
既存の 4モデルに新しい特徴量を追加してモデル改善
API に認証機能（JWT）を追加

中級課題（2-4週間）:

時系列データ（株価予測、需要予測）の機械学習モデル開発
アンサンブル学習（Random Forest、XGBoost）の実装
Docker によるコンテナ化と CI/CD パイプラインの構築

上級課題（1-2ヶ月）:

ディープラーニング（TensorFlow/PyTorch）への拡張
MLOps ツール（MLflow、DVC）の導入
本番環境へのデプロイ（AWS Lambda、GCP Cloud Run）

2. 推奨学習リソース

書籍:

『Python ではじめる機械学習』（Andreas C. Müller、Sarah Guido 著）
『テスト駆動開発』（Kent Beck 著）
『Clean Architecture』（Robert C. Martin 著）

オンラインコース:

コミュニティ:

Kaggle: 機械学習コンペティション
PyData: Python データサイエンスコミュニティ
ML Papers: 最新の機械学習論文と実装

3. キャリアパス

本プロジェクトのスキルセットは以下の職種に直結します：

機械学習エンジニア: モデル開発とデプロイ
データサイエンティスト: データ分析とビジネス価値創出
MLOps エンジニア: ML システムの運用と最適化
バックエンドエンジニア（ML 特化）: API 開発とシステム統合

参考資料

スッキリわかるPythonによる機械学習入門第2版スッキリわかるシリーズ

公式ドキュメント:

開発ツール: