volatility-profile

name	volatility-profile
description	bitbank のローソク足データから単一銘柄のリスク特性を定量化する。 分布統計（歪度・尖度）、ファットテール倍率、時間帯別出来高、 √T スケーリング比などからストップ幅・低流動性時間帯回避を提示する。 代表トリガー: 「BTC のボラどう？」「ファットテール度は？」 「ストップ幅どう決める？」「リスク特性を見て」 注意: 売買シグナル系（RSI / クロス等）は indicator-analysis、 銘柄間関係は correlation-analysis が担当。
compatibility	Requires the bitbank CLI on PATH (install separately: npm i -g bitbank-lab-cli). Plugin install alone does NOT bundle the CLI or its dependencies. Node.js 22+.
metadata	{"author":"bitbankinc","version":"1.0","requires":{"bins":["bitbank"]}}

ボラティリティ・プロファイル Skill

いつ使うか

代表トリガー以外にも以下のような発話で起動する:

• 「ボラ特性見て」「±3σ は理論の何倍出る？」「分布の形は？」
• 「ポジションサイズの目安は？」「出来高薄い時間帯は？」 「流動性のある時間帯は？」
• 曖昧形: 「リスクどうなってる？」「分布見て」

売買シグナル・トレンド判定の発話（「RSI」「クロス」「買い時」等）では 起動しない。indicator-analysis に委ねる。

役割と他 skill との切り分け

本 skill は 「分析に耐えるデータの統計的性質を読む」 ためのもの。 売買判断ではなく、リスク特性のメタ情報 を提供する。

• data-verification との違い: data-verification は「データが分析に耐えるか」を判定するゲートキーパー。 本 skill は その先の段階で、データの統計的性質（分布の形・時間帯偏り・ 自己相関）を読む。data-verification が NG ならまずそちらで対処してから 本 skill を使う。
• indicator-analysis との違い: indicator-analysis は売買シグナル生成のための指標計算（SMA/RSI/MACD/BB）。 本 skill は売買判断をしない。「BTC のボラを見て」では起動するが、 「BTC の RSI を見て」では起動しない。

トリガー条件

以下のような発話で起動する:

• 「BTC のボラ特性は？」「リスク特性見て」「分布の形は？」
• 「ファットテール度は？」「±3σ は理論の何倍出る？」
• 「ストップ幅どれくらい？」「ポジションサイズの目安は？」
• 「出来高薄い時間帯は？」「流動性のある時間帯は？」
• 曖昧形: 「BTC のボラどう？」「リスクどうなってる？」「分布見て」

売買シグナル・トレンド判定の発話（「RSI」「クロス」「買い時」等）では 起動しない。indicator-analysis に委ねる。

データ取得

√T スケーリング検証のため、短期足と長期足の 2 種類 を取得する:

# デフォルト: 短期 1hour + 長期 1day
bitbank candles <pair> --type=1hour --format=json --machine
bitbank candles <pair> --type=1day --format=json --machine

ユーザー指定がある場合の例:

# 期間指定
bitbank candles btc_jpy --type=1hour --from=20240401 --to=20241231 --format=json --machine
bitbank candles btc_jpy --type=1day --from=20240401 --to=20241231 --format=json --machine

# 件数指定
bitbank candles eth_jpy --type=15min --limit=5000 --format=json --machine

ユーザーが片方の足種だけを指定した場合は、その足種だけで計算し、 √T スケーリング項目はスキップする（残り 4 項目は計算）。

envelope の success を確認後、data 配列から各行 {open, high, low, close, vol, timestamp} を取り出す（CLI が数値正規化済み、 timestamp はミリ秒 UNIX/UTC。--machine の data は平坦な配列で data.candlestick は存在しない）。配列は 昇順（古い順）（先頭が最古）。

meta.lastIsIncomplete: true なら末尾足は未確定。分布統計を歪めるため リターン計算から除外する（リターン定義 log(close[t]/close[t-1]) で 末尾が未確定だと std が過小になる）。gaps がある場合は欠損区間を リターン系列から外し、件数をサマリーに明示する。

デフォルト分析セット

ユーザーが項目を指定しない場合、以下 5 セットをすべて計算する。 詳細は references/volatility-guide.md を参照。

1. リターン基本統計量

対数リターン log(close[t] / close[t-1]) を計算し、以下を出す:

• mean（平均）
• std（標準偏差 σ）
• skewness（歪度）— 0 で対称、負で左裾が長い、正で右裾が長い
• excess kurtosis（超過尖度）— 正規分布で 0。プラスならファットテール

重要: pandas の .kurtosis() は 超過尖度（正規分布で 0）を返す。 「kurtosis = 3 が正規分布」と書かれた資料は通常尖度（Pearson 定義）。 本 skill は 超過尖度 を採用するので、計算式や出力ラベルの混在を避ける。 モデルが直接実装する場合の式:

excess_kurtosis = mean( ((x - mean) / std) ** 4 ) - 3

加えて補助項目として min / max / N（サンプル数） も併記する。

2. ファットテール倍率テーブル

±2σ / ±3σ / ±4σ について、以下の 3 列を出す:

基準	正規分布の理論頻度（定数）
±2σ	4.5500%
±3σ	0.2700%
±4σ	0.0063%

• 理論頻度: 上記の定数（scipy.stats.norm 不要）
• 実測頻度: (|return - mean| > k * std).sum() / N を百分率で
• 倍率: 実測 / 理論

暗号資産では ±3σ で 4〜10 倍、±4σ で 50 倍以上が日常的。 倍率が大きいほど「正規分布前提のリスクモデルが過小評価する」と読む。

3. 時間帯別出来高プロファイル（UTC hour 集約）

タイムスタンプを UTC の hour（0〜23）に変換し、各時間帯の 平均出来高 を計算する。

• 24 時間 × 平均出来高の値を テーブル + 簡易 ASCII バー で表示
• 最大時間帯・最小時間帯の hour と値を抽出
• bitbank の取引参加者は JST 中心 のため、UTC と JST を 両方併記:
  • JST = UTC + 9
  • 例: UTC 14:00 → JST 23:00

短期足（1hour 等）が時間帯分析に向く。1day だけ取得した場合は本項目をスキップする。

4. 出来高 × |リターン| の相関

「出来高が大きいほど価格変動も大きい」という関係の強さを定量化:

• Pearson r: 線形相関
• Spearman r: 順位相関（外れ値耐性あり）
• 両者の差の解釈:
  • 差が小さい（|Pearson - Spearman| < 0.05） → 関係が概ね線形
  • Pearson > Spearman に大きく振れる → 大口約定の数件が相関を押し上げている
  • Spearman > Pearson に大きく振れる → 全体的な順位連動はあるが、外れ値で線形性が崩れている

5. √T スケーリング比

「短期足の σ × √(時間倍率)」と「長期足の σ」を比較し、 ボラクラスタリングの有無を判定する。

• 時間倍率はペアの足種から自動決定:

  短期 → 長期	時間倍率
  1min → 1hour	√60
  5min → 1hour	√12
  15min → 1hour	√4
  1hour → 1day	√24
  4hour → 1day	√6
  1hour → 1week	√168
  1day → 1week	√7

• 理論値: σ_short × √(時間倍率)
• 実測値: σ_long
• 比率: 実測 / 理論
  • 0.9〜1.1 付近 → リターンほぼ独立。√T 則が成立
  • 1.1 超え → 長期足の方がボラ大。ボラクラスタリング（ARCH 効果）示唆
  • 0.9 未満 → 平均回帰的。長期では振れが抑制されている

自己チェック（Validation Loop）

出力前に以下を確認し、不整合があれば修正してから出す。

1. 超過尖度の符号と大きさが妥当か？ 暗号資産は通常プラス（5〜20 程度）。マイナスや 0 付近なら計算式を疑う （特に「kurtosis - 3」を二重に引いていないか）。
2. ±2σ の実測頻度が 1〜10% に収まるか？ 桁が違えば σ の計算ミス（標本分散 vs 母分散の取り違え、対数リターンと 単純リターンの混在等）。
3. 時間帯別出来高の合計が全期間出来高の合計と一致するか？ 時間帯集約のロジックチェック。
4. √T 比率が 0.5〜2.0 の常識的範囲か？ 大きく外れたら期間ミスマッチを疑う（短期と長期で取得期間が違う等）。 両足の取得期間を揃える。
5. 対数リターンの計算で close = 0 や負値が混じっていないか？ log(0) で -Infinity が混入し、std が壊れる。 data-verification を未実施なら、計算前に最低限のサニティチェックをかける。

出力フォーマット

セクションごとにテーブル形式。最後に 実用サマリー で読み筋を提示する。

=== ボラティリティ・プロファイル: btc_jpy ===
期間: 2024-04-01 〜 2024-12-31（1hour: 6,576 本 / 1day: 274 本）

--- 基本統計量（1hour）---
mean        std        歪度        超過尖度    最小       最大       N
+0.00012    0.00562   -0.13       7.60       -4.59%    +4.31%   6,576

--- ファットテール倍率 ---
基準    | 正規分布（理論）| 実測頻度  | 倍率
±2σ     | 4.5500%       | 5.21%   | 1.1x
±3σ     | 0.2700%       | 1.18%   | 4.4x
±4σ     | 0.0063%       | 0.41%   | 65x

--- 時間帯別出来高（UTC, JST 併記）---
最大: UTC 14:00 / JST 23:00 — 平均出来高 24.3 BTC
最小: UTC 05:00 / JST 14:00 — 平均出来高  8.7 BTC
（24 時間グリッドのバーを ASCII で表示）

--- 出来高 vs |リターン| ---
Pearson:  0.62
Spearman: 0.51
→ Pearson > Spearman: 大口約定が相関を押し上げている可能性

--- √T スケーリング（1hour → 1day, 倍率 √24）---
σ_1h × √24 (理論):  0.0275
σ_1d (実測):       0.0277
比率:              1.007 → ボラはほぼ独立

--- 実用サマリー ---
- ストップ幅の目安: 1hour ATR の代替として ±2σ ≈ ±1.12% を基準に
- ±3σ が理論の 4.4x → 「滅多に起きない」想定の損失が想定より頻発。
  VaR を正規分布前提で算出すると過小評価
- 高流動性時間帯: JST 22:00〜0:00（NY 市場活発）
- 低流動性時間帯: JST 13:00〜15:00 — 大口注文は避ける
- √T 比 ≈ 1.0 → ボラクラスタリングは弱い。短期 σ から長期リスクを推定可能

実行手順

1. ペアと（指定があれば）期間・足種を確認
2. 短期足・長期足それぞれを CLI で取得（--format=json --machine）
3. envelope の success を確認後、data 配列から各行 {open, high, low, close, vol, timestamp} を取り出す（CLI が数値正規化済み、 timestamp はミリ秒 UTC、配列は昇順＝古い順）。meta.lastIsIncomplete: true なら末尾足を除外、 gaps があれば欠損区間を系列から外しサマリーに明示
4. 対数リターン log(close[t]/close[t-1]) を計算（先頭は欠損）
5. 5 セットの分析を計算（短期足のみ指定時は √T 以外の 4 セット）
6. Validation Loop の 5 項目を点検
7. テーブル + 実用サマリーを出力

カスタマイズ可能なパラメータ

ユーザーが指定した場合はそちらを優先。

パラメータ	デフォルト	説明
短期足	1hour	√T 検証の分子
長期足	1day	√T 検証の分母
データ本数（短期）	5,000	統計的に意味のある最低水準
データ本数（長期）	250	同上
σ 倍率	2, 3, 4	ファットテール表示の閾値
リターン定義	対数リターン	log(close[t]/close[t-1])。単純リターンを希望されたら切替

例: 「±5σ も含めて」「短期は 15min で見て」「過去 1 年で」といった指定はそのまま反映。 ローカル環境なので、このファイルのデフォルト値を直接編集しても OK。

可視化（オプション）

トリガー規律・実行環境の解決・出力先・スタイル・安全規律は _shared/references/visualization-guide.md に従う。デフォルトは off （ユーザーが明示的に求めたとき、または提案に同意したときだけ描く）。 チャートはテキスト出力（テーブル + 実用サマリー）の後に描き、 その置き換えにはしない。

本 skill の標準チャート:

チャート ID	内容	主な構成要素
volatility-profile.return-distribution	リターン分布ヒストグラム	対数リターンのヒストグラム + 同じ mean / σ の正規分布 pdf の重ね描き + ±2σ / ±3σ の縦線。歪度・超過尖度・ファットテール倍率をフッターに
volatility-profile.hourly-volume	時間帯別出来高プロファイル	hour（0〜23）× 平均出来高の棒グラフ。x 軸は UTC を主とし JST を併記（本文セット 3 と同じ UTC hour 集約 + JST 併記）。最大 / 最小時間帯を注記
volatility-profile.volume-return-scatter	出来高 × |リターン| 散布図	セット 4 の散布 + Pearson / Spearman r をタイトルに併記。大口約定の外れ値が視認できるようにする

チャート固有の注意:

• 図中の統計量は本文の対応するセットの値と一致していること （Validation Loop と同じ整合性検証を図にも適用する）
• return-distribution のビン幅は Sturges 等の既定に任せてよいが、 ±4σ の裾が見える範囲まで x 軸を確保する（ファットテールの視認が目的）
• hourly-volume は短期足（1hour 等）取得時のみ。1day だけの場合は 本文どおりセット 3 自体をスキップするので描かない

Gotchas

• 価格は文字列で返る。 parseFloat での数値変換を忘れると std が狂う。 ohlcv[3]（close）は "9250000" のような文字列
• 配列は古い順。 先頭が最古。逆順処理するとリターン符号が反転する
• 対数リターンと単純リターンを混ぜない。 本 skill は 対数リターン統一。 log(close[t] / close[t-1])。±2σ 等のしきい値判定もこれを使う
• 超過尖度の定義に注意。 pandas の .kurtosis() は超過尖度（正規分布で 0）。 「正規分布で 3」と書く資料の式（Pearson 定義）と混在させない。 本 skill は 超過尖度（正規分布で 0） で統一
• ±2σ の理論頻度 4.55% は両側合計。 片側 2.275% × 2。実測も両側で取る
• タイムスタンプはミリ秒 UNIX。 UTC hour に変換するとき、秒・ミリ秒の 扱いを間違えると 0 時付近に偏る
• JST = UTC + 9 のオフセット。 日付をまたぐ場合があるので hour だけで集約する
• √T スケーリングは期間を揃える。 短期と長期で取得期間がズレると、 比率が市場レジーム差で変わってしまう。期間指定するときは両方同時に揃える
• 1month は不定間隔。 月ごとに日数が違うので √T の母数として使わない
• データ本数が少ないと尖度が暴れる。 短期足は最低 1,000 本、できれば 5,000 本以上
• API がエラーを返した場合は _shared/references/bitbank-api-formats.md のエラーコードを確認する
• 本 skill は単一ペア前提。 銘柄間の分布比較（BTC vs ETH 等）は将来 correlation-analysis skill で扱う
• ペアカテゴリ（major/mid/minor）に応じた閾値変更は不要。 本 skill は事実を提示するのみで NG 判定をしない