# 機能設計書 82-as_tibble

## 概要

本ドキュメントは、dplyrパッケージが再エクスポートするas_tibble関数の機能設計を記述する。as_tibbleは既存のオブジェクト（data.frame、リスト、行列等）をtibble形式に変換する型変換ユーティリティであり、dplyrのデータ操作パイプラインへのデータ投入口として重要な役割を果たす。

### 本機能の処理概要

as_tibble関数は、様々なR オブジェクトをtibble（tbl_df）形式に変換する汎用的な型変換機能を提供する。S3ジェネリック関数として実装されており、入力オブジェクトの型に応じた適切な変換メソッドが自動的に選択される。

**業務上の目的・背景**：データ分析の現場では、CSVファイルの読み込み、データベースからのデータ取得、他のパッケージからの出力など、様々な形式のデータを扱う必要がある。これらのデータをtidyverseエコシステムで一貫して処理するためには、tibble形式への統一的な変換手段が不可欠である。as_tibbleは従来のdata.frameや行列、リストなどの多様なデータ構造をtibbleに変換し、dplyrを含むtidyverseパッケージでの一貫したデータ操作を可能にする。

**機能の利用シーン**：base Rのdata.frameをtibbleに変換する場合、行列をデータフレーム形式に変換する場合、名前付きリストをtibbleに変換する場合、他のパッケージが返すdata.frame互換オブジェクトをtibbleに標準化する場合、grouped_dfやrowwise_dfからグループ情報を除去してプレーンなtibbleに戻す場合などに利用される。

**主要な処理内容**：
1. 入力オブジェクトの型を判定し、適切なS3メソッドにディスパッチする
2. 列名の検証と必要に応じた自動修復を行う
3. 行名の処理（保持または破棄）を行う
4. tbl_dfクラスを持つtibbleオブジェクトを構築して返す

**関連システム・外部連携**：as_tibbleはtibbleパッケージで定義され、dplyrパッケージを通じて再エクスポートされる。dplyr内部ではgrouped_df、rowwise_dfの変換メソッドが追加定義されており、グループ化されたデータフレームをプレーンなtibbleに変換する機能が提供される。

**権限による制御**：本機能に権限による制御は適用されない。すべてのユーザーが同一の機能を利用可能である。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | 該当なし | - | 本プロジェクトはRライブラリであり、画面は存在しない |

## 機能種別

型変換 / データ構造変換

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| x | any | Yes | tibbleに変換するオブジェクト（data.frame、リスト、行列、ベクトル等） | as_tibbleメソッドが定義されている型である必要がある |
| ... | 任意 | No | メソッドに渡される追加引数 | メソッドにより異なる |
| .rows | integer | No | tibbleの行数を明示的に指定（リスト変換時） | 非負整数 |
| .name_repair | character/function | No | 列名の修復方法（"check_unique", "unique", "universal", "minimal"、またはカスタム関数） | 有効な修復オプションまたは関数 |
| rownames | character | No | 行名の処理方法（NULL: 破棄、NA: 保持、文字列: 行名を指定列として追加） | NULL、NA、または有効な列名 |

### 入力データソース

Rオブジェクトとして直接渡されるdata.frame、行列、リスト、ベクトル等

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| (返り値) | tbl_df (tibble) | 入力オブジェクトから変換されたtibble。クラスは c("tbl_df", "tbl", "data.frame") |

### 出力先

関数の戻り値として呼び出し元に返される

## 処理フロー

### 処理シーケンス

```
1. 入力オブジェクトの型判定
   └─ S3メソッドディスパッチにより適切なメソッドを選択
2. 型別の変換処理
   └─ data.frame: 属性の再構築
   └─ matrix: 列への分解とdata.frame化
   └─ list: 各要素を列として構築
   └─ grouped_df/rowwise_df: グループ情報の除去
3. 行名の処理
   └─ rownamesパラメータに基づいて処理
4. 列名の検証と修復
   └─ .name_repair引数に基づいて列名を処理
5. tibbleオブジェクトの構築
   └─ new_tibbleを使用してオブジェクトを生成
6. 結果の返却
```

### フローチャート

```mermaid
flowchart TD
    A[開始: as_tibble関数呼び出し] --> B{入力オブジェクトの型?}
    B -->|data.frame| C[data.frame用メソッド]
    B -->|matrix| D[matrix用メソッド]
    B -->|list| E[list用メソッド]
    B -->|grouped_df| F[grouped_df用メソッド]
    B -->|rowwise_df| G[rowwise_df用メソッド]
    B -->|その他| H[デフォルトメソッド]
    C --> I[行名の処理]
    D --> I
    E --> I
    F --> I
    G --> I
    H --> I
    I --> J[列名の検証]
    J --> K{列名に問題あり?}
    K -->|Yes| L[.name_repairで修復]
    K -->|No| M[tibble構築]
    L --> M
    M --> N[終了: tibbleを返却]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-82-01 | 型別ディスパッチ | 入力オブジェクトの型に応じて適切な変換メソッドが自動選択される | 常時適用 |
| BR-82-02 | 行名処理 | デフォルトでは行名は破棄される。rownames引数で保持や列への変換が可能 | 行名を持つオブジェクトの変換時 |
| BR-82-03 | グループ情報除去 | grouped_dfやrowwise_dfからas_tibbleで変換するとグループ情報が除去される | grouped_df/rowwise_dfの変換時 |
| BR-82-04 | 列名一意性 | デフォルトでは列名は一意である必要がある | .name_repair = "check_unique" (デフォルト) |

### 計算ロジック

特別な計算ロジックは存在しない。型変換のみを行う。

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

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

本機能はデータベース操作を行わない。メモリ内での型変換のみを実行する。

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| - | - | - | データベース操作なし |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | error_column_names_must_be_unique | 重複した列名が存在する | 一意な列名を使用するか、.name_repair引数を設定する |
| - | error_incompatible_type | as_tibbleメソッドが定義されていない型が入力された | 変換可能な型を使用する |
| - | error_must_be_a_tibble | rowwise_dfのgroup_dataがtibbleでない | 正しい形式のオブジェクトを使用する |

### リトライ仕様

本機能はステートレスな処理であり、リトライ機構は不要である。

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

本機能はデータベーストランザクションを使用しない。

## パフォーマンス要件

- as_tibbleの変換処理は軽量であり、通常はミリ秒単位で完了する
- 大規模なdata.frameの変換でも、メモリコピーは最小限に抑えられる
- grouped_dfからの変換時は、グループ情報の除去のみで元データのコピーは発生しない

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

- 入力データの内容はそのまま出力に反映される
- 機密データを含むオブジェクトの変換時も、データ内容の変更は行われない

## 備考

- as_tibbleはtibbleパッケージで定義され、dplyrを通じて再エクスポートされている
- dplyrでは追加でgrouped_dfとrowwise_df用のメソッドが定義されている
- 古い関数as_data_frameとtbl_dfは非推奨となり、as_tibbleへの移行が推奨されている

---

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

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

### 推奨読解順序

#### Step 1: 再エクスポートと基本定義を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | reexport-tibble.R | `R/reexport-tibble.R` | dplyrがtibbleパッケージからas_tibbleをエクスポートする仕組み |
| 1-2 | NAMESPACE | `NAMESPACE` | as_tibbleのエクスポートとS3メソッドの登録 |

**読解のコツ**: NAMESPACEファイルで`S3method(as_tibble, grouped_df)`と`S3method(as_tibble, rowwise_df)`が登録されていることを確認する。これはdplyrがtibbleの基本メソッドに加えて独自のメソッドを追加していることを示す。

**主要処理フロー**:
1. **25-27行目** (`R/reexport-tibble.R`): `@importFrom tibble as_tibble` でtibbleパッケージからインポートし、`tibble::as_tibble`として再エクスポート
2. **21行目** (`NAMESPACE`): `S3method(as_tibble,grouped_df)` でgrouped_df用メソッドを登録
3. **22行目** (`NAMESPACE`): `S3method(as_tibble,rowwise_df)` でrowwise_df用メソッドを登録

#### Step 2: dplyr独自のS3メソッドを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | grouped-df.R | `R/grouped-df.R` | grouped_df用as_tibbleメソッドの実装 |
| 2-2 | rowwise.R | `R/rowwise.R` | rowwise_df用as_tibbleメソッドの実装 |

**主要処理フロー**:
- **216-218行目** (`R/grouped-df.R`): `as_tibble.grouped_df` - グループ情報を除去してプレーンなtibbleを返す
  ```r
  as_tibble.grouped_df <- function(x, ...) {
    new_tibble(vec_data(x), nrow = nrow(x))
  }
  ```
- **144-146行目** (`R/rowwise.R`): `as_tibble.rowwise_df` - 行単位グループ情報を除去してtibbleを返す
  ```r
  as_tibble.rowwise_df <- function(x, ...) {
    new_tibble(vec_data(x), nrow = nrow(x))
  }
  ```

**読解のコツ**: 両メソッドとも`vec_data(x)`を使用して属性を除去し、`new_tibble`で新しいtibbleを構築している。これによりグループ化情報が完全に除去される。

#### Step 3: dplyr内部でのas_tibble使用パターンを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | join.R | `R/join.R` | join操作でのas_tibble使用 |
| 3-2 | bind-rows.R | `R/bind-rows.R` | bind_rowsでのas_tibble使用 |
| 3-3 | bind-cols.R | `R/bind-cols.R` | bind_colsでのas_tibble使用 |

**主要処理フロー**:
- **632-633行目** (`R/join.R`): join操作の入力を`as_tibble(x, .name_repair = "minimal")`で標準化
- **50行目** (`R/bind-rows.R`): 単一要素の場合`return(as_tibble(dots))`
- **45行目** (`R/bind-cols.R`): 結果を`out <- as_tibble(out)`でtibble化

#### Step 4: グループ化解除のユースケースを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | group-by.R | `R/group-by.R` | ungroup処理でのas_tibble使用 |
| 4-2 | group-split.R | `R/group-split.R` | ドキュメントでの推奨パターン |

**主要処理フロー**:
- **167行目** (`R/group-by.R`): グループ変数が空の場合`as_tibble(x)`を返す
- **185行目** (`R/group-by.R`): data.frameのungroup時に`as_tibble(x)`
- **85行目** (`R/group-split.R`): エラーメッセージで`as_tibble() |> group_split(...)`パターンを推奨

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

```
dplyr::as_tibble (再エクスポート + 追加メソッド)
    │
    ├─ tibble::as_tibble (tibbleパッケージの基本実装)
    │      │
    │      ├─ as_tibble.data.frame
    │      ├─ as_tibble.matrix
    │      ├─ as_tibble.list
    │      └─ as_tibble.default
    │
    ├─ as_tibble.grouped_df (dplyr独自)
    │      └─ new_tibble(vec_data(x), nrow = nrow(x))
    │
    └─ as_tibble.rowwise_df (dplyr独自)
           └─ new_tibble(vec_data(x), nrow = nrow(x))
```

### データフロー図

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

data.frame            ┌────────────────────┐
matrix           ────▶│   S3ディスパッチ    │
list                  └─────────┬──────────┘
grouped_df                      │
rowwise_df                      ▼
                     ┌────────────────────┐
                     │   型別変換処理     │
                     │  (属性除去等)      │
                     └─────────┬──────────┘
                               │
                     ┌─────────▼──────────┐
                     │   行名/列名処理    │
                     └─────────┬──────────┘
                               │
                     ┌─────────▼──────────┐           tibble
                     │    new_tibble     │─────────▶ (tbl_df)
                     └────────────────────┘
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| reexport-tibble.R | `R/reexport-tibble.R` | ソース | tibbleパッケージ関数の再エクスポート定義 |
| NAMESPACE | `NAMESPACE` | 設定 | S3メソッドの登録とエクスポート宣言 |
| grouped-df.R | `R/grouped-df.R` | ソース | grouped_df用as_tibbleメソッド |
| rowwise.R | `R/rowwise.R` | ソース | rowwise_df用as_tibbleメソッド |
| join.R | `R/join.R` | ソース | join操作でのas_tibble使用例 |
| bind-rows.R | `R/bind-rows.R` | ソース | bind_rowsでのas_tibble使用例 |
| bind-cols.R | `R/bind-cols.R` | ソース | bind_colsでのas_tibble使用例 |
| group-by.R | `R/group-by.R` | ソース | グループ解除でのas_tibble使用例 |
| defunct.R | `R/defunct.R` | ソース | 非推奨関数からas_tibbleへの移行メッセージ |
