# 通知設計書 21-count() wt = n() 非推奨

## 概要

本ドキュメントは、dplyrパッケージの `count()` および `tally()` 関数において `wt = n()` という引数指定が非推奨となったことに関する通知の設計書です。

### 本通知の処理概要

この通知は、`count()` や `tally()` 関数で `wt = n()` を指定した場合に発生する非推奨警告の処理内容を定義します。

**業務上の目的・背景**：dplyr 1.0.0で `wt` 引数の挙動が変更され、`wt = n()` は冗長な指定となりました。これは、`wt` 引数を省略した場合のデフォルト動作が既に行数をカウントする（`n()` を使用する）ためです。この非推奨警告により、開発者に対してコードの簡素化と最新のAPIへの移行を促しています。

**通知の送信タイミング**：ユーザーが `count(wt = n())` または `tally(wt = n())` という形式で関数を呼び出した際に、即座に警告が発生します。これは関数実行時のランタイムチェックとして動作します。

**通知の受信者**：dplyrパッケージを使用するRユーザー（データサイエンティスト、統計分析者、Rプログラマー）が対象です。特に、dplyr 1.0.0以前のコードを使用している開発者に向けた通知です。

**通知内容の概要**：警告メッセージとして「`wt = n()` の使用は非推奨であり、`wt` 引数を省略できるようになった」という内容が表示されます。

**期待されるアクション**：受信者は `wt = n()` の指定を削除し、単に `count()` または `tally()` として呼び出すことが期待されます。これにより、コードがより簡潔になり、将来のバージョンでの互換性が維持されます。

## 通知種別

コンソール警告（lifecycle::deprecate_warn）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（関数実行時即時） |
| 優先度 | 中 |
| リトライ | 無 |

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

Rセッション内で `count()` または `tally()` を呼び出したユーザーに対して、コンソールを通じて警告メッセージが表示されます。この警告は `lifecycle` パッケージの `deprecate_warn()` 関数により管理され、同一セッション内では1度のみ表示される設計（`always = TRUE` により毎回表示）になっています。

## 通知テンプレート

### コンソール警告の場合

| 項目 | 内容 |
|-----|------|
| 送信元 | dplyrパッケージ |
| 送信元名称 | lifecycle::deprecate_warn |
| 形式 | テキスト |

### 本文テンプレート

```
Using `wt = n()` was deprecated in dplyr 1.0.1.
i You can now omit the `wt` argument.
```

### 添付ファイル

該当なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| when | 非推奨となったバージョン | ハードコード値 "1.0.1" | Yes |
| what | 非推奨となった機能 | ハードコード値 "`wt = n()`" | Yes |
| details | 追加情報 | ハードコード値 "You can now omit the `wt` argument." | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| 関数呼び出し | `count(wt = n())` または `tally(wt = n())` | `wt` 引数が `n()` 関数呼び出し（引数なし）である | compat_wt関数内でquosureの内容をチェック |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| `wt` が `n()` 以外の場合 | 正当な重み付けカウントとして処理される |
| `wt` が NULL の場合 | デフォルト動作として処理される |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[count/tally関数呼び出し] --> B[compat_wt関数でwt引数チェック]
    B --> C{wt がn()関数呼び出しか?}
    C -->|Yes| D[is_call検査: n, n=0]
    C -->|No| E[通常処理継続]
    D --> F[lifecycle::deprecate_warn発行]
    F --> G[wt = quo(NULL)に変換]
    G --> H[処理継続]
    E --> H
```

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

### 参照テーブル一覧

該当なし（インメモリ処理のみ）

### 更新テーブル一覧

該当なし

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| 該当なし | この通知は警告のみで、エラーは発生しない | - |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 0（リトライなし） |
| リトライ間隔 | - |
| リトライ対象エラー | - |

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| セッションあたり | 無制限（always = TRUE により毎回表示） |

### 配信時間帯

制限なし（関数呼び出し時に即時発行）

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

特になし。本通知はユーザーコンソールへの警告表示のみで、個人情報やセキュリティに関わるデータは含まれません。

## 備考

- この非推奨警告は dplyr 1.0.1 で導入されました
- `id = "dplyr-count-wt"` により警告が識別されます
- 将来のバージョンでは `wt = n()` の指定が完全に削除される可能性があります

---

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

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

### 推奨読解順序

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

まず、`wt` 引数がどのように処理されるかを理解することが重要です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | count-tally.R | `R/count-tally.R` | quosureとしての`wt`引数の扱いを理解する |

**読解のコツ**: Rのrlangパッケージの`enquo()`、`quo_get_expr()`、`is_call()`の理解が必要です。

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

処理の起点となる関数を特定します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | count-tally.R | `R/count-tally.R` | `count()` および `tally()` 関数のS3メソッドディスパッチを理解する |

**主要処理フロー**:
1. **行83-85**: `count()` ジェネリック関数の定義
2. **行89-112**: `count.data.frame()` メソッドの実装
3. **行105**: `compat_wt(enquo(wt))` の呼び出し

#### Step 3: 非推奨チェックロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | count-tally.R | `R/count-tally.R` | `compat_wt()` 関数の実装詳細 |

**主要処理フロー**:
- **行245-262**: `compat_wt()` 関数の完全な実装
- **行246-248**: `is_call(quo_get_expr(wt), "n", n = 0)` による `n()` 呼び出しの検出
- **行251-259**: `lifecycle::deprecate_warn()` による警告発行
- **行261**: `quo(NULL)` を返して `wt` 引数を無効化

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

```
count() / tally()
    │
    └─ count.data.frame() / tally.data.frame()
           │
           ├─ enquo(wt) - wt引数をquosureに変換
           │
           └─ compat_wt(wt)
                  │
                  ├─ is_call(quo_get_expr(wt), "n", n = 0)
                  │      └─ TRUE: n()呼び出しを検出
                  │
                  ├─ lifecycle::deprecate_warn()
                  │      └─ 非推奨警告を発行
                  │
                  └─ quo(NULL) を返却
```

### データフロー図

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

wt = n() ───▶ enquo(wt) ───▶ compat_wt() ───▶ 警告メッセージ
                                   │
                                   └─▶ quo(NULL)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| count-tally.R | `R/count-tally.R` | ソース | count/tally関数と非推奨チェックの実装 |
| lifecycle | 外部パッケージ | 依存関係 | deprecate_warn関数の提供 |
