correlation-analysis

name	correlation-analysis
description	bitbank のローソク足リターン系列から複数銘柄間の関係性を定量化する。 Pearson/Spearman 相関、β 行列、ローリング相関、環境別相関、 ラグ相関を出して記述的に答える。売買判断は出さない。 代表トリガー: 「BTC-ETH の相関は？」「ETH の β は？」 「分散投資効果はある？」「下落時に相関は上がる？」 注意: 単一銘柄リスクは volatility-profile、シグナル予測力は signal-explorer、保有資産評価は portfolio が担当。
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

いつ使うか

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

• 「ETH と XRP ってどれくらい連動してる？」「アルトの連動度は？」
• 「環境別相関を見て」「銘柄間ラグはある？」「BTC が先行する？」
• 「リスク分散できてる？」
• 曖昧形: 「BTC と ETH の関係どう？」「複数銘柄の相関見て」

役割と他 skill との切り分け

本 skill は 「複数銘柄のリターン系列から銘柄間の関係性を定量化する」 ための 記述的分析レイヤー。同時相関・β・ローリング相関・環境別相関・ラグ相関を出すが、 売買判断や戦略 PnL は一切出さない。

• portfolio との違い: portfolio は 保有資産の評価（実体）。今いくら持っているか、評価損益は いくらかを見る。本 skill は 任意ペアの関係性（仮定） を見るので、 保有していない銘柄のペアでも分析できる。
• volatility-profile との違い: volatility-profile は 単一銘柄 のリスク特性（分布・時間帯・クラスタリング）。 本 skill は 複数銘柄 の関係性。「BTC のボラ」は volatility-profile、 「BTC と ETH の連動度」は本 skill。
• signal-explorer との違い: signal-explorer は シグナル → 将来リターン の予測力（時間方向の関係）。 本 skill は 銘柄 ↔ 銘柄 の同時/ラグ関係（記述）。 「RSI は将来リターンと相関ある？」は signal-explorer、 「ETH のリターンは BTC のリターンと相関ある？」は本 skill。
• indicator-analysis / backtest との違い: どちらも単一銘柄での売買シグナル / 戦略評価。本 skill は売買判断を出さない。

トリガー条件

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

• 「BTC-ETH の相関は？」「ETH と XRP ってどれくらい連動してる？」
• 「ETH の β は？」「BTC が 1% 動いたら ETH は何 % 動く？」
• 「アルトの連動度を見て」「銘柄間の関係性を見て」
• 「下落時に相関は上がる？」「環境別相関を見て」
• 「銘柄間にリードラグはある？」「BTC が先行する？」
• 「分散投資効果はある？」「リスク分散できてる？」
• 曖昧形: 「BTC と ETH の関係どう？」「複数銘柄の相関見て」

以下では 起動しない:

• 「BTC のボラ特性は？」（単一銘柄 → volatility-profile）
• 「RSI は将来リターンと相関ある？」（シグナル予測力 → signal-explorer）
• 「今いくら持ってる？」（保有資産 → portfolio）
• 「BTC の RSI を見て」（指標値の読み → indicator-analysis）

ペア指定とデータ取得

入力

• ペア配列: 2 個以上。デフォルトは btc_jpy / eth_jpy / xrp_jpy
• 時間軸 (--type): デフォルト 1day
• 期間: デフォルト直近 1000 本

ユーザー指定があれば優先。ペア数の自動絞り込みはしない（指定通りに処理）。

CLI 取得（各ペアごとに 1 コマンド）

bitbank candles btc_jpy --type=1day --limit=1000 --format=json --machine
bitbank candles eth_jpy --type=1day --limit=1000 --format=json --machine
bitbank candles xrp_jpy --type=1day --limit=1000 --format=json --machine

期間指定時:

bitbank candles btc_jpy --type=1day --from=20240101 --to=20241231 --format=json --machine

整列（inner join）

• envelope の success を確認後、data 配列から各行 {open, high, low, close, vol, timestamp} を取り出す（CLI が数値正規化済み、 timestamp はミリ秒 UTC、配列は昇順＝古い順）。本 skill は close と timestamp を使う
• 各ペアの meta.lastIsIncomplete: true なら末尾足をリターン計算から除外 （未確定足を含めると当日の相関が安定しない）。gaps がある場合は欠損 区間を取り除いてから inner join する
• 各ペアの close 系列を timestamp で inner join（全ペアに存在する足だけ残す）
• 整列後の close 配列に pct_change（または対数リターン）を適用してリターン化
• 以降のすべての計算はリターンベース

リターン定義は 対数リターン を本 skill のデフォルトとする:

r[t] = log(close[t] / close[t-1])

ユーザーが単純リターンを希望した場合のみ (close[t] - close[t-1]) / close[t-1] に 切り替える。ペア間で混在させない。

デフォルト分析セット（8 ステップ）

Step 1: 価格 vs リターンの相関比較

各ペアについて 価格そのものの相関 と リターンの相関 を両方計算し並記する。

• 価格の相関は通常 0.9 を超える（共通トレンドの結果）
• 価格相関 > 0.9 のときは「共通トレンド由来の見せかけ」と必ず注記
• 以降の Step 2〜8 はすべて リターンベース で計算する

Step 2: Pearson / Spearman / 差分

全ペア（n × (n-1) / 2 通り）について 3 列を表で出す:

ペア	Pearson	Spearman	差 (P − S)
BTC-ETH	...	...	...

差分の解釈:

• ≈ 0: 関係はほぼ線形
• > +0.05: 外れ値が Pearson を押し上げ（少数の大変動足が線形相関を盛っている） または Spearman で順位は揃いにくい
• < -0.05: 外れ値が Pearson を押し下げ、または非線形単調関係（Spearman の方が拾える）

Step 3: 相関ヒートマップ（テキスト整形）

n × n の対称行列を表で表示。対角は 1.000。

ラベル:

• |r| > 0.7 → 強相関
• 0.4 ≤ |r| ≤ 0.7 → 中相関
• |r| < 0.4 → 弱相関

Step 4: β 行列

β_{Y on X} = r_{X,Y} × σ_Y / σ_X

「X が 1% 動くと Y は β% 動く」と解釈する。

• β 行列は非対称（β_{Y on X} ≠ β_{X on Y}）。σ 比で計算するため
• 対角は 1.0、それ以外を計算
• β > 1 → 増幅（X より変動が大きい）
• β < 1 → 減衰

行 = 説明側 (X)、列 = 反応側 (Y) で出力。

Step 5: ローリング相関

2 つの窓を使う（デフォルト 短期 30 / 長期 90 本）。

各ペア × 各窓について以下を表示:

| ペア / 窓 | 平均 | 最小 | 最大 | 直近 | 全期間 r との最大乖離 |

「全期間 r では 0.8 でも、一時的に 0.4 まで落ちる」という不安定性を可視化する。 trailing window（末尾合わせ）で計算。center=True 厳禁（signal-explorer Gotchas と同様）。

Step 6: 外れ値トリミング

ペア単位で 各列の上下 1% を除外して相関を再計算する。

• トリミング前後の Pearson r を併記
• 差分が大きい（|変化| > 0.1）→ 数本の極端値が相関を支配していた示唆
• トリミングは ペアごとに独立 に実施（ペアの両系列で同時に上下 1% を切る）

Step 7: 環境別相関

条件銘柄（デフォルト = ペア配列の先頭）の リターン正負 でデータを分割し、 各環境で相関行列を再計算する。

• up: 条件銘柄のリターン > 0 の足
• down: 条件銘柄のリターン < 0 の足
• 0 リターンは除外（双方どちらにも入れない）

出力:

• 上昇局面の相関行列、下落局面の相関行列、差分行列 down − up
• down − up >= 0.1 のペアは 「下落時に相関上昇」 と注記 （クラッシュ時に分散効果が消える典型）

注意:

• 条件銘柄を含むペアは機械的バイアスあり。条件銘柄自身の符号で分割しているので、 自己相関的に高くなる。出力で必ず明示する
• ペア数 = 2 では条件銘柄を含むペアしか存在せず解釈不能。 警告を出してこの Step をスキップ提案する

Step 8: ラグ相関（クロスコリログラム）

lag = -k 〜 +k（デフォルト k = 5）で各ペアの相関を計算する:

corr_lag[k] = Pearson(r_X[t], r_Y[t + k])

• lag = 0 は 同時相関（Step 2 の Pearson と一致するはず → Validation で確認）
• lag > 0 → X が Y より先行（X[t] が Y[t+k] と相関）
• lag < 0 → Y が X より先行

ピーク lag を表示し、ピークが lag = 0 ならリードラグなし と結論する。 ピークが lag = 0 から外れたとき だけ リードラグ兆候ありと表示する（保守的判定）。

8.1 安定性チェック

• 全期間を 4 等分し、各サブ期間で lag = +1 の 符号 を判定
• 4 サブ期間で符号が一致しない（=反転がある）→ 不安定 と警告
• 一致していれば「持続的な傾向」と読む

多重比較への注意を 1 行入れる: (2k+1) ラグ × ペア数を同時検定するため、 偶然のピークが出やすい。ピーク 1 個に飛びつかない。

最終サマリー

5 項目を 1 ボックスで提示する:

1. 最連動ペア / 最独立ペア（リターンベースの Pearson r で）
2. β > 1 のペア（増幅関係）
3. 環境非対称（down − up >= 0.1）のペア
4. リードラグ兆候のあるペア: 同時相関より顕著に高いラグ相関があれば。 なければ「同時動作のみ」と書く
5. 平均相関 > 0.7（デフォルト閾値）→ 「分散効果は限定的」とコメント

出力フォーマット例

=== 銘柄間関係性: btc_jpy / eth_jpy / xrp_jpy (1day, N=730) ===

--- 1. 価格 vs リターン相関 ---
価格 r (BTC-ETH): 0.97 ← 共通トレンドによる見せかけ
リターン r (BTC-ETH): 0.81 ← 真の連動

--- 2. Pearson / Spearman / 差 ---
BTC-ETH: 0.81 / 0.80 / -0.01
BTC-XRP: 0.61 / 0.63 / +0.02
ETH-XRP: 0.59 / 0.60 / +0.01

--- 3. ヒートマップ ---
            BTC    ETH    XRP
      BTC | 1.00  0.81  0.61
      ETH | 0.81  1.00  0.59
      XRP | 0.61  0.59  1.00

--- 4. β 行列（行が X, 列が Y。X が 1% 動くと Y は β% 動く）---
            BTC    ETH    XRP
      BTC | 1.00  1.18  0.92
      ETH | 0.55  1.00  0.71
      XRP | 0.40  0.49  1.00
→ BTC→ETH = 1.18（増幅）, BTC→XRP = 0.92（減衰）

--- 5. ローリング相関（BTC-ETH, win=30）---
平均 0.78, min 0.42, max 0.95, 直近 0.81
全期間 r=0.81 との最大乖離: -0.39

--- 6. 外れ値トリミング（上下 1%）---
BTC-ETH: 0.81 → 0.77 (差 -0.04)
BTC-XRP: 0.61 → 0.55 (差 -0.06)

--- 7. 環境別相関（条件銘柄 = BTC, ペア数 3）---
注: 条件銘柄を含むペア (BTC-ETH, BTC-XRP) は機械的バイアスあり
ETH-XRP: up = 0.51, down = 0.68, 差 +0.17 → 下落時に相関上昇

--- 8. ラグ相関（k = ±5）---
BTC→ETH: peak = lag 0 (r=0.81) → リードラグなし
BTC→XRP: peak = lag 0 (r=0.61) → リードラグなし
安定性 (4 期間 lag+1 符号): BTC-ETH 反転あり → 不安定
※ (2k+1)×ペア数の多重比較に注意

=== サマリー ===
- 最連動ペア: BTC-ETH (r=0.81) / 最独立ペア: ETH-XRP (r=0.59)
- β > 1: BTC→ETH (1.18)
- 環境非対称: ETH-XRP (down−up = +0.17)
- リードラグ: なし（同時動作のみ）
- 平均相関 r=0.67 → 0.7 未満なので「限定的」とは言わない（分散効果はある。ただし強くはない）

自己チェック（Validation Loop）

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

1. リターンを使っているか（価格直接で相関を取っていないか）。Step 1 の 価格相関と Step 2 以降のリターン相関で 明確に区別されているか
2. 相関行列の対角が 1.000、対称行列であるか（誤差 < 1e-6）。 corr(X, X) = 1 と corr(X, Y) = corr(Y, X) を点検
3. β 行列は非対称が正しい（対称化されていたら誤り）。 β_{Y on X} = r × σ_Y / σ_X で σ 比が入るため、X→Y と Y→X は別値
4. 環境別相関の up / down サンプル数の合計が全体と概ね一致するか （= 0 リターンは除外されるので少しだけ減る程度）
5. ラグ相関の lag = 0 が Step 2 の Pearson 相関と一致するか（誤差 < 1e-6）。 ずれていればインデックスのシフトミス

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

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

パラメータ	デフォルト	説明
ペア配列	btc_jpy / eth_jpy / xrp_jpy	2 個以上
時間軸	1day	--type の値
期間	直近 1000 本	--limit または --from/--to
ローリング窓	短期 30 / 長期 90	trailing window
トリミング率	上下 1%	Step 6
条件銘柄	配列先頭	Step 7
ラグ範囲	±5	Step 8
安定性サブ期間数	4	Step 8.1
強相関閾値	0.7	ヒートマップの強/中/弱ラベル
分散効果評価閾値	平均相関 0.7	サマリーで「限定的」と表示する閾値
リターン定義	対数リターン	単純リターンを希望時のみ切替

ローカル環境なので、このファイルのデフォルト値を直接編集しても OK。

可視化（オプション）

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

本 skill の標準チャート:

チャート ID	内容	主な構成要素
correlation-analysis.heatmap	リターン相関ヒートマップ	Step 3 の n×n 行列。0 中心の diverging カラーマップ（vmin=-1, vmax=1）+ セルに数値注記。タイトルに return-based を明記（価格相関でないこと）
correlation-analysis.rolling	ローリング相関の時系列	Step 5 の窓別（短期 / 長期）ローリング相関 + 全期間 r の水平線。不安定性（全期間 r からの乖離）が読めるようにする
correlation-analysis.env-split	環境別相関の比較	Step 7 の up / down 相関をペアごとのグループ棒 + 差分。条件銘柄バイアスの注記を脚注に
correlation-analysis.cross-correlogram	ラグ相関	Step 8 の lag = −k〜+k の棒グラフ。lag=0 を強調表示。多重比較への注意を脚注に

チャート固有の注意:

• 図中の値は本文の対応する Step のテーブルと一致していること （Validation Loop と同じ整合性検証を図にも適用する）
• rolling はペア数が多いと線が重なって読めない。3 ペアを超える場合は 主要ペアに絞るか、ペアごとに 1 図に分ける
• env-split はペア数 = 2 のとき本文どおり Step 7 自体をスキップするので描かない
• 全チャートはリターンベース。価格系列そのものの相関図は作らない （Step 1 の注記と同じ理由）

Gotchas

• 価格そのままの相関は使わない。 共通トレンドで簡単に 0.9 を超え、見せかけの 連動になる。本 skill は Step 1 で価格相関も「対比用に」出すが、解釈の主軸は リターン相関
• 環境別相関は条件銘柄を含むペアでバイアスあり。 条件銘柄自身の符号で分割 しているため自己相関的に高く出る。出力で必ず明示する
• 多重比較問題。 ペア × ラグ × サブ期間で検定を繰り返すので個別 p 値で 判断しない。本 skill は r の絶対値とローリング相関の安定性 を主軸にし、 p 値は脇役（出さない）
• inner join で欠損ペアが混じるとサンプル激減。 取引停止ペアや上場日が 違うペアを混ぜると、共通期間が極端に短くなる。事前に data-verification での確認を推奨
• ペア数 = 2 で環境別相関は解釈不能。 警告 + Step 7 スキップ提案
• β 行列は非対称。 β_{Y on X} = r × σ_Y / σ_X の σ 比で X→Y と Y→X は 別値。対称化したら誤り
• ラグ相関で安易にリードラグを謳わない。 同時相関 (lag=0) より顕著に高い ピークが他ラグにあるとき だけ 兆候ありとする。安定性チェック（4 サブ 期間で符号一致）も併用
• ローリング相関は trailing window 厳守。 center=True は未来データを 参照する。Z-score / 相関含めて全 rolling を末尾合わせで
• 対数リターンと単純リターンを混ぜない。 本 skill は 対数リターン統一
• bitbank 現物の JPY ペアのみ対象。 USDT クロス・海外取引所データは扱わない （signal-explorer の経路 C に相当する仕組みは持たない）
• 配列は古い順。 ohlcv の先頭が最古。逆順処理するとリターン符号が反転
• 価格は文字列で返る。 parseFloat で数値変換してから計算する
• タイムスタンプはミリ秒 UNIX。 各ペアで秒/ミリ秒を取り違えると inner join が空になる
• ペアカテゴリ（major/mid/minor）の混在に注意。 minor 同士のペアは出来高 ゼロ足が混じり相関が歪む。_shared/references/pair-classification.md を 併せて参照
• API がエラーを返した場合は _shared/references/bitbank-api-formats.md を参照

参照資料

詳細な理論的背景・価格相関とリターン相関の数学的差・β の導出・環境別相関の 条件付けバイアス・多重比較補正の方針・bitbank 主要ペアの典型的相関値レンジ・ 平均相関 0.7 が分散投資にもたらす影響の試算は references/correlation-guide.md を参照。