data-quality-checker

概要

公開前に市場分析ドキュメントの一般的なデータ品質問題を検出します。チェッカーは5つのカテゴリを検証します：価格スケール一貫性、インストルメント記法、日付/曜日の正確性、配分合計、および単位の使用。すべての検出結果は助言的なものです。公開をブロックするのではなく、人間によるレビューの対象として潜在的な問題にフラグを立てます。

使用時期

• 週次戦略ブログまたは市場分析レポートを公開する前
• 自動生成された市場サマリー後
• 翻訳されたドキュメント (英語/日本語) のデータ精度をレビューするとき
• 複数のソース (FRED、FMP、FINVIZ) からのデータを1つのレポートに組み合わせるとき
• 金融データを含む任意のドキュメントの事前確認チェックとして

前提条件

• Python 3.9以上
• 外部 API キーは不要
• サードパーティの Python パッケージは不要 (標準ライブラリのみ使用)

ワークフロー

ステップ1: 入力ドキュメント受け取り

対象のマークダウンファイルパスとオプションパラメータを受け取ります：

• --file: 検証するマークダウンドキュメントへのパス (必須)
• --checks: 実行するチェックをカンマ区切りで指定 (オプション；デフォルト: 全て)
• --as-of: 年推測用の参照日付 YYYY-MM-DD 形式 (オプション)
• --output-dir: レポート出力ディレクトリ (オプション；デフォルト: reports/)

ステップ2: 検証スクリプト実行

データ品質チェッカースクリプトを実行します：

python3 skills/data-quality-checker/scripts/check_data_quality.py \
  --file path/to/document.md \
  --output-dir reports/

特定のチェックのみを実行する場合：

python3 skills/data-quality-checker/scripts/check_data_quality.py \
  --file path/to/document.md \
  --checks price_scale,dates,allocations

年推測用の参照日付を指定する場合 (ドキュメントに明示的な年がない日付の場合に有用)：

python3 skills/data-quality-checker/scripts/check_data_quality.py \
  --file path/to/document.md \
  --as-of 2026-02-28

ステップ3: 参照基準の読み込み

検出結果の文脈化のため、関連する参照ドキュメントを読み込みます：

• references/instrument_notation_standard.md -- 標準ティッカー記法、各インストルメントクラスの桁数ヒント、命名規約
• references/common_data_errors.md -- 頻繁に観察されるエラーのカタログ。FRED データの遅延、ETF/先物スケール混乱、祝日の見落とし、配分合計の落とし穴、単位混乱パターンを含む

検出結果の説明と修正提案に、これらの参照を使用します。

ステップ4: 検出結果をレビュー

出力の各検出結果を確認します：

• ERROR -- 高信度の問題 (例：カレンダー計算で検証された日付-曜日のミスマッチ)。修正を強く推奨します。
• WARNING -- 人間の判断が必要な可能性の高い問題 (例：価格スケール異常、記法不一貫性、配分合計が 0.5% を超えてずれている)。
• INFO -- 情報提供のみ (例：混在する bp/% 使用法は意図的かもしれない)。

ステップ5: 品質レポート生成

スクリプトは2つの出力ファイルを生成します：

1. JSON レポート (data_quality_YYYY-MM-DD_HHMMSS.json): 重要度、カテゴリ、メッセージ、行番号、文脈を含む機械可読の検出結果リスト。
2. Markdown レポート (data_quality_YYYY-MM-DD_HHMMSS.md): 重要度レベルでグループ化された人間が読みやすいレポート。

ナレッジベースを参照する説明とともに検出結果をユーザーに提示します。各問題について具体的な修正を提案します。

出力形式

JSON 検出結果の構造

{
  "severity": "WARNING",
  "category": "price_scale",
  "message": "GLD: $2,800 has 4 digits (expected 2-3 digits)",
  "line_number": 5,
  "context": "GLD: $2,800"
}

Markdown レポートの構造

# Data Quality Report
**Source:** path/to/document.md
**Generated:** 2026-02-28 14:30:00
**Total findings:** 3

## ERROR (1)
- **[dates]** (line 12): Date-weekday mismatch: January 1, 2026 (Monday) -- actual weekday is Thursday

## WARNING (2)
- **[price_scale]** (line 5): GLD: $2,800 has 4 digits (expected 2-3 digits)
  > `GLD: $2,800`
- **[allocations]**: Allocation total: 110.0% (expected ~100%)

リソース

• scripts/check_data_quality.py -- メイン検証スクリプト
• references/instrument_notation_standard.md -- 記法と価格スケールの参照
• references/common_data_errors.md -- 一般的なエラーパターンと予防

主要な原則

1. 助言モード: すべての検出結果は人間によるレビューのための警告です。スクリプトは検出結果が存在する場合でも、実行成功時に常に終了コード 0 で終了します。終了コード 1 はスクリプト失敗 (ファイルが見つからない、パースエラー) のために予約されています。

2. セクション対応の配分チェック: "配分"、"Allocation" などのような見出しまたは "ウェイト"、"目安比率" などの表列で識別される配分セクション内のパーセンテージのみがチェックされます。本文内のランダムなパーセンテージ (確率、RSI、年度変化) は無視されます。

3. バイリンガルサポート: 英語と日本語の日付形式、曜日名、セクション見出しの両方に対応します。全角文字 (％、〜、エンダッシュ) は処理前に正規化されます。

4. 年推測: 明示的な年を持たない日付については、チェッカーが (優先順) 以下を使用して年を推測します：--as-of オプション、ドキュメントのタイトル/メタデータで見つかった YYYY パターン、または 6か月の年越しヒューリスティックを用いた現在の年。

5. 桁数ヒューリスティック: 価格スケール検証は絶対的な価格範囲ではなく桁数 (小数点前の桁数) を使用します。このアプローチは時間経過に伴う価格変化に強固ですが、ETF/先物混乱エラーをキャッチします。