# 機能設計書 76-starwars

## 概要

本ドキュメントは、dplyrパッケージの`starwars`データセットに関する機能設計書です。`starwars`は、Star Warsシリーズのキャラクター情報を含むサンプルデータセットです。

### 本機能の処理概要

`starwars`データセットは、Star Wars API（SWAPI）から取得したキャラクター情報を基にしたtibbleです。データ分析やdplyr関数のデモンストレーションに使用される代表的なサンプルデータです。

**業務上の目的・背景**：データ分析ツールの学習や機能のデモンストレーションには、適切なサンプルデータが必要です。`starwars`データセットは、多様なデータ型（数値、文字列、リスト列）、欠損値、カテゴリカル変数を含み、dplyrの様々な機能を実演するのに適した構造を持っています。また、Star Warsという広く知られた題材を使用することで、データの意味が直感的に理解しやすくなっています。

**機能の利用シーン**：
- dplyr関数の学習・教育用途
- データ操作のデモンストレーション
- フィルタリング、グループ化、集計のテスト
- リスト列を含むデータの操作練習
- ドキュメントやvignetteでの例示

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

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

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

## 関連画面

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

## 機能種別

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

## 入力仕様

### 入力パラメータ

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

### 入力データソース

パッケージ内に格納された`.rda`ファイルから読み込まれます。元データはStar Wars API（SWAPI）から取得されました。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| name | character | キャラクター名 |
| height | integer | 身長（cm） |
| mass | double | 体重（kg） |
| hair_color | character | 髪の色 |
| skin_color | character | 肌の色 |
| eye_color | character | 目の色 |
| birth_year | double | 生年（BBY = Battle of Yavin以前） |
| sex | character | 生物学的性別（male/female/hermaphroditic/none） |
| gender | character | 性別アイデンティティ（masculine/feminine） |
| homeworld | character | 出身惑星名 |
| species | character | 種族名 |
| films | list | 出演映画のリスト |
| vehicles | list | 操縦した乗り物のリスト |
| starships | list | 操縦した宇宙船のリスト |

### 出力先

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

## 処理フロー

### 処理シーケンス

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

### フローチャート

```mermaid
flowchart TD
    A[library dplyr] --> B[lazy loading]
    B --> C[starwars tibble 利用可能]
    C --> D{使用方法}
    D -->|直接参照| E[starwars]
    D -->|パイプ処理| F[starwars %>% filter...]
    D -->|dplyr関数の引数| G[select starwars, name]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-76-01 | 読み取り専用 | データセットは変更不可（コピーして使用） | 常時 |
| BR-76-02 | tibble形式 | data.frameではなくtibbleとして提供 | 常時 |
| BR-76-03 | リスト列含有 | films/vehicles/starshipsはリスト列 | 常時 |
| BR-76-04 | 欠損値含有 | 一部の列にNA値が存在 | 常時 |

### 計算ロジック

計算ロジックはありません。静的なデータセットです。

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

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

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

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

## エラー処理

### エラーケース一覧

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

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

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

## パフォーマンス要件

- 87行14列の小規模データセット
- 即座に読み込み可能

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

特別なセキュリティ考慮事項はありません。公開されているStar Warsの情報を基にしています。

## 備考

- データはStar Wars API（SWAPI: https://swapi.py4e.com/）から取得
- 性別（sex/gender）情報は追加調査に基づいて修正されています
- Droidは生物学的性別がなく（none）、プログラムされた性別アイデンティティを持ちます
- 87キャラクター、14変数を含みます

---

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

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

### 推奨読解順序

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

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

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

**読解のコツ**: Rのドキュメント形式（roxygen2）を理解しておくと、各列の説明が読みやすくなります。

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

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

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

**主要処理フロー**:
1. **4-18行目**: get_all()関数でSWAPIから全データを取得
2. **20-21行目**: people APIからキャラクター情報を取得
3. **25-39行目**: 関連情報（species, films, planets等）のルックアップテーブルを作成
4. **41-70行目**: tibbleとしてデータを構成
5. **83-103行目**: 性別情報（sex/gender）の追加・修正
6. **133行目**: usethis::use_data()でパッケージに保存

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

```
data-raw/starwars.R (データ生成時のみ)
    │
    ├─ get_all(url) [data-raw/starwars.R:4-18]
    │      └─ httr::GET()でAPIを呼び出し
    │
    ├─ lookup(url, name) [data-raw/starwars.R:25-33]
    │      └─ 各種関連情報のルックアップテーブル作成
    │
    └─ tibble(...) [tibble]
           └─ データフレームを構成

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

### データフロー図

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

SWAPI API ────────────▶ get_all()
                            │
                            ▼
                       people データ
                            │
                            ▼
species/films/        lookup() で
planets/etc API ─────▶ ルックアップテーブル作成
                            │
                            ▼
                       tibble()で構成
                            │
                            ▼
                       性別情報の追加
                            │
                            ▼
                       usethis::use_data()
                            │
                            ▼
                       data/starwars.rda

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

library(dplyr) ─────▶ lazy loading
                            │
                            ▼
                       starwars tibble
                            │
                            ▼
                       ユーザーの分析
```

### 関連ファイル一覧

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