# 機能設計書 77-storms

## 概要

本ドキュメントは、dplyrパッケージの`storms`データセットに関する機能設計書です。`storms`は、NOAAの大西洋ハリケーンデータベースから取得した嵐の追跡データを含むサンプルデータセットです。

### 本機能の処理概要

`storms`データセットは、NOAA（アメリカ海洋大気庁）のAtlantic hurricane database best track dataを基にしたtibbleです。1975年以降の熱帯暴風雨やハリケーンの位置と属性情報を含みます。

**業務上の目的・背景**：時系列データや地理データの分析を学習・デモンストレーションするには、適切なサンプルデータが必要です。`storms`データセットは、時間的・空間的な変動を持つ実世界のデータであり、グループ化操作（年、嵐の名前など）、時系列分析、可視化などの学習に適しています。

**機能の利用シーン**：
- 時系列データ分析の学習
- グループ化操作（group_by）のデモンストレーション
- 地理データの可視化練習
- ファクタ変数（status）の操作練習
- 集計・要約処理のテスト

**主要な処理内容**：
1. パッケージ読み込み時にデータセットがlazyloadingされる
2. `storms`と入力するとtibbleがコンソールに表示される
3. 分析やデータ操作の対象として使用される

**関連システム・外部連携**：データの元となったNOAAのHURDATデータベースは外部サービスですが、データセット自体はパッケージに同梱されているため、実行時の外部連携はありません。

**権限による制御**：特になし。dplyrをロードすれば誰でもアクセス可能です。

## 関連画面

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

## 機能種別

サンプルデータセット / 教育用データ

## 入力仕様

### 入力パラメータ

データセットであるため、入力パラメータはありません。

### 入力データソース

パッケージ内に格納された`.rda`ファイルから読み込まれます。元データはNOAAのHURDAT2データベースから取得されました。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| name | character | 嵐の名前 |
| year | double | 年 |
| month | double | 月 |
| day | integer | 日 |
| hour | double | 時刻（UTC） |
| lat | double | 緯度 |
| long | double | 経度 |
| status | factor | 嵐の分類（hurricane/tropical storm/tropical depression等） |
| category | double | Saffir-Simpsonハリケーンカテゴリ（1-5、非ハリケーンはNA） |
| wind | integer | 最大持続風速（ノット） |
| pressure | integer | 中心気圧（ミリバール） |
| tropicalstorm_force_diameter | integer | 熱帯暴風雨強度風域の直径（海里）、2004年以降 |
| hurricane_force_diameter | integer | ハリケーン強度風域の直径（海里）、2004年以降 |

### 出力先

R環境内のオブジェクトとして参照されます。

## 処理フロー

### 処理シーケンス

```
1. dplyrパッケージのロード
   └─ library(dplyr)またはdplyr::storms
2. データセットのlazy loading
   └─ .rdaファイルからデータが読み込まれる
3. tibbleとして利用可能
   └─ 数万行13列のtibble
```

### フローチャート

```mermaid
flowchart TD
    A[library dplyr] --> B[lazy loading]
    B --> C[storms tibble 利用可能]
    C --> D{使用方法}
    D -->|直接参照| E[storms]
    D -->|パイプ処理| F[storms %>% filter...]
    D -->|可視化| G[ggplot storms...]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-77-01 | 読み取り専用 | データセットは変更不可（コピーして使用） | 常時 |
| BR-77-02 | tibble形式 | data.frameではなくtibbleとして提供 | 常時 |
| BR-77-03 | 1975年以降 | 1975年以降のデータのみ含む | 常時 |
| BR-77-04 | status因子 | statusはfactor型で9種類の値を持つ | 常時 |
| BR-77-05 | カテゴリ条件 | categoryはハリケーンのみに値があり、それ以外はNA | 常時 |

### 計算ロジック

データ生成時の計算ロジック：
- **カテゴリ分類**: 風速に基づいてSaffir-Simpsonスケールで分類
  - Category 1: 64+ knots
  - Category 2: 83+ knots
  - Category 3: 96+ knots
  - Category 4: 113+ knots
  - Category 5: 137+ knots

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

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

本機能はデータベースを操作しません。

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| - | - | - | メモリ内データのみ |

## エラー処理

### エラーケース一覧

エラーケースはありません。パッケージに同梱されたデータセットです。

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

トランザクション管理はありません。

## パフォーマンス要件

- 数万行13列のデータセット
- lazy loadingにより初回アクセス時のみ読み込み

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

特別なセキュリティ考慮事項はありません。公開されている気象データを基にしています。

## 備考

- データはNOAA HURDAT2データベース（https://www.nhc.noaa.gov/data/#hurdat）から取得
- 1979年以降は6時間ごとの測定、それ以前は一部欠損あり
- statusの値: hurricane, tropical storm, tropical depression, extratropical, subtropical depression, subtropical storm, other low, tropical wave, disturbance
- tropicalstorm_force_diameterとhurricane_force_diameterは2004年以降のみ利用可能

---

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

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

### 推奨読解順序

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

データセットの構造と各列の意味を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | data-storms.R | `R/data-storms.R` | データセットのドキュメント |

**読解のコツ**: 気象データ特有の用語（knots、millibars、Saffir-Simpsonスケール等）を理解しておくとデータの意味が把握しやすくなります。

#### Step 2: データ生成スクリプトを理解する

データがどのように生成されたかを理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | storms.R | `data-raw/storms.R` | データ生成スクリプト |

**主要処理フロー**:
1. **10-13行目**: HURDAT2ファイルをダウンロード
2. **16-27行目**: ヘッダー行の識別と解析
3. **54-78行目**: 各嵐のデータをパース
4. **91-111行目**: 日付・座標・風域の計算
5. **118-132行目**: status（嵐の分類）のリコーディング
6. **135-147行目**: ハリケーンカテゴリの計算
7. **176-194行目**: 列の選択と最終整形
8. **201行目**: usethis::use_data()でパッケージに保存

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

```
data-raw/storms.R (データ生成時のみ)
    │
    ├─ read_file() / read_lines() [readr]
    │      └─ HURDATファイルを読み込み
    │
    ├─ str_count() / str_sub() [stringr]
    │      └─ ヘッダー行の識別
    │
    ├─ read_csv() [readr]
    │      └─ 各嵐のデータをパース
    │
    ├─ bind_rows() [dplyr]
    │      └─ 全嵐のデータを結合
    │
    ├─ mutate() + recode() [dplyr]
    │      └─ status、categoryの計算
    │
    └─ usethis::use_data()
           └─ パッケージに保存

R/data-storms.R (パッケージ使用時)
    │
    └─ ドキュメントのみ（"storms"文字列を定義）
```

### データフロー図

```
[データ生成フロー]

NOAA HURDAT2 ────────▶ read_file() / read_lines()
                            │
                            ▼
                       storm_strings
                            │
                            ▼
                       ヘッダー行を識別
                            │
                            ▼
                       各嵐をread_csv()でパース
                            │
                            ▼
                       bind_rows()で結合
                            │
                            ▼
                       mutate()で列を計算
                       (date, lat, long, status, category等)
                            │
                            ▼
                       filter()でデータをクリーン
                            │
                            ▼
                       usethis::use_data()
                            │
                            ▼
                       data/storms.rda

[パッケージ使用フロー]

library(dplyr) ─────▶ lazy loading
                            │
                            ▼
                       storms tibble
                            │
                            ▼
                       ユーザーの分析・可視化
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| data-storms.R | `R/data-storms.R` | ソース | データセットのドキュメント |
| storms.R | `data-raw/storms.R` | データ生成 | HURDATからデータを取得・加工 |
| storms.csv | `data-raw/storms.csv` | データ | diffに便利なCSV形式 |
| storms.rda | `data/storms.rda` | データ | パッケージに同梱されるバイナリ |
| storms.Rd | `man/storms.Rd` | ドキュメント | ヘルプファイル |
