# 機能設計書 60-cummean

## 概要

本ドキュメントは、dplyrパッケージにおける`cummean()`関数の機能設計を定義する。`cummean()`は累積平均（実行時平均）を計算する累積関数である。

### 本機能の処理概要

**業務上の目的・背景**：時系列データ分析において、各時点までのデータの平均値（実行時平均、移動平均）を計算することは頻繁に発生する要件である。例えば、株価の累積平均、売上の月次累積平均、センサーデータの平滑化などが該当する。`cummean()`は、このような累積的な平均計算を効率的に実現するために設計された。

**機能の利用シーン**：実行時平均の計算、データの平滑化、トレンド分析、移動平均との比較、時系列データの要約などに利用される。

**主要な処理内容**：
1. 入力数値ベクトルを先頭から順に処理する
2. 各位置iにおいて、位置1からiまでの要素の平均を計算する
3. 内部的には累積和を要素数で除算して実現する
4. 結果は`cumsum(x) / seq_along(x)`と等価である

**関連システム・外部連携**：C++で実装された`dplyr_cummean`関数を内部で呼び出す。高速な処理が可能。

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

## 関連画面

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

## 機能種別

計算処理 / 累積数値関数

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| x | numeric/integer | Yes | 累積平均を計算する数値ベクトル | 数値型に変換可能であること |

### 入力データソース

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

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| result | numeric | 入力と同じ長さの数値ベクトル。各位置での累積平均 |

### 出力先

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

## 処理フロー

### 処理シーケンス

```
1. 入力を数値型に変換
   └─ as.numeric(x)
2. C++実装を呼び出し
   └─ .Call(`dplyr_cummean`, ...)
3. 累積平均計算
   └─ 累積和を保持しながら各位置で要素数で除算
4. 結果を返却
```

### フローチャート

```mermaid
flowchart TD
    A[開始: cummean] --> B[as.numeric で型変換]
    B --> C[C++実装呼び出し]
    C --> D[累積和を初期化: sum = 0]
    D --> E{次の要素があるか}
    E -->|Yes| F["sum += x[i]"]
    F --> G["out[i] = sum / (i + 1)"]
    G --> E
    E -->|No| H[結果を返却]
    H --> I[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-60-01 | 累積平均 | 各位置で先頭からその位置までの平均を計算 | 常に適用 |
| BR-60-02 | 等価性 | cumsum(x) / seq_along(x) と等価 | 常に適用 |
| BR-60-03 | 空ベクトル | 空の入力には空の出力 | 空入力時 |
| BR-60-04 | 浮動小数点 | 結果は常にnumeric（double）型 | 常に適用 |

### 計算ロジック

- `cummean(c(1, 3, 5, 2, 2))` → `c(1.0, 2.0, 3.0, 2.75, 2.6)`
  - i=1: 1/1 = 1.0
  - i=2: (1+3)/2 = 2.0
  - i=3: (1+3+5)/3 = 3.0
  - i=4: (1+3+5+2)/4 = 2.75
  - i=5: (1+3+5+2+2)/5 = 2.6
- 等価計算: `cumsum(x) / seq_along(x)`

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

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

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 型エラー | 数値型に変換できない入力 | 数値ベクトルを使用する |

### リトライ仕様

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

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

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

## パフォーマンス要件

- 計算量: O(n)（単一パス処理）
- メモリ使用量: O(n)（出力ベクトル用）
- C++実装により高速処理
- 浮動小数点誤差への対策あり

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

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

## 備考

- Rの標準関数`cumsum()`、`cummax()`、`cummin()`を補完する関数
- `cumsum(x) / seq_along(x)`と等価だが、C++実装によりオーバーフローに強い
- 浮動小数点誤差に関するテスト（test-funs.R）で精度が確認されている

---

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

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

### 推奨読解順序

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

cummean関数は、C++実装を呼び出すシンプルなラッパーである。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | funs.R | `R/funs.R` | cumall/cumany/cummeanのドキュメント（68-106行目） |

**読解のコツ**: ドキュメント内の例（86-90行目）で`cummean(x)`と`cumsum(x) / seq_along(x)`の等価性を確認できる。

#### Step 2: Rラッパーを理解する

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

**主要処理フロー**:
1. **119行目**: `cummean(x)`関数のシグネチャ
2. **120行目**: `.Call(\`dplyr_cummean\`, as.numeric(x))`
   - `as.numeric(x)`: 数値型に変換
   - `.Call()`: C++実装を呼び出し

#### Step 3: C++実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | funs.cpp | `src/funs.cpp` | `dplyr_cummean`関数の定義（80-95行目） |

**主要処理フロー**:
- **80-85行目**: 関数シグネチャと出力ベクトルの確保
- **87行目**: 累積和変数の初期化（`sum = 0.0`）
- **88-91行目**: ループ処理
  - 累積和に加算
  - 要素数で除算して平均を計算

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

```
cummean(x)
    │
    ├─ as.numeric(x) [型変換]
    │
    └─ .Call(`dplyr_cummean`, ...) [C++呼び出し]
           │
           └─ dplyr_cummean() [src/funs.cpp]
                  ├─ sum = 0.0 初期化
                  └─ for each i:
                        ├─ sum += x[i]
                        └─ out[i] = sum / (i + 1)
```

### データフロー図

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

x = [1,3,5,2,2]   ───▶  cummean(x)                 ───▶  [1.0, 2.0, 3.0, 2.75, 2.6]
                         │
                         └─▶ C++実装
                               ├─ i=0: sum=1,  out=1/1=1.0
                               ├─ i=1: sum=4,  out=4/2=2.0
                               ├─ i=2: sum=9,  out=9/3=3.0
                               ├─ i=3: sum=11, out=11/4=2.75
                               └─ i=4: sum=13, out=13/5=2.6
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| funs.R | `R/funs.R` | ソース | cummean関数のRラッパー |
| funs.cpp | `src/funs.cpp` | ソース | cummean関数のC++実装 |
| test-funs.R | `tests/testthat/test-funs.R` | テスト | 累積関数のテスト（111-150行目） |
