# 機能設計書 53-min_rank

## 概要

本ドキュメントは、dplyrパッケージにおける`min_rank()`関数の機能設計を定義する。`min_rank()`は同順位に同じ最小ランク値を付与するランキング関数である。

### 本機能の処理概要

**業務上の目的・背景**：スポーツの順位付けや試験の成績ランキングなど、同点・同スコアの場合に同じ順位を与え、次の順位に「ギャップ」を設ける形式のランキングは一般的な要件である。例えば、3人が同点1位の場合、次の人は4位となる（2位、3位はスキップ）。`min_rank()`は、このような「スポーツ形式」のランキングを実現するために設計された。

**機能の利用シーン**：競技の順位付け、試験成績のランキング、売上高による企業ランキング、同率順位を許容する各種ランキング処理に利用される。特にタイがあった場合に次の順位にギャップが生じることを期待する場合に有用である。

**主要な処理内容**：
1. 入力ベクトルの値を昇順で評価し、各値にランクを付与する
2. 同じ値（タイ）がある場合、すべてに同じ最小ランク値を付与する
3. 次の異なる値のランクは、前のグループの人数分だけスキップされる
4. 欠損値（NA）はランクNAとして扱われる

**関連システム・外部連携**：vctrsパッケージの`vec_rank()`関数を`ties = "min"`オプションで使用する。

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

## 関連画面

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

## 機能種別

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

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| x | vector / data.frame | Yes | ランク付けする対象ベクトルまたはデータフレーム | 順序付け可能な型であること |

### 入力データソース

Rのベクトルまたはデータフレーム。`mutate()`や`filter()`内で使用される場合は、現在処理中のグループのデータが対象となる。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| result | integer | 整数のランクベクトル。同じ値には同じランクが付与され、次の値にはギャップがある |

### 出力先

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

## 処理フロー

### 処理シーケンス

```
1. 入力ベクトル x を受け取る
2. vec_rank(x, ties = "min", incomplete = "na") を呼び出し
   └─ 値を昇順でソート
   └─ 同じ値には同じランク（グループ内最小値）を付与
   └─ 次の異なる値のランクは位置ベース
3. 整数ベクトルとして結果を返却
```

### フローチャート

```mermaid
flowchart TD
    A[開始: min_rank] --> B[vec_rank を呼び出し]
    B --> C["ties='min', incomplete='na'"]
    C --> D[同じ値に同じ最小ランクを付与]
    D --> E[ギャップを含むランクベクトル生成]
    E --> F[整数ベクトルを返却]
    F --> G[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-53-01 | 同順位処理 | 同じ値にはすべて同じランクを付与 | タイ存在時 |
| BR-53-02 | 最小ランク使用 | タイの場合、そのグループの最小ランク値を使用 | タイ存在時 |
| BR-53-03 | ギャップ生成 | 次の異なる値は位置ベースのランクとなりギャップが生じる | タイ後 |
| BR-53-04 | NA処理 | 欠損値にはNAランクを付与 | NA存在時 |
| BR-53-05 | 昇順ランク | 最小値にランク1を付与 | 常に適用 |

### 計算ロジック

- `min_rank(x)`: `rank(x, ties.method = "min")` と等価
- 例: `c(10, 20, 20, 30)` → `c(1, 2, 2, 4)`
  - 10は1位
  - 20が2つあり、どちらも2位
  - 30は4位（2位が2人いたので3位はスキップ）

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

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

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 型エラー | 順序付けできない型の入力 | 順序付け可能な型を使用する |

### リトライ仕様

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

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

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

## パフォーマンス要件

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

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

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

## 備考

- スポーツの順位付け方式と同様の動作
- `row_number()`と異なり、タイに同じランクを付与
- `dense_rank()`と異なり、ギャップが生じる
- SQLの`RANK()`ウィンドウ関数に相当

---

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

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

### 推奨読解順序

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

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

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

**読解のコツ**: ドキュメント内の例 `c(10, 20, 20, 30)` → `c(1, 2, 2, 4)` でタイ処理とギャップを理解できる。

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

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

**主要処理フロー**:
1. **69行目**: `min_rank(x)`関数のシグネチャ
2. **70行目**: `vec_rank(x, ties = "min", incomplete = "na")` を呼び出し
3. タイには最小ランク値を使用（ties = "min"）

#### Step 3: 他のランキング関数との比較

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | rank.R | `R/rank.R` | 11-17行目の説明でrow_number/min_rank/dense_rankの違いを理解 |

**主要処理フロー**:
- 11-13行目: `min_rank()`はタイに同じ値を与え、ギャップが生じる
- 例との対比で3つの関数の違いを明確に把握できる

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

```
min_rank(x)
    │
    └─ vec_rank(x, ties = "min", incomplete = "na")
           │
           └─ [vctrsパッケージ内部処理]
                  ├─ ソート処理
                  ├─ タイ検出
                  └─ 最小ランク割り当て
```

### データフロー図

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

x = [10,20,20,30] ───▶  min_rank(x)                ───▶  [1, 2, 2, 4]
                         │                                (ギャップあり)
                         └─▶ vec_rank(ties="min")
                               ├─ 10 → ランク1
                               ├─ 20 → ランク2（2つとも）
                               └─ 30 → ランク4（3はスキップ）
```

### 関連ファイル一覧

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