# 機能設計書 52-row_number

## 概要

本ドキュメントは、dplyrパッケージにおける`row_number()`関数の機能設計を定義する。`row_number()`は各入力に一意のランクを付与するランキング関数である。

### 本機能の処理概要

**業務上の目的・背景**：データ分析において、各レコードに連番を振ったり、値の順位を計算することは頻繁に発生するタスクである。例えば、顧客ごとの購買履歴に時系列の番号を振る、成績順にランク付けする、グループ内で上位N件を抽出するなどの処理が該当する。`row_number()`は、同じ値（タイ）があっても必ず一意の番号を付与するため、重複のない行識別子が必要な場面で特に有用である。

**機能の利用シーン**：グループ内での連番付与、タイがあっても一意のランク付けが必要な場合、フィルタリングで各グループの先頭/末尾N行を抽出する場合、SQLの`ROW_NUMBER()`ウィンドウ関数と同等の処理が必要な場合に利用される。

**主要な処理内容**：
1. 引数なしで呼び出された場合、現在のグループ内で1から始まる連番を返す
2. 引数としてベクトルが渡された場合、値の昇順でランクを計算する
3. 同じ値（タイ）がある場合でも、出現順に異なる番号を付与する（ties.method = "first"相当）
4. 欠損値（NA）はランクNAとして扱われる

**関連システム・外部連携**：vctrsパッケージの`vec_rank()`関数を内部で使用する。`n()`コンテキスト関数と組み合わせて使用される。

**権限による制御**：本関数に権限による実行制御は存在しない。

## 関連画面

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

## 機能種別

計算処理 / ランキング関数

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| x | vector / data.frame | No | ランク付けする対象ベクトルまたはデータフレーム。省略時は行番号を返す | - |

### 入力データソース

Rのベクトル、データフレーム、または省略（グループコンテキストから行数を取得）。`mutate()`や`filter()`内で使用される場合は、現在処理中のグループのデータが対象となる。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| result | integer | 整数のランクベクトル。各要素は1から始まる一意のランク値 |

### 出力先

関数の戻り値として返却される。通常は`mutate()`や`filter()`の結果としてデータフレームの列に格納される。

## 処理フロー

### 処理シーケンス

```
1. 引数の有無を確認
   └─ x が省略されている場合
      └─ n() を呼び出してグループサイズを取得
      └─ seq_len(n()) で1からnまでの連番を生成
   └─ x が指定されている場合
      └─ vec_rank(x, ties = "sequential", incomplete = "na") を呼び出し
2. 結果を整数ベクトルとして返却
```

### フローチャート

```mermaid
flowchart TD
    A[開始: row_number] --> B{xが省略されているか}
    B -->|Yes| C[n関数でグループサイズ取得]
    C --> D[seq_len でシーケンス生成]
    B -->|No| E[vec_rank を呼び出し]
    E --> F["ties='sequential', incomplete='na'"]
    D --> G[整数ベクトルを返却]
    F --> G
    G --> H[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-52-01 | 一意性保証 | 同じ値があっても各入力に一意のランクを付与 | 常に適用 |
| BR-52-02 | タイの処理 | タイは出現順に番号付け（ties.method = "first"相当） | x指定時 |
| BR-52-03 | NA処理 | 欠損値にはNAランクを付与 | NA存在時 |
| BR-52-04 | 引数省略時 | グループ内の行番号（1からn）を返す | x省略時 |
| BR-52-05 | 昇順ランク | 最小値にランク1を付与 | 常に適用 |

### 計算ロジック

- `row_number()`（引数なし）: `seq_len(n())` と等価（1, 2, 3, ..., n）
- `row_number(x)`: `rank(x, ties.method = "first")` と等価
- 例: `c(10, 20, 20, 30)` → `c(1, 2, 3, 4)`（同じ20でも異なるランク）

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

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

本関数はインメモリのベクトル操作のみを行い、データベース操作は行わない。

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | コンテキストエラー | グループコンテキスト外で引数なしで呼び出し | mutate/filter内で使用するか、引数を指定する |

### リトライ仕様

リトライは不要（同期的なインメモリ処理）。

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

トランザクション管理は不要（ステートレスな関数型処理）。

## パフォーマンス要件

- 計算量: O(n log n)（ソートベースのランキング）
- メモリ使用量: O(n)（出力ベクトル用）
- vctrsパッケージの最適化されたランキングアルゴリズムを使用

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

特別なセキュリティ考慮事項はない。

## 備考

- SQL2003の`ROW_NUMBER()`ウィンドウ関数に相当
- `min_rank()`や`dense_rank()`とは異なり、常に一意のランクを返す
- データフレームを渡すと複数列でランク付け可能

---

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

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

### 推奨読解順序

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

row_number関数は、vctrsパッケージのvec_rank関数に依存している。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | rank.R | `R/rank.R` | ランキング関数群の定義とドキュメント |

**読解のコツ**: `@family ranking functions`タグで関連するランキング関数（min_rank, dense_rankなど）がグループ化されている。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | rank.R | `R/rank.R` | `row_number()`関数の定義（59-65行目） |

**主要処理フロー**:
1. **59行目**: `row_number(x)`関数のシグネチャ
2. **60行目**: `missing(x)`で引数の有無を確認
3. **61行目**: 引数なしの場合、`seq_len(n())`でシーケンス生成
4. **63行目**: 引数ありの場合、`vec_rank()`でランキング計算

#### Step 3: 関連関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | context.R | `R/context.R` | `n()`関数の実装（グループサイズ取得） |

**主要処理フロー**:
- `n()`はdplyrのコンテキスト関数で、現在のグループの行数を返す
- `mutate()`や`summarise()`内で使用されることを前提としている

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

```
row_number(x)
    │
    ├─ [xが省略] missing(x) == TRUE
    │      │
    │      ├─ n() [グループサイズ取得]
    │      │
    │      └─ seq_len(n()) [シーケンス生成]
    │
    └─ [xが指定] missing(x) == FALSE
           │
           └─ vec_rank(x, ties = "sequential", incomplete = "na")
                  │
                  └─ [vctrsパッケージ内部処理]
```

### データフロー図

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

(引数なし)       ───▶  row_number()                ───▶  [1, 2, 3, ..., n]
                        │
                        └─▶ seq_len(n())

x = [5,1,3,2,2] ───▶  row_number(x)               ───▶  [5, 1, 3, 2, 4]
                        │                                 (タイでも一意)
                        └─▶ vec_rank(x, ties="sequential")
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| rank.R | `R/rank.R` | ソース | row_number/min_rank/dense_rank関数の実装 |
| context.R | `R/context.R` | ソース | n()コンテキスト関数の実装 |
| test-rank.R | `tests/testthat/test-rank.R` | テスト | ランキング関数のユニットテスト |
