# 機能設計書 49-replace_na

## 概要

本ドキュメントは、機能一覧No.49「replace_na」の機能設計について記述する。

**重要な注意**：`replace_na()`関数はdplyrパッケージには実装されていない。この機能はtidyrパッケージで提供されている。dplyrで同等の機能を実現するには、`coalesce()`または`replace_values(x, NA ~ value)`を使用する。

### 本機能の処理概要

`replace_na()`は、ベクトルまたはデータフレーム内の`NA`値を指定した値で置換する関数である。これは`coalesce()`の逆操作に相当する。tidyrパッケージで提供されており、dplyrと組み合わせて使用されることが多い。

**業務上の目的・背景**：データ分析において、欠損値（`NA`）を特定のデフォルト値で埋める必要がある場面は頻繁に発生する。例えば、数値列のNAを0で、文字列列のNAを"unknown"で置換するといったケースである。`replace_na()`はこの操作を簡潔に記述できる。

**機能の利用シーン**：
- 数値計算のためにNAを0に置換する
- 可視化のためにNAをデフォルト値に置換する
- データフレーム内の複数列のNAを一括置換する

**主要な処理内容**：
1. データがベクトルの場合：NA値を指定した置換値で置換する
2. データがデータフレームの場合：各列のNA値を対応する置換値で置換する

**dplyrでの代替手段**：
- `coalesce(x, replacement)` - 単一ベクトルのNA置換
- `replace_values(x, NA ~ replacement)` - より柔軟なNA置換
- `mutate(across(everything(), ~ coalesce(.x, replacement)))` - 複数列のNA置換

**関連システム・外部連携**：tidyrパッケージの機能。

**権限による制御**：特になし。

## 関連画面

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

## 機能種別

データ変換 / 欠損値処理（tidyrパッケージの機能）

## 入力仕様

### 入力パラメータ（tidyr::replace_na）

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| data | any | Yes | ベクトルまたはデータフレーム | ベクトルまたはデータフレームであること |
| replace | any | Yes | 置換値。データフレームの場合は名前付きリスト | dataと互換性のある型であること |

### dplyrでの代替実装

```r
# coalesceを使用（推奨）
x |> coalesce(replacement)

# replace_valuesを使用
x |> replace_values(NA ~ replacement)

# データフレームの複数列に適用
df |> mutate(across(everything(), ~ coalesce(.x, 0)))
```

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| result | any | NA値が置換されたベクトルまたはデータフレーム |

### 出力先

呼び出し元に返される。

## 処理フロー

### 処理シーケンス（coalesceを使用した代替実装）

```
1. 入力の検証
   └─ ベクトルであることを確認
2. coalesce()を呼び出す
   └─ x, replacementを渡す
3. 結果ベクトルを返す
   └─ NA値がreplacementで置換される
```

### フローチャート

```mermaid
flowchart TD
    A[開始: NA置換が必要] --> B{dplyrのみ使用?}
    B -->|Yes| C[coalesce または replace_values を使用]
    B -->|No| D[tidyr::replace_na を使用]
    C --> E[coalesce x, replacement]
    D --> F[tidyr::replace_na data, replace]
    E --> G[NA値が置換されたベクトル]
    F --> G
    G --> H[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-49-01 | dplyr非実装 | この機能はdplyrには実装されていない。tidyrまたはdplyrの代替関数を使用する | 常に適用 |
| BR-49-02 | coalesce代替 | 単一ベクトルのNA置換にはcoalesce()を使用可能 | 単一ベクトルの場合 |
| BR-49-03 | replace_values代替 | より柔軟なNA置換にはreplace_values()を使用可能 | 条件付き置換の場合 |

### 計算ロジック（coalesceを使用）

```
coalesce(x, replacement)
# 各位置iについて：
#   if is.na(x[i]):
#     result[i] = replacement
#   else:
#     result[i] = x[i]
```

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| - | - | - | 本関数はインメモリ操作のみでデータベース操作を行わない |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 関数未定義 | dplyrでreplace_na()を呼び出した場合 | tidyrをロードするか、coalesce()を使用する |

### リトライ仕様

リトライは不要

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

該当なし（インメモリ操作のみ）

## パフォーマンス要件

- coalesce()またはreplace_values()の効率的な実装を活用すること

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

特になし

## 備考

- **dplyrには実装されていない**：tidyrパッケージの機能
- dplyrのみで同等の機能を実現するには`coalesce()`または`replace_values()`を使用
- `coalesce(x, 0)`は`replace_na(x, 0)`と同等
- `replace_values(x, NA ~ 0)`も同等の機能を提供

---

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

本機能はdplyrには実装されていないため、代替となるdplyr関数のコードを参照する。

### 推奨読解順序

#### Step 1: coalesce()を理解する

`coalesce()`は`replace_na()`の代替として使用できる。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | coalesce.R | `R/coalesce.R` | `coalesce()`関数の実装を理解する |

**読解のコツ**: `coalesce(x, replacement)`は、`x`のNA値を`replacement`で置換する。これは`replace_na(x, replacement)`と同等である。

#### Step 2: replace_values()を理解する

`replace_values()`はより柔軟なNA置換を提供する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | recode-values.R | `R/recode-values.R` | `replace_values()`関数の実装を理解する |

**読解のコツ**: `replace_values(x, NA ~ replacement)`は、NA値を指定した値で置換する。条件に基づく柔軟な置換が可能。

### プログラム呼び出し階層図（coalesceを使用）

```
coalesce(x, replacement) [replace_naの代替]
    │
    ├─ vec_ptype_common() [共通型決定]
    │
    ├─ vec_cast_common() [共通型にキャスト]
    │
    └─ vec_case_when() [最初の非欠損値を選択]
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| coalesce.R | `R/coalesce.R` | ソース | `coalesce()`関数（replace_naの代替） |
| recode-values.R | `R/recode-values.R` | ソース | `replace_values()`関数（replace_naの代替） |
| na-if.R | `R/na-if.R` | ソース | `na_if()`関数（逆操作） |
