# 機能設計書 66-n

## 概要

本ドキュメントは、dplyrパッケージの`n`関数の機能設計について記述する。`n`は現在のグループのサイズ（行数）を取得するコンテキスト関数である。

### 本機能の処理概要

`n`関数は、`summarise()`、`mutate()`などのデータマスク動詞内で呼び出され、現在処理中のグループに含まれる行数を返す。グループ化されていないデータフレームの場合は、全体の行数を返す。

**業務上の目的・背景**：データ分析において、各グループのサイズを取得することは非常に一般的な操作である。例えば、カテゴリごとの件数カウント、グループサイズに基づく重み付け、グループサイズによるフィルタリングなどに使用される。`n()`は、これらの操作を直感的に記述できるようにするコンテキスト関数である。

**機能の利用シーン**：
- `summarise()`内でグループの行数をカウントする場合
- `mutate()`内でグループサイズを新しい列として追加する場合
- `filter()`内でグループサイズに基づいてフィルタリングする場合
- グループごとの統計量の計算（例：平均の信頼区間）

**主要な処理内容**：
1. 現在のデータマスクコンテキストを取得（`peek_mask()`）
2. マスクから現在のグループサイズを取得（`get_current_group_size()`）
3. グループサイズ（整数）を返す

**関連システム・外部連携**：DataMaskオブジェクトに依存している。

**権限による制御**：特に権限による制御は行われない。

## 関連画面

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

## 機能種別

コンテキスト関数 / 情報取得

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| (なし) | - | - | パラメータなし | - |

### 入力データソース

現在のデータマスクコンテキスト（`peek_mask()`経由で取得）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| result | integer | 現在のグループの行数 |

### 出力先

関数の戻り値として返却

## 処理フロー

### 処理シーケンス

```
1. データマスクの取得
   └─ peek_mask(): 現在のコンテキストからDataMaskを取得

2. グループサイズの取得
   └─ mask$get_current_group_size(): 現在のグループの行数を取得

3. 結果の返却
   └─ 整数値を返す
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{データマスク内?}
    B -->|Yes| C[peek_mask]
    B -->|No| D[エラー]
    C --> E[get_current_group_size]
    E --> F[整数値返却]
    F --> G[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-66-01 | コンテキスト制限 | データマスク動詞内でのみ使用可能 | 常時 |
| BR-66-02 | グループサイズ | グループ化されている場合は各グループの行数を返す | グループ化時 |
| BR-66-03 | 全体サイズ | グループ化されていない場合は全体の行数を返す | 非グループ化時 |

### 計算ロジック

```
n()の動作:
- グループ化されている場合: 現在のグループの行数
- グループ化されていない場合: データフレーム全体の行数
- rowwise()の場合: 常に1（各行が1グループ）

例:
  df |> group_by(g) |> summarise(count = n())
  # 各グループgの行数がcount列に格納される
```

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

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

該当なし（本関数はデータベース操作を行わない）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | コンテキストエラー | データマスク動詞外で呼び出された場合 | mutate()やsummarise()内で呼び出す |

### リトライ仕様

該当なし

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

該当なし（本関数はトランザクション処理を行わない）

## パフォーマンス要件

グループサイズは事前計算されており、O(1)で取得可能。

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

特になし

## 備考

- data.tableの`.N`に相当する機能
- `count()`は`group_by() |> summarise(n = n())`と同等
- `tally()`も同様の機能を提供

---

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

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

### 推奨読解順序

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

本関数はDataMaskオブジェクトに依存しているため、その構造を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | context.R | `R/context.R` | n関数定義（50-52行目） |
| 1-2 | data-mask.R | `R/data-mask.R` | DataMaskクラス（get_current_group_size） |

**読解のコツ**: `peek_mask()`で現在のDataMaskコンテキストを取得し、そのメソッドを呼び出す構造。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | context.R | `R/context.R` | `n`関数本体（50-52行目） |

**主要処理フロー**:
1. **51行目**: `peek_mask()$get_current_group_size()` - 唯一の処理行

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | data-mask.R | `R/data-mask.R` | get_current_group_size メソッド（203-206行目） |
| 3-2 | context.R | `R/context.R` | peek_mask関数（171-177行目） |

**主要ポイント**:
- **data-mask.R 203-206行目**: `duplicate()`でサイズを複製して返す
- **context.R 171-177行目**: コンテキスト環境からマスクを取得

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

```
n()
    │
    └─ peek_mask()                      [context.R]
           │
           └─ context_peek("mask")      [context.R]
                  │
                  └─ DataMask$get_current_group_size()  [data-mask.R]
                         │
                         └─ duplicate(current_group_size)
```

### データフロー図

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

(コンテキスト) ──▶ peek_mask() ──▶ DataMask ──▶ get_current_group_size() ──▶ 整数
                                      │
                                      ▼
                           env_current_group_info
                           ["dplyr:::current_group_size"]
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| context.R | `R/context.R` | ソース | n関数およびその他のコンテキスト関数 |
| data-mask.R | `R/data-mask.R` | ソース | DataMaskクラスの実装 |
| test-context.R | `tests/testthat/test-context.R` | テスト | コンテキスト関数のユニットテスト |
