| 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 種類 を取得する:
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）
出力前に以下を確認し、不整合があれば修正してから出す。
- 超過尖度の符号と大きさが妥当か？
暗号資産は通常プラス（5〜20 程度）。マイナスや 0 付近なら計算式を疑う
（特に「kurtosis - 3」を二重に引いていないか）。
- ±2σ の実測頻度が 1〜10% に収まるか？
桁が違えば σ の計算ミス（標本分散 vs 母分散の取り違え、対数リターンと
単純リターンの混在等）。
- 時間帯別出来高の合計が全期間出来高の合計と一致するか？
時間帯集約のロジックチェック。
- √T 比率が 0.5〜2.0 の常識的範囲か？
大きく外れたら期間ミスマッチを疑う（短期と長期で取得期間が違う等）。
両足の取得期間を揃える。
- 対数リターンの計算で
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 → ボラクラスタリングは弱い。短期 σ から長期リスクを推定可能
実行手順
- ペアと（指定があれば）期間・足種を確認
- 短期足・長期足それぞれを CLI で取得（
--format=json --machine）
- envelope の
success を確認後、data 配列から各行
{open, high, low, close, vol, timestamp} を取り出す（CLI が数値正規化済み、
timestamp はミリ秒 UTC、配列は昇順＝古い順）。meta.lastIsIncomplete: true なら末尾足を除外、
gaps があれば欠損区間を系列から外しサマリーに明示
- 対数リターン
log(close[t]/close[t-1]) を計算（先頭は欠損）
- 5 セットの分析を計算（短期足のみ指定時は √T 以外の 4 セット）
- Validation Loop の 5 項目を点検
- テーブル + 実用サマリーを出力
カスタマイズ可能なパラメータ
ユーザーが指定した場合はそちらを優先。
| パラメータ | デフォルト | 説明 |
|---|
| 短期足 | 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 判定をしない
