# 機能設計書 81-tibble

## 概要

本ドキュメントは、dplyrパッケージが再エクスポートするtibble関数の機能設計を記述する。tibbleは従来のdata.frameを改良したデータ構造を作成する関数であり、tidyverseエコシステムの中核をなすデータ操作の基盤である。

### 本機能の処理概要

tibble関数は、Rにおけるdata.frameの改良版であるtibbleオブジェクトを作成する機能を提供する。tibbleはdata.frameと後方互換性を持ちながら、より現代的で使いやすいデータフレーム構造を実現している。

**業務上の目的・背景**：従来のdata.frameには、文字列を自動的にfactorに変換する、部分一致で列名を補完する、行数が1の場合にベクトルに変換されるなど、予期しない挙動が多数存在していた。tibbleはこれらの問題を解決し、データ分析ワークフローにおける予測可能性と安全性を向上させることを目的としている。tidyverseの全パッケージがtibbleを標準的なデータ構造として採用しており、dplyr操作の入出力として一貫性のあるデータハンドリングを可能にする。

**機能の利用シーン**：新規データセットの作成時、スクリプト内でのサンプルデータ定義時、関数の戻り値としてデータフレームを返す際、既存データの変換結果を格納する際など、あらゆるデータ操作の起点として利用される。特にdplyrのパイプライン処理において、tibbleは最も頻繁に使用されるデータ構造である。

**主要な処理内容**：
1. 引数として渡された名前付きベクトルまたはリストから列を構築する
2. リサイクル規則に基づいて異なる長さのベクトルを調整する
3. 列名の検証と必要に応じた自動修復を行う
4. tbl_dfクラスを持つデータフレームオブジェクトを返す

**関連システム・外部連携**：tibbleはtibbleパッケージで定義され、dplyrパッケージを通じて再エクスポートされる。pillarパッケージと連携して整形された出力を提供し、vctrsパッケージのベクトル型システムと統合されている。

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

## 関連画面

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

## 機能種別

データ構造作成 / オブジェクト生成

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| ... | 名前付き引数 | No | 列として追加するベクトルまたは値。名前が列名となる | 各ベクトルの長さは1またはリサイクル可能な長さである必要がある |
| .rows | integer | No | 作成するtibbleの行数を明示的に指定 | 非負整数である必要がある |
| .name_repair | character/function | No | 列名の修復方法を指定（"check_unique", "unique", "universal", "minimal"、またはカスタム関数） | 有効な修復オプションまたは関数 |

### 入力データソース

引数として直接渡されるRオブジェクト（ベクトル、リスト、NULL等）

## 出力仕様

### 出力データ

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

### 出力先

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

## 処理フロー

### 処理シーケンス

```
1. 引数の受け取りと解析
   └─ ...引数を名前付きリストとして収集
2. 各引数の評価
   └─ 遅延評価により、前の列を参照する式も評価可能
3. ベクトル長の検証とリサイクル
   └─ 長さ1のベクトルは行数に合わせてリサイクル
4. 列名の検証と修復
   └─ .name_repair引数に基づいて列名を処理
5. tibbleオブジェクトの構築
   └─ vctrsを使用してデータフレームを構築
6. 結果の返却
   └─ tbl_dfクラスを持つオブジェクトを返す
```

### フローチャート

```mermaid
flowchart TD
    A[開始: tibble関数呼び出し] --> B[引数を名前付きリストとして収集]
    B --> C[各引数を順次評価]
    C --> D{すべての引数を評価完了?}
    D -->|No| C
    D -->|Yes| E[ベクトル長の検証]
    E --> F{長さが互換性あり?}
    F -->|No| G[エラー: 互換性のない長さ]
    F -->|Yes| H[リサイクル処理]
    H --> I[列名の検証]
    I --> J{列名に問題あり?}
    J -->|Yes| K[.name_repairに基づき修復]
    J -->|No| L[tibbleオブジェクト構築]
    K --> L
    L --> M[tbl_dfクラスを設定]
    M --> N[終了: tibbleを返却]
    G --> O[終了: エラー]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-81-01 | リサイクル規則 | 長さ1のベクトルは他の列の長さに合わせてリサイクルされる | 異なる長さのベクトルが入力された場合 |
| BR-81-02 | 遅延評価 | 列定義は左から右へ順次評価され、前の列を参照可能 | 式中で他の列名を参照する場合 |
| BR-81-03 | 列名一意性 | デフォルトでは列名は一意である必要がある | .name_repair = "check_unique" (デフォルト) |
| BR-81-04 | 文字列保持 | 文字列は自動的にfactorに変換されない | 常時適用 |

### 計算ロジック

リサイクル規則：
- 長さ1のベクトルは、最長ベクトルの長さに合わせて繰り返される
- 長さ0以外で長さ1でもないベクトルは、すべて同じ長さである必要がある
- .rows引数が指定された場合、その値が目標行数となる

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

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

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | tibble_error_incompatible_size | リサイクル不可能な異なる長さのベクトルが指定された | ベクトルの長さを揃えるか、長さ1に調整する |
| - | tibble_error_column_names_must_be_unique | 重複した列名が存在する | 一意な列名を使用するか、.name_repair引数を設定する |
| - | tibble_error_column_must_be_vector | 列として無効な型が指定された | ベクトル型のオブジェクトを使用する |

### リトライ仕様

本機能はステートレスな処理であり、リトライ機構は不要である。エラー発生時は入力を修正して再実行する。

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

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

## パフォーマンス要件

- tibbleの作成は軽量な操作であり、通常はミリ秒単位で完了する
- 大量の行（数百万行以上）を持つtibbleを作成する場合でも、data.frameと同等のパフォーマンスを維持する

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

- tibble関数は入力データをそのまま格納するため、機密データを含むtibbleの取り扱いには注意が必要
- tibbleの内容はRコンソールに表示される可能性があるため、機密情報を含む列の表示制御を検討する

## 備考

- tibbleはtibbleパッケージで定義され、dplyrを通じて再エクスポートされている
- dplyrの多くの関数（filter, select, mutate等）の出力は自動的にtibble形式となる
- data.frameとの主な違い：部分一致無効、文字列のfactor自動変換無効、行名非推奨、表示の改善

---

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

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

### 推奨読解順序

#### Step 1: 再エクスポートの仕組みを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | reexport-tibble.R | `R/reexport-tibble.R` | dplyrがtibbleパッケージから関数をエクスポートする仕組み |
| 1-2 | NAMESPACE | `NAMESPACE` | エクスポートとインポートの宣言 |

**読解のコツ**: Rの再エクスポートは `@importFrom` と `@export` ディレクティブを組み合わせて実現する。`tibble::tibble` という記法は、tibbleパッケージのtibble関数をそのままエクスポートすることを意味する。

**主要処理フロー**:
1. **21-23行目** (`R/reexport-tibble.R`): `@importFrom tibble tibble` でtibbleパッケージからインポート
2. **22行目**: `@export` でdplyrのエクスポート対象として登録
3. **23行目**: `tibble::tibble` でtibbleパッケージの関数をそのまま再エクスポート

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | utils.R | `R/utils.R` | dplyr内部で使用される高速tibble作成ユーティリティ |
| 2-2 | grouped-df.R | `R/grouped-df.R` | grouped_dfでのtibble使用例 |

**主要処理フロー**:
- **52-55行目** (`R/utils.R`): `dplyr_new_tibble` 関数はtibble::new_tibble()の約9倍高速な内部用tibble作成関数
- **27行目** (`R/grouped-df.R`): グループ化変数が空の場合に`as_tibble(data)`を返す
- **42行目** (`R/grouped-df.R`): グループ変数の抽出で`as_tibble(data)[vars]`を使用
- **49行目** (`R/grouped-df.R`): グループ情報の保存に`tibble(!!!old_keys, ".rows" := old_rows)`を使用

#### Step 3: テストケースからユースケースを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | test-select.R | `tests/testthat/test-select.R` | tibbleの一般的な使用パターン |
| 3-2 | test-distinct.R | `tests/testthat/test-distinct.R` | tibbleを使ったテストケースの書き方 |

**主要処理フロー**:
- **2行目** (`tests/testthat/test-select.R`): `tibble(g = 1:3, x = 3:1)` - 基本的なtibble作成
- **68行目** (`tests/testthat/test-select.R`): `.name_repair = "minimal"` オプションの使用例

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

```
dplyr::tibble (再エクスポート)
    │
    └─ tibble::tibble (tibbleパッケージの実装)
           │
           ├─ tibble::tibble_quos() - 引数の準クォート処理
           │
           ├─ vctrs::vec_recycle_common() - リサイクル処理
           │
           └─ tibble::new_tibble() - オブジェクト構築
                  │
                  └─ vctrs::new_data_frame() - 基盤データフレーム作成
```

### データフロー図

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

名前付き引数         ┌─────────────────────┐
(x = 1:3,    ───────▶│   引数解析・評価    │
 y = "a")            └──────────┬──────────┘
                               │
                     ┌─────────▼──────────┐
                     │  リサイクル処理    │
                     └──────────┬─────────┘
                               │
                     ┌─────────▼──────────┐
                     │   列名検証/修復    │
                     └──────────┬─────────┘
                               │
                     ┌─────────▼──────────┐         tibble
                     │   tibble構築      │────────▶ (tbl_df)
                     └────────────────────┘
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| reexport-tibble.R | `R/reexport-tibble.R` | ソース | tibbleパッケージ関数の再エクスポート定義 |
| NAMESPACE | `NAMESPACE` | 設定 | パッケージのエクスポート/インポート宣言 |
| DESCRIPTION | `DESCRIPTION` | 設定 | tibbleパッケージへの依存関係定義 |
| utils.R | `R/utils.R` | ソース | dplyr内部用tibbleユーティリティ関数 |
| grouped-df.R | `R/grouped-df.R` | ソース | grouped_dfでのtibble使用例 |
| test-select.R | `tests/testthat/test-select.R` | テスト | tibbleを使用したテストケース |
| test-distinct.R | `tests/testthat/test-distinct.R` | テスト | tibbleを使用したテストケース |
