# バッチ設計書 3-storms.R

## 概要

本ドキュメントは、NOAA（米国海洋大気庁）のAtlantic Hurricaneデータベースから嵐データを取得し、stormsサンプルデータセットを生成してdplyrパッケージのdataディレクトリに保存するバッチ処理の設計書である。

### 本バッチの処理概要

このバッチは、NOAAのHURDAT2（Hurricane Database 2）フォーマットで提供されるAtlantic basin tropical stormデータを取得し、複雑なデータ変換処理を行った上で、dplyrパッケージで利用可能なサンプルデータセットとして保存する処理を行う。

**業務上の目的・背景**：dplyrパッケージでは、時系列データやグループ化処理の例示に適したリアルワールドデータセットが必要である。stormsデータセットは、1975年以降のAtlantic basinにおける熱帯性暴風雨・ハリケーンの追跡データを含み、group_by()、filter()、summarise()等の関数のデモンストレーションに最適である。また、気象データという実用的なコンテキストにより、ユーザーの学習意欲を高める効果がある。

**バッチの実行タイミング**：パッケージ開発時の手動実行。NOAAがHURDAT2データを更新した場合（通常は年次更新）に実行される。データファイルのURLは年度により変更されるため、実行時にURLの更新が必要な場合がある。

**主要な処理内容**：
1. tidyverse、lubridateライブラリの読み込み
2. NOAAのHURDAT2テキストファイルをダウンロード
3. メタデータ行とデータ行を分離してパース
4. 各嵐ごとにサブデータフレームを作成
5. 日付・時刻・座標のフォーマット変換
6. 嵐のステータスコードを人間可読な名称に変換
7. Saffir-Simpsonスケールによるハリケーンカテゴリの算出
8. 熱帯性暴風雨以上の記録のみをフィルタ
9. 不正データの除去とタイトルケース化
10. CSV形式での保存とパッケージデータとしての保存

**前後の処理との関連**：前提となるバッチは存在しない。本バッチの出力は、パッケージのビルド時にdata/ディレクトリに含まれ、パッケージ利用者がdata(storms)で読み込み可能となる。

**影響範囲**：dplyrパッケージのdata/storms.rdaファイルおよびdata-raw/storms.csvファイルが更新される。stormsデータセットはパッケージの公開APIの一部であり、年次更新によりレコード数が増加する。

## バッチ種別

データ生成（外部データ連携）

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（NOAAデータ更新時） |
| 実行時刻 | N/A |
| 実行曜日 | N/A |
| 実行日 | N/A |
| トリガー | 手動（開発者による実行） |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| tidyverseパッケージ | tidyverseがインストールされていること |
| lubridateパッケージ | lubridateがインストールされていること |
| usethisパッケージ | usethisがインストールされていること |
| ネットワーク接続 | www.nhc.noaa.govへのアクセスが可能であること |
| Rプロジェクト構成 | dplyrパッケージのルートディレクトリで実行すること |

### 実行可否判定

手動実行のため、開発者の判断により実行。NOAAのHURDAT2データが更新されていることを確認後に実行する。URLの確認はhttps://www.nhc.noaa.gov/data/#hurdat で行う。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| なし | - | - | - | 本バッチは入力パラメータを受け取らない |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| www.nhc.noaa.gov/data/hurdat/hurdat2-*.txt | TEXT/CSV | HURDAT2形式の嵐データ |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| data/storms.rda | R binary | 嵐データセット |
| data-raw/storms.csv | CSV | diff確認用テキストファイル |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | storms.rda, storms.csv |
| 出力先 | data/, data-raw/ |
| 文字コード | UTF-8（CSV） |
| 区切り文字 | カンマ（CSV） |

#### stormsデータセット構造

| カラム名 | 型 | 説明 |
|---------|-----|------|
| name | character | 嵐の名前 |
| year | integer | 年 |
| month | integer | 月 |
| day | integer | 日 |
| hour | numeric | 時（0-23） |
| lat | numeric | 緯度 |
| long | numeric | 経度（西経は負の値） |
| status | factor | 嵐のステータス（hurricane, tropical storm等） |
| category | integer | ハリケーンカテゴリ（1-5、NULLの場合あり） |
| wind | integer | 最大持続風速（ノット） |
| pressure | integer | 中心気圧（ミリバール） |
| tropicalstorm_force_diameter | integer | 熱帯性暴風雨レベルの風の直径（海里） |
| hurricane_force_diameter | integer | ハリケーンレベルの風の直径（海里） |

## 処理フロー

### 処理シーケンス

```
1. ライブラリの読み込み
   └─ tidyverse, lubridateをロード
2. HURDAT2データファイルのダウンロード
   └─ read_file()でURLからテキスト取得
3. ヘッダー行の特定
   └─ カンマが3つの行をヘッダーとして識別
4. メタデータの抽出
   └─ id, name, n_obs, skipをheaders_dfとして構築
5. 各嵐のデータをパース
   └─ forループで各嵐をサブデータフレームとして読み込み
6. 全嵐データの結合
   └─ bind_rows()で単一データフレームに結合
7. 日付・時刻カラムの変換
   └─ ymd(), year(), month(), day()等で分解
8. 座標の変換
   └─ 緯度・経度を数値に変換、半球記号を符号に変換
9. 風速直径の計算
   └─ tropicalstorm_force_diameter, hurricane_force_diameterを算出
10. 欠損気圧データの除外
    └─ filter(!is.na(pressure))
11. ステータスコードの変換
    └─ HU→hurricane, TS→tropical storm等にrecode
12. ハリケーンカテゴリの算出
    └─ Saffir-Simpsonスケールに基づきcategoryを設定
13. 熱帯性以上の嵐のみを保持
    └─ 少なくとも1レコードがTD以上の嵐のみ残す
14. 名前のタイトルケース化
    └─ str_to_title()で変換（AL0*形式は除外）
15. 不正データの除去
    └─ 1969年Debbieの異常経度データを除去
16. 1975年以降に限定・カラム選択
    └─ filter(year >= 1975), select()で13カラムに絞り込み
17. CSV形式で保存
    └─ data-raw/storms.csvに出力
18. パッケージデータとして保存
    └─ usethis::use_data()でdata/storms.rdaに出力
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B[ライブラリ読み込み]
    B --> C[HURDAT2ファイルダウンロード]
    C --> D[ヘッダー行特定・メタデータ抽出]
    D --> E[各嵐データをパース]
    E --> F[全嵐データを結合]
    F --> G[日付・座標変換]
    G --> H[風速直径計算]
    H --> I[欠損データ除外]
    I --> J[ステータス・カテゴリ変換]
    J --> K[フィルタリング・名前変換]
    K --> L[1975年以降に限定]
    L --> M[CSV保存]
    M --> N[RDAファイル保存]
    N --> O[バッチ終了]
```

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

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

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| N/A | N/A | N/A | 本バッチはデータベースを使用しない |

### テーブル別操作詳細

本バッチはファイルシステムへの出力のみを行い、データベースは使用しない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ダウンロードエラー | NOAAサーバーへの接続失敗 | ネットワーク確認後再実行 |
| - | パースエラー | HURDAT2フォーマット変更 | スクリプトを更新 |
| - | URL変更 | 年度更新によりURLが変更 | 最新URLをスクリプトに反映 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | なし（手動実行） |
| リトライ間隔 | N/A |
| リトライ対象エラー | N/A |

### 障害時対応

エラー発生時は、エラーメッセージを確認し、NOAAサイトでデータファイルのURLを確認後、スクリプトを更新して再実行する。

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | なし（ファイル出力） |
| コミットタイミング | write_csv(), use_data()呼び出し時 |
| ロールバック条件 | なし |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 数万レコード（1975年以降の全嵐データ） |
| 目標処理時間 | 数十秒〜数分 |
| メモリ使用量上限 | 数十MB |

## 排他制御

同時実行の制御は行わない。開発者が手動で実行するため、同時実行は想定されない。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 警告ログ | パース時 | problems()による警告表示 |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| N/A | N/A | N/A（手動実行バッチのため監視なし） |

## 備考

- このスクリプトは開発時のデータセット生成用であり、通常のパッケージ利用時には実行されない
- NOAAのHURDAT2データは通常年次で更新される
- データファイルのURLは`https://www.nhc.noaa.gov/data/#hurdat`で確認可能
- 1975年以降のデータに限定しているのは、後方互換性の維持とファイルサイズの最適化のため
- statusカラムはfactor型であり、9種類のステータス（hurricane, tropical storm, tropical depression, extratropical, subtropical depression, subtropical storm, other low, tropical wave, disturbance）を含む
- categoryカラムはSaffir-Simpsonスケールに基づき、風速64ノット以上のハリケーンに対して1-5の値を設定
