data-quality-checker

概要

公開前に、市場分析文書によくあるデータ品質の問題を検出します。チェッカーは、価格スケールの一貫性、金融商品の表記、日付と曜日の正確性、配分の合計、単位の使用という5つのカテゴリを検証します。検出結果はすべて参考情報であり、公開をブロックするのではなく、人による確認が必要な可能性のある問題を示します。

使用するタイミング

• 週次の戦略ブログや市場分析レポートを公開する前
• 自動生成された市場サマリーの作成後
• 翻訳文書（英語／日本語）のデータの正確性を確認するとき
• 複数のソース（FRED、FMP、FINVIZ）のデータを1つのレポートにまとめるとき
• 金融データを含む文書の公開前チェックとして

前提条件

• Python 3.9+
• 外部 API キーは不要です
• サードパーティの Python パッケージは不要です（標準ライブラリのみを使用します）

ワークフロー

ステップ 1：入力文書を受け取る

対象の Markdown ファイルのパスと、任意のパラメーターを指定します。

• --file：検証する Markdown 文書のパス（必須）
• --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 と先物の取り違えも検出できます。