# 機能設計書 71-cur_data

## 概要

本ドキュメントは、dplyrパッケージの`cur_data()`関数に関する機能設計書です。`cur_data()`は、グループ化されたデータフレームに対する操作（mutate、summarise等）の内部で、現在処理中のグループのデータ（グループ化キーを除く）を取得するための関数です。

### 本機能の処理概要

`cur_data()`関数は、dplyrのグループ操作中に現在のグループのデータをtibbleとして取得するためのコンテキスト関数です。

**業務上の目的・背景**：データ分析において、グループごとに異なる処理を行う際に、現在処理中のグループデータ全体にアクセスする必要が生じることがあります。例えば、グループ内のデータを別の関数に渡して複雑な計算を行う場合や、グループのデータ構造を動的に確認する必要がある場合に有用です。ただし、dplyr 1.1.0以降では非推奨となり、`pick()`関数への移行が推奨されています。

**機能の利用シーン**：
- グループごとに複雑なモデルを適用する場合
- グループデータを別のデータ処理関数に渡す場合
- デバッグ目的でグループ内のデータを確認する場合
- グループ内のデータ構造に基づいた動的な処理を行う場合

**主要な処理内容**：
1. DataMaskオブジェクトから現在のグループ情報を取得
2. グループ化キーを除いた列を特定
3. 現在のグループに属するデータをtibbleとして返却
4. 非推奨警告を発行（dplyr 1.1.0以降）

**関連システム・外部連携**：本機能はdplyr内部のDataMaskシステムと連携し、グループ操作のコンテキスト内でのみ動作します。外部システムとの連携はありません。

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

## 関連画面

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

## 機能種別

コンテキスト情報取得 / データ抽出

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| なし | - | - | 引数なしの関数 | - |

### 入力データソース

DataMask内部環境から取得。`mutate()`、`summarise()`、`filter()`等のdplyr動詞の実行コンテキスト内でのみ有効です。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | tibble | 現在のグループのデータ（グループ化キーを除く列を含む） |

### 出力先

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

## 処理フロー

### 処理シーケンス

```
1. 非推奨警告の発行
   └─ lifecycle::deprecate_warn()で"1.1.0"以降の非推奨であることを通知
2. DataMaskオブジェクトの取得
   └─ peek_mask()でカレントマスクを取得
3. 非グループ変数の特定
   └─ mask$current_non_group_vars()でグループキー以外の変数名を取得
4. データの抽出と返却
   └─ mask$pick_current(vars)で現在のグループデータをtibbleとして返却
```

### フローチャート

```mermaid
flowchart TD
    A[cur_data呼び出し] --> B[非推奨警告を発行]
    B --> C[peek_mask でDataMaskを取得]
    C --> D[current_non_group_vars で非グループ列を取得]
    D --> E[pick_current でデータを抽出]
    E --> F[tibbleとして返却]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-71-01 | コンテキスト必須 | dplyr動詞の実行コンテキスト内でのみ使用可能 | 常時 |
| BR-71-02 | グループキー除外 | 返却データにはグループ化キーが含まれない | グループ化されたデータに対して |
| BR-71-03 | 非推奨警告 | dplyr 1.1.0以降では非推奨警告を発行 | 常時 |
| BR-71-04 | rowwise対応 | rowwise_dfの場合、リスト列の扱いが特別 | rowwiseデータに対して |

### 計算ロジック

特別な計算ロジックはありません。DataMaskの内部状態から現在のグループデータを抽出するのみです。

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

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

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | エラー | dplyr動詞コンテキスト外での呼び出し | mutate/summarise等の内部で使用する |

### リトライ仕様

リトライ機構はありません。エラー時は即座に例外をスローします。

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

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

## パフォーマンス要件

- グループごとにデータコピーが発生するため、大規模データでは注意が必要
- pick()への移行が推奨される理由の一つはパフォーマンス改善

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

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

## 備考

- dplyr 1.1.0で非推奨となり、`pick()`への移行が推奨されています
- `cur_data_all()`との違いは、グループ化キーを含むかどうかです
- rowwiseデータフレームでの使用時は、リスト列がリストとして保持されます

---

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

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

### 推奨読解順序

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

まず、DataMaskクラスの構造を理解することが重要です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | data-mask.R | `R/data-mask.R` | DataMaskクラスの定義、privateメンバーの役割を理解 |

**読解のコツ**: R6クラスの記法を理解しておくことが重要です。`private`と`public`のメンバーの違い、`self`による自己参照に注目してください。

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

処理の起点となるファイル・関数を特定します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | deprec-context.R | `R/deprec-context.R` | cur_data関数の定義、非推奨警告の発行方法 |

**主要処理フロー**:
1. **19-29行目**: cur_data関数の定義。非推奨警告を発行し、peek_mask()でDataMaskを取得
2. **26-28行目**: current_non_group_vars()でグループキー以外の変数を取得し、pick_current()でデータを抽出

#### Step 3: DataMaskの内部処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | data-mask.R | `R/data-mask.R` | pick_current、current_non_group_vars、current_varsメソッドの実装 |

**主要処理フロー**:
- **134-149行目**: pick_current()メソッド - 指定された変数のデータを取得しtibbleを作成
- **151-153行目**: current_cols()メソッド - 環境からカラムデータを取得
- **172-174行目**: current_vars()メソッド - 現在のデータの変数名を取得
- **176-178行目**: current_non_group_vars()メソッド - グループキーを除いた変数名を取得

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

```
cur_data() [R/deprec-context.R:19-29]
    │
    ├─ lifecycle::deprecate_warn() [外部パッケージ]
    │      └─ 非推奨警告を発行
    │
    ├─ peek_mask() [内部関数]
    │      └─ 現在のDataMaskオブジェクトを取得
    │
    ├─ mask$current_non_group_vars() [R/data-mask.R:176-178]
    │      └─ mask$current_vars() [R/data-mask.R:172-174]
    │             └─ private$by_names を除外
    │
    └─ mask$pick_current(vars) [R/data-mask.R:134-149]
           ├─ self$current_cols(vars) [R/data-mask.R:151-153]
           └─ dplyr_new_tibble() [内部関数]
```

### データフロー図

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

DataMask             peek_mask()
(内部環境) ─────────▶ ─────────────▶ mask オブジェクト
                          │
                          ▼
                     current_non_group_vars()
                          │
                          ▼
                     pick_current(vars)
                          │
                          ▼
                     current_cols(vars)
                          │
                          ▼
                     dplyr_new_tibble() ──────▶ tibble
                                               (グループデータ)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| deprec-context.R | `R/deprec-context.R` | ソース | cur_data/cur_data_all関数の定義 |
| data-mask.R | `R/data-mask.R` | ソース | DataMaskクラスの実装 |
| test-deprec-context.R | `tests/testthat/test-deprec-context.R` | テスト | cur_data/cur_data_allのテストケース |
