# 機能設計書 80-glimpse

## 概要

本ドキュメントは、dplyrパッケージの`glimpse()`関数に関する機能設計書です。`glimpse()`は、データフレームの概要を表示するための関数で、`str()`の改良版として位置づけられています。

### 本機能の処理概要

`glimpse()`関数は、データフレームの列を行方向に表示し、各列のデータをできるだけ多く横方向に表示します。これにより、データフレームの全列を一目で確認できます。pillarパッケージから再エクスポートされている関数です。

**業務上の目的・背景**：データ分析において、データセットの構造を素早く把握することは重要です。標準のRの`str()`関数は多くの情報を提供しますが、出力が冗長になりがちです。`glimpse()`は、よりコンパクトで見やすい形式でデータの概要を表示し、探索的データ分析の効率を向上させます。

**機能の利用シーン**：
- データセットの初期探索
- 列名と型の確認
- データのサンプル値の確認
- パイプライン内でのデータ確認（透過的に元データを返す）
- リモートデータソース（データベース等）の構造確認

**主要な処理内容**：
1. データフレームの列情報を取得
2. 各列を行として表示（列名、型、サンプル値）
3. 元のデータを不可視（invisibly）で返却

**関連システム・外部連携**：pillarパッケージから再エクスポートされています。リモートデータソース（tibbleのソース）でも動作します。

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

## 関連画面

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

## 機能種別

データ表示 / ユーティリティ

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| x | data.frame/tibble | Yes | 表示対象のデータフレーム | - |
| width | integer | No | 出力の幅（文字数） | NULLの場合はコンソール幅 |
| ... | - | No | 追加引数（pillar::glimpseに渡される） | - |

### 入力データソース

関数の引数として直接渡されるデータフレーム。リモートデータソースもサポート。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| コンソール出力 | text | 行数・列数、各列の名前・型・サンプル値 |
| 戻り値 | same as input | 入力xを不可視（invisibly）で返却 |

### 出力先

コンソールに出力され、入力データを不可視で返却します。

## 処理フロー

### 処理シーケンス

```
1. データフレームの情報取得
   └─ 行数、列数、列名、列の型を取得
2. フォーマット処理
   └─ 各列を1行として表示形式に変換
3. コンソール出力
   └─ Rows: N, Columns: M 形式でヘッダー表示
   └─ 各列を「$ 列名 <型> サンプル値」形式で表示
4. 元データの返却
   └─ 入力データをinvisiblyで返却
```

### フローチャート

```mermaid
flowchart TD
    A[glimpse x 呼び出し] --> B[行数・列数を取得]
    B --> C[各列の情報を取得]
    C --> D[フォーマット処理]
    D --> E[コンソールに出力]
    E --> F[x を invisibly で返却]
    F --> G{パイプラインで使用?}
    G -->|Yes| H[次の処理へ x を渡す]
    G -->|No| I[処理終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-80-01 | 透過的返却 | 入力データをinvisiblyで返却し、パイプラインを継続可能 | 常時 |
| BR-80-02 | 列方向表示 | 各列を行として表示（転置表示） | 常時 |
| BR-80-03 | 幅適応 | コンソール幅に応じてサンプル値を切り詰め | 常時 |
| BR-80-04 | 基底データ表示 | リモートデータソースでも実際のデータを表示 | リモートソースの場合 |

### 計算ロジック

特別な計算ロジックはありません。表示フォーマット処理のみです。

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

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

本機能はデータベースを操作しません（リモートソースでは読み取りのみ）。

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| - | - | SELECT（リモート時） | データのサンプル取得のみ |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | エラー | 非データフレームオブジェクト | データフレームまたはtibbleを渡す |

### リトライ仕様

リトライ機構はありません。

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

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

## パフォーマンス要件

- 即座に実行される（サンプル値の取得のみ）
- 大規模データでも高速（全データを処理しない）

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

特別なセキュリティ考慮事項はありません。

## 備考

- pillarパッケージの関数を再エクスポート
- `str()`の代替として設計
- パイプライン内で使用可能（`%>%`や`|>`）
- リモートデータソースでも基底データを表示

---

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

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

### 推奨読解順序

#### Step 1: 再エクスポートの仕組みを理解する

glimpseがpillarからどのように再エクスポートされているかを理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | reexport-pillar.R | `R/reexport-pillar.R` | 再エクスポートの定義 |

**読解のコツ**: `@importFrom`と`@export`の組み合わせによる再エクスポートパターンを理解してください。

#### Step 2: ドキュメントを理解する

関数の使用方法とサンプルを理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | reexport-pillar.R | `R/reexport-pillar.R` | ドキュメントコメント |

**主要処理フロー**:
1. **1-13行目**: ドキュメント（@description）- glimpseの機能説明
2. **15-16行目**: 戻り値の説明 - invisiblyで元データを返却
3. **17-26行目**: 使用例 - mtcars、パイプライン、starwars
4. **27-28行目**: @importFrom pillar glimpse による再エクスポート
5. **29-30行目**: @exportと関数名の定義

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

```
glimpse(x) [dplyr経由でpillar::glimpse()]
    │
    └─ pillar::glimpse() [pillarパッケージ]
           │
           ├─ データフレームの情報取得
           │      ├─ nrow(x) - 行数
           │      ├─ ncol(x) - 列数
           │      └─ sapply(x, ...) - 各列の型とサンプル
           │
           ├─ フォーマット処理
           │      └─ 各列を「$ 列名 <型> サンプル値」形式に
           │
           ├─ cat() でコンソール出力
           │
           └─ invisible(x) で元データを返却
```

### データフロー図

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

x (data.frame) ─────────▶ pillar::glimpse()
                                │
                                ├─▶ 行数・列数の取得
                                │         │
                                │         ▼
                                │   "Rows: N"
                                │   "Columns: M"
                                │
                                ├─▶ 各列の情報取得
                                │         │
                                │         ▼
                                │   "$ col1 <type> val1, val2..."
                                │   "$ col2 <type> val1, val2..."
                                │
                                └─▶ invisible(x) ──────────▶ 元データ
                                                           (パイプライン継続可能)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| reexport-pillar.R | `R/reexport-pillar.R` | ソース | glimpse/type_sumの再エクスポート |
| glimpse.Rd | `man/glimpse.Rd` | ドキュメント | ヘルプファイル |
