# 機能設計書 74-recode_factor

## 概要

本ドキュメントは、dplyrパッケージの`recode_factor()`関数に関する機能設計書です。`recode_factor()`は、値を再コード化し、結果を因子（factor）として返す関数で、レベルの順序を置換ルールの順序に合わせます。

### 本機能の処理概要

`recode_factor()`関数は、`recode()`関数の変種であり、値を再コード化した後、結果を因子として返します。重要な特徴は、因子のレベル順序が置換ルールの指定順序に従うことです。

**業務上の目的・背景**：データ分析において、カテゴリカル変数を特定の順序を持つ因子として扱いたい場合があります。例えば、アンケートの回答（非常に不満、不満、普通、満足、非常に満足）を論理的な順序で因子化したい場合です。`recode_factor()`は、再コード化と順序付き因子化を一度に行うことができます。ただし、dplyr 1.1.0以降では非推奨（superseded）となり、将来的にはforcatsパッケージに代替機能が追加される予定です。

**機能の利用シーン**：
- 数値コードをラベル付き因子に変換する場合
- カテゴリの順序を明示的に指定したい場合
- 順序付き因子（ordered factor）を作成する場合
- 欠損値に特別なレベルを割り当てる場合

**主要な処理内容**：
1. `recode()`を呼び出して値を再コード化
2. 置換ルールの順序に基づいてレベル順序を決定
3. `.default`と`.missing`を適切な位置にレベルとして追加
4. 因子として結果を返却

**関連システム・外部連携**：外部システムとの連携はありません。dplyr内部で完結する機能です。

**権限による制御**：特になし。Rの関数として公開されており、dplyrをロードした任意のユーザーが使用可能です。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | 該当なし | - | 本プロジェクトはRライブラリであり、ユーザーインターフェース画面は存在しません |

## 機能種別

値変換 / データ変換 / 因子化

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| .x | vector | Yes | 変換対象のベクトル | NULLでないこと |
| ... | dynamic-dots | Yes | 置換ルール。名前付き引数で指定 | 少なくとも1つは必要 |
| .default | any | No | 未マッチ値のデフォルト値 | 長さ1または.xと同じ長さ |
| .missing | any | No | NA値の置換値 | 長さ1または.xと同じ長さ |
| .ordered | logical | No | TRUEで順序付き因子を作成 | 論理値 |

### 入力データソース

関数の引数として直接渡されるベクトル。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | factor | レベル順序が置換ルールの順序に従う因子 |

### 出力先

呼び出し元のR環境に返却されます。

## 処理フロー

### 処理シーケンス

```
1. superseded警告の発行
   └─ lifecycle::signal_stage()でsupersededであることを通知
2. recode()の呼び出し
   └─ 内部でrecode()を使用して値を再コード化
3. レベル順序の決定
   └─ 置換ルール、.default、.missingの順でレベルを構成
4. 因子の作成と返却
   └─ factor()で指定したレベル順序の因子を作成
```

### フローチャート

```mermaid
flowchart TD
    A[recode_factor呼び出し] --> B[superseded警告を発行]
    B --> C[recode で値を再コード化]
    C --> D[レベル順序を決定]
    D --> E{.orderedは TRUE?}
    E -->|Yes| F[順序付き因子を作成]
    E -->|No| G[通常の因子を作成]
    F --> H[結果を返却]
    G --> H
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-74-01 | レベル順序 | レベルは置換ルールの指定順序に従う | 常時 |
| BR-74-02 | default位置 | .defaultのレベルは最後に追加される | .defaultが指定された場合 |
| BR-74-03 | missing位置 | .missingのレベルは.defaultの後に追加される | .missingが指定された場合 |
| BR-74-04 | ordered指定 | .ordered=TRUEで順序付き因子を作成 | .orderedがTRUEの場合 |
| BR-74-05 | 未網羅警告 | すべての値を網羅しない場合は警告 | 一部の値が未置換の場合 |

### 計算ロジック

**レベル順序の決定**:
1. 置換ルール（...）の順序でレベルを構成
2. `.default`がある場合、レベルの末尾に追加
3. `.missing`がある場合、さらにその後に追加
4. 実際にデータに存在するレベルのみを最終的なレベルとして使用

## データベース操作仕様

### 操作別データベース影響一覧

本機能はデータベースを直接操作しません。

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| - | - | - | メモリ内データの操作のみ |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | エラー | 置換ルールが指定されていない | 少なくとも1つの置換ルールを指定 |
| - | 警告 | 一部の値が未置換 | .defaultを指定するか全値を網羅 |

### リトライ仕様

リトライ機構はありません。

## トランザクション仕様

トランザクション管理はありません（メモリ内操作のため）。

## パフォーマンス要件

- 線形時間計算量（O(n)）で動作
- recode()を内部で呼び出すため、recode()と同等のパフォーマンス

## セキュリティ考慮事項

特別なセキュリティ考慮事項はありません。

## 備考

- dplyr 1.1.0でsuperseded（非推奨）となりました
- 直接の代替は現在存在しませんが、将来的にforcatsパッケージに追加予定
- 現在の代替方法: ルックアップテーブルを使用し、`to`列を因子に変換して`recode_values()`を使用
- 既存の因子のレベル順序を維持したい場合は`recode()`を使用してください

---

## コードリーディングガイド

本機能を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

因子（factor）の構造とレベルの概念を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | recode.R | `R/recode.R` | recode_factor関数の定義と因子のレベル処理 |

**読解のコツ**: Rの因子（factor）はレベルの順序を持つことが重要です。`levels`引数によってこの順序を制御できることを理解してください。

#### Step 2: エントリーポイントを理解する

処理の起点となる関数を特定します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | recode.R | `R/recode.R` | recode_factor関数の定義（332-354行目） |

**主要処理フロー**:
1. **339-340行目**: superseded警告を発行
2. **342-343行目**: list2(...)で置換ルールを取得し、recode()を呼び出し
3. **345-351行目**: レベル順序を決定（values, .default, .missingの順）
4. **353行目**: factor()で因子を作成して返却

#### Step 3: 関連する内部関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | recode.R | `R/recode.R` | recode()関数 - 値の再コード化を担当 |
| 3-2 | recode.R | `R/recode.R` | recode_default()メソッド - デフォルト値の決定 |

**主要処理フロー（recode_factor内部）**:
- **342行目**: list2(...)で動的引数を取得
- **343行目**: recode()を呼び出し、実際の値変換を実行
- **345-349行目**: all_levelsを構成（values, recode_default結果, .missing）
- **350行目**: 実際に存在するレベルのみをrecoded_levelsとして取得
- **351行目**: all_levelsとrecoded_levelsの交差を最終レベルとする
- **353行目**: factor()で因子化、.orderedフラグで順序付き因子かを決定

### プログラム呼び出し階層図

```
recode_factor(.x, ...) [R/recode.R:332-354]
    │
    ├─ lifecycle::signal_stage() [外部パッケージ]
    │      └─ superseded警告を発行
    │
    ├─ list2(...) [rlang]
    │      └─ 動的引数を取得
    │
    ├─ recode(.x, !!!values, .default, .missing) [R/recode.R:170-174]
    │      └─ 値の再コード化を実行
    │
    ├─ unique() [base]
    │      └─ all_levelsの重複を除去
    │
    ├─ recode_default(.x, .default, recoded) [R/recode.R:303-328]
    │      └─ デフォルト値を決定
    │
    ├─ intersect() [base]
    │      └─ all_levelsとrecoded_levelsの交差
    │
    └─ factor(recoded, levels, ordered) [base]
           └─ 最終的な因子を作成
```

### データフロー図

```
[入力]                      [処理]                         [出力]

.x (vector) ─────────────▶ recode()で再コード化
                                │
                                ▼
... (置換ルール) ─────────▶ list2()で取得
                                │
                                ▼
                          レベル順序を決定
                          (values, .default, .missing)
                                │
                                ▼
                          実在レベルとの交差
                                │
                                ▼
.ordered ─────────────────▶ factor()で因子化
                                │
                                ▼
                           因子 ─────────────────────▶ 呼び出し元
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| recode.R | `R/recode.R` | ソース | recode/recode_factor関数の実装 |
| recode-values.R | `R/recode-values.R` | ソース | 後継関数の実装 |
| test-recode.R | `tests/testthat/test-recode.R` | テスト | recode_factorのテストケース |
