# 通知設計書 13-top_n重み変数選択

## 概要

本ドキュメントは、dplyrパッケージの`top_n()`関数において、重み付け変数（`wt`引数）が省略された場合に、デフォルトで使用される変数名を通知する情報メッセージの設計を記載する。

### 本通知の処理概要

`top_n()`関数は、データフレームから上位（または下位）n行を選択する機能を提供する。選択の基準となる重み付け変数は`wt`引数で指定するが、省略された場合はデータフレームの最後の列が自動的に使用される。

**業務上の目的・背景**：`top_n()`はsuperseded（廃止予定）の関数であり、`slice_min()`/`slice_max()`への移行が推奨されている。しかし、既存コードの互換性のために維持されている。`wt`引数のデフォルト動作（最後の列を使用）は直感的でないため、ユーザーにどの変数が使用されるかを明示的に通知することで、予期しない動作を防ぐ。

**通知の送信タイミング**：`top_n()`関数の実行時、`wt`引数が指定されていない（missing）場合に通知が発生する。具体的には、`quo_is_missing(wt)`がTRUEの場合、データフレームの最後の列名を取得し、その変数名を通知する。

**通知の受信者**：R言語のコンソールを使用している開発者・データアナリスト。通知はコンソールに直接出力される。

**通知内容の概要**：「Selecting by {変数名}」という形式で、選択に使用される変数名が表示される。

**期待されるアクション**：ユーザーは通知を確認し、使用される変数が意図したものか確認する。意図しない場合は明示的に`wt`引数を指定する。また、`slice_min()`/`slice_max()`への移行を検討することが推奨される。

## 通知種別

コンソール情報メッセージ（`inform()`による`message`条件）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（関数実行中に即座に表示） |
| 優先度 | 低（情報通知） |
| リトライ | 無し |

### 送信先決定ロジック

R言語の標準メッセージハンドラを通じてコンソールに出力される。`suppressMessages()`で抑制可能。

## 通知テンプレート

### コンソール出力の場合

| 項目 | 内容 |
|-----|------|
| 形式 | テキスト |

### 本文テンプレート

```
Selecting by {変数名}
```

### 添付ファイル

該当なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| wt_name | 選択に使用される変数名 | `vars[length(vars)]`（データフレームの最後の列名） | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| 関数呼び出し | `top_n()`の実行 | `wt`引数が省略されている | `quo_is_missing(wt)`がTRUE |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| `wt`引数が明示的に指定されている場合 | デフォルト変数を使用しないため通知不要 |
| `suppressMessages()`でラップされている場合 | ユーザーが明示的にメッセージを抑制 |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[top_n実行] --> B{wt引数が指定されているか}
    B -->|No| C[tbl_varsで全変数名取得]
    C --> D[最後の変数名を取得]
    D --> E[inform関数で通知]
    E --> F[wtにその変数を設定]
    B -->|Yes| G[指定されたwtを使用]
    F --> H[filter処理を実行]
    G --> H
    H --> I[結果を返す]
```

## データベース参照・更新仕様

### 参照テーブル一覧

| テーブル名 | 用途 | 備考 |
|-----------|------|------|
| 該当なし | - | インメモリデータフレーム操作 |

### テーブル別参照項目詳細

該当なし（データベースは使用しない）

### 更新テーブル一覧

該当なし

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| 該当なし | - | この通知自体はエラーではなく情報提供 |

### リトライ仕様

該当なし

## 配信設定

### レート制限

該当なし（即座に1回表示）

### 配信時間帯

該当なし（関数実行時に即座に表示）

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

変数名情報がコンソールに出力されるため、機密性の高い変数名が含まれる場合は注意が必要。

## 備考

- `top_n()`はsuperseded（廃止予定）であり、`slice_min()`/`slice_max()`の使用が推奨される
- `top_frac()`は内部的に`top_n()`を呼び出すため、同様の通知が発生する
- `lifecycle::signal_stage("superseded", "top_n()")`により、関数自体がsupersededであることも通知される

---

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

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

### 推奨読解順序

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

top_n()はデータフレームの列を重み付け変数として使用し、上位/下位n行を選択する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | top-n.R | `R/top-n.R` | 1-40行目のドキュメントでtop_n()の概要とsuperseded状態を理解 |

**読解のコツ**: `slice_min()`/`slice_max()`との対応関係を意識すると理解しやすい。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | top-n.R | `R/top-n.R` | 41-52行目の`top_n()`関数 |

**主要処理フロー**:
1. **42行目**: `lifecycle::signal_stage("superseded", "top_n()")`でsuperseded通知
2. **43行目**: `wt <- enquo(wt)`でwt引数をquosureに変換
3. **44-49行目**: wt引数が省略された場合のデフォルト処理
4. **51行目**: `filter(x, top_n_rank(...))`で実際のフィルタリング

#### Step 3: 通知ロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | top-n.R | `R/top-n.R` | 44-49行目のwt省略時の処理 |

**主要処理フロー**:
- **44行目**: `quo_is_missing(wt)`でwt引数が省略されているかチェック
- **45行目**: `vars <- tbl_vars(x)`でデータフレームの全変数名を取得
- **46行目**: `wt_name <- vars[length(vars)]`で最後の変数名を取得
- **47行目**: `inform(glue("Selecting by ", wt_name))`で通知
- **48行目**: `wt <- sym(wt_name)`でwtにシンボルを設定

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | top-n.R | `R/top-n.R` | 54-60行目の`top_n_rank()`ヘルパー関数 |
| 4-2 | top-n.R | `R/top-n.R` | 64-66行目の`top_frac()`関数 |

**主要処理フロー**:
- **54-60行目**: `top_n_rank()`は正負のnに応じて`min_rank(desc(wt))`または`min_rank(wt)`を使用
- **65行目**: `top_frac()`は`top_n(x, n * n(), wt)`を呼び出し

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

```
top_n(x, n, wt)
    │
    ├─ lifecycle::signal_stage()        # superseded通知
    │
    ├─ enquo(wt)                         # wt引数のquosure化
    │
    ├─ quo_is_missing(wt)               # wt省略チェック
    │      │
    │      └─ [wt省略時]
    │             ├─ tbl_vars(x)          # 変数名取得
    │             ├─ inform()             # 通知(本通知)
    │             │     └─ glue()
    │             └─ sym()                # シンボル生成
    │
    └─ filter(x, top_n_rank(...))        # 実際のフィルタリング
           └─ top_n_rank()
                  └─ min_rank()
                  └─ desc()
```

### データフロー図

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

x (data.frame) ───┐
                  │
n (numeric) ──────┼──▶ top_n() ──▶ 結果(data.frame)
                  │         │
wt (省略時) ──────┘         │
                            ├─▶ tbl_vars()で変数名取得
                            │
                            └─▶ 最後の変数名を取得
                                     │
                                     ▼
                           [コンソール通知]
                           "Selecting by {変数名}"
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| top-n.R | `R/top-n.R` | ソース | top_n(), top_frac(), top_n_rank()の実装 |
| slice.R | `R/slice.R` | ソース | 推奨される代替関数slice_min(), slice_max()の実装 |
| filter.R | `R/filter.R` | ソース | top_n()内部で使用されるfilter()の実装 |
