# 通知設計書 16-.cols引数名変更通知

## 概要

本ドキュメントは、dplyrパッケージのcolwise関数群（`summarise_at()`, `mutate_at()`, `transmute_at()`）において、非推奨となった`.cols`引数が使用された場合に、`.vars`への名前変更を通知する情報メッセージの設計を記載する。

### 本通知の処理概要

`_at`バリアントの関数では、列選択に使用する引数名が`.cols`から`.vars`に変更された。旧名称の`.cols`引数が使用された場合、新しい名称`.vars`を使用するように通知する。

**業務上の目的・背景**：dplyrのAPI一貫性向上のため、引数名が`.vars`に統一された。古い`.cols`引数を使用しているコードの互換性を維持しつつ、ユーザーに新しい引数名への移行を促す。なお、これらの関数自体がsupersededであり、`across()`の使用が推奨される。

**通知の送信タイミング**：`summarise_at()`, `mutate_at()`, `transmute_at()`が`.cols`引数付きで呼び出された際、`check_dot_cols()`関数内で通知が発生する。

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

**通知内容の概要**：「`.cols` has been renamed and is deprecated, please use `.vars`」という固定メッセージが表示される。

**期待されるアクション**：ユーザーはコードを更新し、`.cols`引数を`.vars`に置き換える。また、`across()`への移行を検討することが推奨される。

## 通知種別

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

## 送信仕様

### 基本情報

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

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

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

## 通知テンプレート

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

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

### 本文テンプレート

```
`.cols` has been renamed and is deprecated, please use `.vars`
```

### 添付ファイル

該当なし

## テンプレート変数

該当なし（固定メッセージ）

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| 関数呼び出し | `summarise_at()`/`mutate_at()`/`transmute_at()`の実行 | `.cols`引数が指定されている | `!is_null(cols)`がTRUE |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| `.cols`引数が指定されていない場合 | 旧引数を使用していないため |
| `suppressMessages()`でラップされている場合 | ユーザーが明示的にメッセージを抑制 |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[summarise_at等の実行] --> B[check_dot_cols呼び出し]
    B --> C{.cols引数がNULLか}
    C -->|Yes| D[.varsをそのまま返す]
    C -->|No| E[inform関数で通知]
    E --> F{.vars引数がmissingか}
    F -->|Yes| G[.colsを返す]
    F -->|No| H[.varsを返す]
    D --> I[処理継続]
    G --> I
    H --> I
```

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

### 参照テーブル一覧

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

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

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

### 更新テーブル一覧

該当なし

## エラー処理

### エラーケース一覧

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

### リトライ仕様

該当なし

## 配信設定

### レート制限

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

### 配信時間帯

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

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

特になし（固定メッセージのみ）。

## 備考

- `.vars`と`.cols`の両方が指定された場合、`.vars`が優先される
- これらの関数はsupersededであり、`across()`の使用が推奨される
- この通知は引数名の変更に関するものであり、`lifecycle::deprecate_warn()`ではなく`inform()`が使用されている

---

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

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

### 推奨読解順序

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

`_at`バリアントは`.vars`引数で列を選択し、選択した列に対して操作を適用する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | colwise-mutate.R | `R/colwise-mutate.R` | 19行目の`.cols`引数のドキュメント |
| 1-2 | colwise.R | `R/colwise.R` | 43-45行目の`.vars`引数のドキュメント |

**読解のコツ**: `.cols`は`.vars`の旧名称であり、同じ機能を持つ。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | colwise-mutate.R | `R/colwise-mutate.R` | 143-156行目の`summarise_at()`関数 |
| 2-2 | colwise-mutate.R | `R/colwise-mutate.R` | 304-318行目の`mutate_at()`関数 |
| 2-3 | colwise-mutate.R | `R/colwise-mutate.R` | 353-367行目の`transmute_at()`関数 |

**主要処理フロー**:
1. **144行目**: `lifecycle::signal_stage("superseded", "summarise_at()")`でsuperseded通知
2. **145行目**: `.vars <- check_dot_cols(.vars, .cols)`で通知（本通知）
3. **146-154行目**: `manip_at()`で操作を構築
4. **155行目**: `summarise(.tbl, !!!funs)`で実行

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | colwise-mutate.R | `R/colwise-mutate.R` | 474-481行目の`check_dot_cols()`ヘルパー関数 |

**主要処理フロー**:
- **475-476行目**: `.cols`がNULLの場合、`.vars`をそのまま返す
- **478行目**: `inform()`で通知を発行
- **479行目**: `.vars`がmissingの場合は`.cols`を、そうでなければ`.vars`を返す

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

```
summarise_at(.tbl, .vars, .funs, ..., .cols)
    │
    ├─ lifecycle::signal_stage()        # superseded通知
    │
    ├─ check_dot_cols()                  # 通知(本通知)
    │      │
    │      ├─ is_null(.cols)             # .cols指定チェック
    │      │
    │      └─ inform()                   # 通知発行
    │
    ├─ manip_at()                        # 操作の構築
    │
    └─ summarise()                       # 実際の集計
```

### データフロー図

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

.tbl (data.frame) ───┐
                     │
.vars (cols選択) ────┤
                     ├──▶ summarise_at() ──▶ 結果(data.frame)
.funs (関数) ────────┤           │
                     │           │
.cols (旧引数) ──────┘           │
                                 ├─▶ check_dot_cols()
                                 │        │
                                 │        ▼
                                 │   [コンソール通知]
                                 │   "`.cols` has been renamed..."
                                 │
                                 └─▶ manip_at()
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| colwise-mutate.R | `R/colwise-mutate.R` | ソース | summarise/mutate/transmute系colwise関数の実装 |
| colwise.R | `R/colwise.R` | ソース | scoped verbsの共通処理とドキュメント |
