Data verification

データ検証 Skill

いつ使うか

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

• 「candles のデータ大丈夫？」「ちゃんと取れてる？」

indicator-analysis / backtest / portfolio の前段として自動実行はしない。

トリガー条件

明示リクエストのみ。 以下のような発話で起動する:

• 「データ検証して」「データの品質をチェックして」
• 「欠損ないか確認して」「ちゃんと取れてる？」
• 「このデータ信用できる？」

indicator-analysis / backtest / portfolio の前段として自動実行はしない。

データ取得

bitbank candles <pair> --type=<timeframe> --format=json --machine

ユーザーが期間を指定した場合:

bitbank candles <pair> --type=<timeframe> --from=YYYYMMDD --to=YYYYMMDD --format=json --machine

指定がなければ直近データ（デフォルト 1000 本）で検証する。

--machine envelope の meta.gaps / dedupedCount / truncated は本 skill の検証項目（欠損足・重複・時系列連続性）と直接対応する。CLI が既に検出した ものは項目 1〜8 の集計に組み込み、再検出ではなく 既知の検出結果として そのまま報告する（取得側 vs 計算側で二重検出すると件数が合わなくなる）。

検証項目

8 つのチェックを順に実行する。詳細は references/verification-guide.md を参照。

1. 欠損足の検出

期待される本数と実際の本数を比較する。

• 取得期間と時間軸から「あるべきタイムスタンプ列」を計算
• 実データのタイムスタンプと突き合わせ、欠損箇所を特定
• 暗号資産は 24/7 取引のため、土日・祝日による正当な欠損はない

2. 重複タイムスタンプの検出

同一タイムスタンプが複数存在しないか確認する。

• ページネーション境界での重複が起きやすい
• 重複があれば件数と該当タイムスタンプを報告

3. OHLCV 整合性チェック

各ローソク足が以下のルールを満たすか検証する:

• high >= max(open, close)
• low <= min(open, close)
• high >= low
• volume >= 0
• すべての価格 > 0

違反行があれば該当タイムスタンプと具体的な値を報告。

4. 基本統計量サマリー

全フィールドの min / max / mean / std を算出し、データ全体の「顔」を見る。

• 価格の桁チェック: BTC/JPY なら百万〜千万円台、XRP/JPY なら数十〜数百円台。桁が明らかに違えばデータ取り違えの可能性
• min/max の異常: min が 0 や負値、max が直近相場の数倍 → 異常データ混入
• std/mean 比（変動係数）: 極端に大きい場合はレジーム変化（急騰暴落期）を含む期間。バックテスト時は期間分割を検討
• 出来高の偏り: mean に対して max が極端に大きい場合、特定の足に出来高が集中（大口約定やイベント）

検証としては INFO レベル。「一目で全体像を掴む」ための項目であり、NG 判定はしない。

5. 異常値（外れ値）の検出

直前の足からの変動率で異常を検出する。 暗号資産はペアごとにボラティリティが大きく異なるため、閾値を 3 段階に分ける。

ペアカテゴリ: _shared/references/pair-classification.md を参照。 bitbank 上の実際の 24h 出来高シェアに基づく分類。

カテゴリ	基準	代表ペア
major	出来高シェア 10% 以上	btc_jpy, xrp_jpy, eth_jpy
mid	出来高シェア 1〜10%	doge_jpy, sol_jpy, ltc_jpy, ada_jpy 等
minor	出来高シェア 1% 未満	mona_jpy, sand_jpy, gala_jpy 等

デフォルト閾値（ペアカテゴリ × 時間軸）:

	短期足 (1min〜30min)	中期足 (1hour〜12hour)	長期足 (1day〜)
major	価格 ±3%, 出来高 30x	価格 ±8%, 出来高 20x	価格 ±15%, 出来高 15x
mid	価格 ±5%, 出来高 30x	価格 ±12%, 出来高 20x	価格 ±20%, 出来高 15x
minor	価格 ±8%, 出来高 50x	価格 ±18%, 出来高 30x	価格 ±30%, 出来高 20x

ペアが分類表に未掲載の場合は mid を適用する。 ユーザーが閾値を明示した場合はそちらを優先する。

閾値を超えた足をフラグし、タイムスタンプ・値・変動率を報告する。 異常値は「除去すべきエラー」ではなく「確認すべきイベント」として扱う。 暗号資産ではファットテール（4σ超の変動）が珍しくないため、 フラグ = 即削除ではなく、ユーザーの判断材料として提示する。

6. 出来高ゼロ連続の検出

出来高ゼロの足が連続していないか検出する。

• bitbank のアルトコインでは出来高ゼロ足が散発的に出ることは正常
• ただし 連続 3 本以上 のゼロ出来高はフラグする（流動性枯渇の警告）
• major ペアでゼロ出来高が 1 本でもあれば NG（通常あり得ない）

7. ヒゲ異常（wick anomaly）の検出

ローソク足の実体に対してヒゲが異常に長い足を検出する。 十字線・コマ足（始値 ≒ 終値）では wick_ratio が発散するため、実体サイズで判定を 2 段階に分ける。

body       = abs(close - open)
wick_range = high - low
wick_ratio = wick_range / body    # body が十分ある場合のみ

実体サイズ判定（十字線除外）:

body < high * 0.003（価格の 0.3% 未満）なら十字線・コマ足とみなし、wick_ratio は計算しない。 この場合はヒゲ幅 (high - low) の絶対値をペア・時間軸の価格変動閾値（項目 5 のテーブル）と比較する。

フラグ条件（2 段階）:

実体サイズ	判定基準	フラグ
実体が十分ある（body >= high * 0.003）	wick_ratio > 15	INFO
実体が極小（body < high * 0.003、十字線）	wick_range / high が価格変動閾値を超過（例: major/1day なら 15%）	INFO

• 清算カスケードやフラッシュクラッシュで発生しやすい
• OHLCV 整合性は通るが、この足を含む指標計算は歪む可能性がある
• 十字線それ自体は正常なローソク足。ヒゲ幅が小さければフラグしない

8. 時系列連続性チェック

タイムスタンプが等間隔で並んでいるか確認する。

• 期待間隔: 時間軸に対応するミリ秒数（例: 1hour = 3,600,000ms）
• 間隔の飛びがあれば欠損足チェック（項目 1）と照合して原因を推定

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

ユーザーがパラメータを指定した場合はそちらを優先する。 指定がなければ項目 4 のペアカテゴリ × 時間軸テーブルを使う。

パラメータ	デフォルト	説明
価格変動閾値	ペア・時間軸別（項目 4 参照）	ユーザー指定で一律上書き可
出来高変動閾値	ペア・時間軸別（項目 4 参照）	同上
ゼロ出来高連続閾値	3 本 (mid/minor), 1 本 (major)	連続ゼロ出来高のフラグ基準
ヒゲ異常倍率	15x	wick_ratio がこの値を超えたらフラグ

例: 「閾値を 5% にして検証して」→ 価格変動閾値をペアカテゴリに関係なく ±5% に一律変更して実行。

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

実行手順

1. candles コマンドで OHLCV データを取得（--format=json）
2. 出力は Candle オブジェクトの配列。各要素は { open, high, low, close, vol, timestamp }
3. フィールドは CLI が数値変換済み。そのまま計算に使える
4. ペア名からカテゴリ（major/mid/minor）を判定し、時間軸と合わせて閾値を決定
5. 8 つの検証項目を順に実行
6. 結果をレポート形式で出力

出力フォーマット

サマリーテーブル

検証項目               | 結果   | 詳細
-----------------------|--------|------------------------------------------
欠損足                 | OK/NG  | 0 件 / 3 件（タイムスタンプ一覧）
重複タイムスタンプ      | OK/NG  | 0 件 / 2 件
OHLCV 整合性           | OK/NG  | 違反 0 件 / 1 件
基本統計量             | INFO   | close: mean=9,250,000 std=145,000 min=9,050,000 max=9,500,000
異常値（価格）          | INFO   | フラグ 0 件 / 2 件（閾値: major/1hour ±8%）
異常値（出来高）        | INFO   | フラグ 0 件 / 1 件（閾値: major/1hour 20x）
出来高ゼロ連続          | OK/NG  | 0 件 / 1 箇所（5 本連続）
ヒゲ異常               | INFO   | フラグ 0 件 / 1 件（wick_ratio > 15）
時系列連続性           | OK/NG  | 等間隔 / 不連続 2 箇所

ペアカテゴリ: major | 時間軸: 1hour
総合: ✅ データ品質に問題なし / ⚠️ 要確認項目あり

異常値の詳細（フラグがある場合）

タイムスタンプ          | close      | 前足 close | 変動率   | 備考
-----------------------|------------|-----------|---------|--------
2024-03-05T14:00:00Z   | 10,200,000 | 9,100,000 | +12.1%  | 閾値超過

判定基準

• OK: 問題なし
• NG: データ品質に影響する問題あり（分析前に対処を検討）
• INFO: 異常値フラグ（情報提供のみ、除去は推奨しない）

Gotchas

• フィールド名に注意。 出来高は volume ではなく vol
• 配列は古い順。 先頭が最も古いデータ
• 日付形式に注意。 --type=1month は --date=2024、それ以外は YYYYMMDD
• 暗号資産は 24/7。 株式と違い「正当な休場」はない。欠損 = 取引所メンテか API 障害
• 異常値 ≠ エラー。 急騰・急落はファットテール分布の特性。フラグは「要確認」であり「要削除」ではない
• ペアによってボラが全く違う。 BTC の 1h ±8% は異常事態だが、MONA の 1h ±8% は日常。一律閾値は使わない
• minor ペアの出来高ゼロは珍しくない。 即 NG にせず連続本数で判断する。major で出来高ゼロは逆に異常
• ヒゲ異常は OHLCV 整合性チェックを通過する。 high >= open, low <= close 等のルールは満たすが、指標計算を歪める。別チェックが必要
• 十字線・コマ足では wick_ratio が誇張される。 close ≒ open だと分母（実体）が極小になり、ヒゲ幅が小さくても比率が数十〜数百倍に跳ね上がる。実体サイズ（body < high * 0.003 等）で分岐し、十字線はヒゲ幅の絶対値で判定すること
• API がエラーを返した場合は _shared/references/bitbank-api-formats.md のエラーコードを確認する