# 機能設計書 8-transmute

## 概要

本ドキュメントは、dplyrパッケージの`transmute`関数に関する機能設計書です。`transmute`関数は、新しい列を作成し、それ以外の列を削除する機能を提供します。現在は`mutate(.keep = "none")`に置き換えられ、非推奨（superseded）となっています。

### 本機能の処理概要

`transmute`関数は、指定された計算式で新しい列を作成し、元のデータフレームの他の列を全て削除するデータ操作関数です。`mutate`関数の変種として位置づけられ、内部的には`mutate_cols`を使用して実装されています。

**業務上の目的・背景**：特定の計算結果のみを必要とし、元のデータの他の列が不要な場合に使用されていました。しかし、dplyr 1.0.0で`mutate`に`.keep`引数が追加されたことで、`transmute`の機能は`mutate(.keep = "none")`で完全に代替可能となり、非推奨となりました。

**機能の利用シーン**：
- 計算結果のみを含む新しいデータフレームの作成
- 元データを保持せず、派生データのみを取得
- ※現在は`mutate(.keep = "none")`の使用を推奨

**主要な処理内容**：
1. lifecycle警告の発出（superseded）
2. 非サポート引数のチェック（.keep、.before、.after）
3. `mutate_cols`による列計算
4. `dplyr_col_modify`による列適用
5. グループ変数と計算列のみを出力列として選択

**関連システム・外部連携**：
- lifecycle: 非推奨警告の管理
- mutate: 内部実装の共有

**権限による制御**：該当なし（Rライブラリのため）

## 関連画面

本プロジェクトはRライブラリ（dplyr）であり、ユーザーインターフェース画面は存在しません。

## 機能種別

データ操作（列の作成・選択）/ データ変換 / 非推奨機能

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| .data | data.frame | Yes | 処理対象のデータフレーム | data.frameまたはその派生クラス |
| ... | expressions | No | 列を作成する式（name = value形式） | - |

※ `.keep`、`.before`、`.after`引数はサポートされない

### 入力データソース

- メモリ上のdata.frame、tibble、grouped_df

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | .dataと同じ型 | 計算列とグループ変数のみを含むデータフレーム |

### 出力先

- 関数の戻り値として返却（メモリ上）

## 処理フロー

### 処理シーケンス

```
1. lifecycle警告の発出
   └─ lifecycle::signal_stage("superseded", ...)
2. 引数チェック
   └─ check_transmute_args(): .keep/.before/.afterを拒否
3. mutate_cols()の実行
   └─ mutate関数と同じ内部実装を使用
4. dplyr_col_modify()で列を適用
5. 出力列の選択
   └─ NULLで削除された列を除外
   └─ グループ変数を先頭に配置
   └─ 計算列を順序通り配置
6. dplyr_col_select()で列を選択
```

### フローチャート

```mermaid
flowchart TD
    A[transmute開始] --> B[lifecycle警告]
    B --> C[check_transmute_args]
    C --> D{.keep/.before/.after?}
    D -->|あり| E[エラー終了]
    D -->|なし| F[mutate_cols]
    F --> G[dplyr_col_modify]
    G --> H[NULL列を除外]
    H --> I[グループ変数を先頭に]
    I --> J[計算列を配置]
    J --> K[dplyr_col_select]
    K --> L[結果返却]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | 列の限定出力 | 計算列とグループ変数のみが出力される | 常時 |
| BR-02 | 行数の不変 | 行数は変更されない | 常時 |
| BR-03 | グループ変数の保持 | グループ変数は自動的に先頭に配置される | grouped_df使用時 |
| BR-04 | NULL削除 | NULLを設定した列は出力から除外される | 常時 |
| BR-05 | 非推奨 | dplyr 1.1.0以降は`mutate(.keep = "none")`を推奨 | 常時 |

### 計算ロジック

- `mutate_cols`と同じ計算ロジックを使用
- 出力は`cols_group + cols_expr`の順序

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

該当なし（インメモリ操作のみ）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | abort | .keep引数を指定した場合 | mutate(.keep = ...)を使用 |
| - | abort | .before引数を指定した場合 | mutate(.before = ...)を使用 |
| - | abort | .after引数を指定した場合 | mutate(.after = ...)を使用 |

### リトライ仕様

該当なし（同期処理のため）

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

該当なし（インメモリ操作のため）

## パフォーマンス要件

- `mutate`と同等のパフォーマンス

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

- 入力データの検証はdplyrフレームワーク内で実施

## 備考

- **非推奨（superseded）**: `mutate(.keep = "none")`を使用することを推奨
- dplyr 1.1.0でsupersedとしてマーク
- `.by`引数は公開されていない（内部的には使用されていない）

---

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

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

### 推奨読解順序

#### Step 1: transmute関数の定義を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | transmute.R | `R/transmute.R` | transmute関数の定義とlifecycle警告 |

**読解のコツ**: transmute.Rは非常に短いファイルで、mutate_colsを再利用している点に注目。

**主要処理フロー**:
- **30-39行目**: transmute関数定義
- **32-36行目**: lifecycle::signal_stage - 非推奨警告

#### Step 2: data.frame向け実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | transmute.R | `R/transmute.R` | transmute.data.frame実装 |

**主要処理フロー**:
- **42-69行目**: transmute.data.frame
- **43行目**: check_transmute_args - 非サポート引数のチェック
- **49行目**: mutate_cols - mutateと共通の列計算
- **51行目**: dplyr_col_modify - 列の適用
- **57-58行目**: compact_null - NULL列の除外
- **60-66行目**: 出力列の決定

#### Step 3: 引数チェックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | transmute.R | `R/transmute.R` | check_transmute_args関数 |

**主要処理フロー**:
- **73-91行目**: check_transmute_args
- **80-88行目**: .keep/.before/.afterを拒否

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

```
transmute(.data, ...)
    │
    ├─ lifecycle::signal_stage("superseded", "transmute()", ...)
    │      └─ 非推奨警告を発出
    │
    └─ UseMethod("transmute")
           │
           └─ transmute.data.frame(.data, ...)
                  │
                  ├─ check_transmute_args(...)
                  │      └─ .keep/.before/.afterがあればエラー
                  │
                  ├─ dplyr_quosures(!!!dots)
                  │
                  ├─ compute_by(by = NULL, data)  ← .byは常にNULL
                  │
                  ├─ mutate_cols(.data, dots, by)
                  │      └─ mutateと同じ処理
                  │
                  ├─ dplyr_col_modify(.data, cols)
                  │
                  ├─ compact_null(cols)
                  │      └─ NULL列を除去
                  │
                  └─ dplyr_col_select(out, cols_retain)
                         └─ cols_group + cols_expr
```

### データフロー図

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

.data (data.frame)  ───▶ mutate_cols ───▶ dplyr_col_modify ───▶ 列選択
      │                       │                  │               │
      │                       ▼                  ▼               ▼
      │                  計算列リスト       適用済みdf    グループ変数+計算列
      │                       │                  │               │
      └───────────────────────┴──────────────────┴───────────────┘
                                                                 │
                                                                 ▼
                                                       dplyr_col_select
                                                                 │
                                                                 ▼
                                                        結果data.frame
                                                    （計算列のみ含む）
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| transmute.R | `R/transmute.R` | ソース | transmute関数の実装 |
| mutate.R | `R/mutate.R` | ソース | mutate_cols関数（共有） |
| generics.R | `R/generics.R` | ソース | dplyr_col_modify, dplyr_col_select |
