theme-detector

テーマ検出

概要

このスキルは、セクター横断的なモメンタム、出来高、広がりのシグナルを分析して、トレンドの市場テーマを検出し、ランク付けします。強気（上昇モメンタム）と弱気（下落圧力）の両方のテーマを特定し、ライフサイクルの成熟度（新興／加速／トレンド／成熟／衰退）を評価するとともに、定量データとナラティブ分析を組み合わせた信頼度スコアを提示します。

3 次元スコアリングモデル：

1. テーマの勢い（0～100）：テーマの方向性に依存しない強さ（モメンタム、出来高、上昇トレンド比率、広がり）
2. ライフサイクルの成熟度：継続期間、極端な値の集中、バリュエーション、ETF の増加状況に基づくステージ分類（新興／加速／トレンド／成熟／衰退）
3. 信頼度（低／中／高）：定量的な広がりとナラティブによる確認を組み合わせた、検出の信頼性。スクリプトの出力は「中」までです。Claude の WebSearch によるナラティブ確認ステップで「高」に引き上げることができます。

主な機能：

• FINVIZ の業界データを使用したセクター横断的なテーマ検出
• 方向性を考慮したスコアリング（強気と弱気のテーマ）
• 取引の混雑度と新興度を特定するライフサイクル成熟度の評価
• ETF の増加状況のスコアリング（ETF が多いほど、テーマの成熟度・混雑度が高い）
• 3 点評価のための uptrend-dashboard との連携
• FINVIZ Elite（高速）または公開データのスクレイピング（低速、制限あり）によるデュアルモード動作
• 上位テーマの WebSearch によるナラティブ確認

---

このスキルを使用する場面

明示的なトリガー：

• 「今、どのような市場テーマがトレンドになっていますか？」
• 「どのセクターが好調／不調ですか？」
• 「現在の市場テーマを検出してください」
• 「最も強い強気／弱気のナラティブは何ですか？」
• 「AI／クリーンエネルギー／防衛は、まだ強いテーマですか？」
• 「セクターローテーションはどこに向かっていますか？」
• 「テーマ型投資の機会を教えてください」

暗黙的なトリガー：

• ユーザーが市場全体のナラティブの変化を理解したい
• ユーザーがテーマ型 ETF やセクター配分のアイデアを探している
• ユーザーが混雑した取引やサイクル後半のテーマについて尋ねる
• ユーザーが新興テーマと衰退したテーマを知りたい

使用しない場面：

• 個別株の分析（代わりに us-stock-analysis を使用）
• チャート分析を含む特定セクターの詳細分析（代わりに sector-analyst を使用）
• ポートフォリオのリバランス（代わりに portfolio-manager を使用）
• 配当／インカム投資（代わりに value-dividend-screener を使用）

---

前提条件

必須：

• Python 3.7 以降とコア依存関係：

  pip install requests beautifulsoup4 lxml pandas numpy yfinance
  

任意の API キー：

FINVIZ Elite（幅広い業界を網羅し、高速に処理するため推奨）：

export FINVIZ_API_KEY=your_finviz_elite_api_key_here

FMP API（任意。P/E 比率のバリュエーションデータ用）：

export FMP_API_KEY=your_fmp_api_key_here

任意の Python パッケージ：

• finvizfinance - FINVIZ Elite モードに必要
• PyYAML - カスタムテーマ用の --themes-config に必要

FINVIZ Elite を使用しない場合、このスキルは公開 FINVIZ のスクレイピングを使用します（各業界あたり約 20 銘柄に制限され、レート制限により処理速度も低下します）。

---

ワークフロー

ステップ 1：環境を確認する

前提条件を参照し、API キーが設定されていることを確認します：

# Verify FINVIZ Elite API key (optional but recommended)
echo $FINVIZ_API_KEY

# Verify FMP API key (optional)
echo $FMP_API_KEY

ステップ 2：テーマ検出スクリプトを実行する

メインの検出スクリプトを実行します：

python3 skills/theme-detector/scripts/theme_detector.py \
  --output-dir reports/

スクリプトのオプション：

# Full run (public FINVIZ mode, no API key required)
python3 skills/theme-detector/scripts/theme_detector.py \
  --output-dir reports/

# With FINVIZ Elite API key
python3 skills/theme-detector/scripts/theme_detector.py \
  --finviz-api-key $FINVIZ_API_KEY \
  --output-dir reports/

# With FMP API key for enhanced stock data
python3 skills/theme-detector/scripts/theme_detector.py \
  --fmp-api-key $FMP_API_KEY \
  --output-dir reports/

# Custom limits
python3 skills/theme-detector/scripts/theme_detector.py \
  --max-themes 5 \
  --max-stocks-per-theme 10 \
  --output-dir reports/

# Explicit FINVIZ mode
python3 skills/theme-detector/scripts/theme_detector.py \
  --finviz-mode public \
  --output-dir reports/

想定実行時間：

• FINVIZ Elite モード：約 2～3 分（14 以上のテーマ）
• 公開 FINVIZ モード：約 5～8 分（レート制限付きのスクレイピング）

ステップ 3：検出結果を読み取り、解析する

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

• theme_detector_YYYY-MM-DD_HHMMSS.json - プログラムで利用する構造化データ
• theme_detector_YYYY-MM-DD_HHMMSS.md - 人が読みやすいレポート

定量的な結果を把握するため、JSON 出力を読み取ります：

# Find the latest report
ls -lt reports/theme_detector_*.json | head -1

# Read the JSON output
cat reports/theme_detector_YYYY-MM-DD_HHMMSS.json

Step 4: WebSearch によるナラティブの確認

Theme Heat スコア上位 5 テーマについて、WebSearch クエリを実行してナラティブの強さを確認します。

検索パターン：

"[theme name] stocks market [current month] [current year]"
"[theme name] sector momentum [current month] [current year]"

ナラティブの兆候を評価します：

• 強いナラティブ：複数の主要メディアによる報道、アナリストの格上げ、政策を後押しする要因
• 中程度のナラティブ：報道はあるものの、見方が分かれており、明確な要因がない
• 弱いナラティブ：報道が少ない、または主に逆張り・懐疑的な論調

調査結果に基づいて信頼度を更新します：

• 定量的評価が High ＋ ナラティブが強い = 信頼度 High
• 定量的評価が High ＋ ナラティブが弱い = 信頼度 Medium（モメンタムとの乖離の可能性）
• 定量的評価が Low ＋ ナラティブが強い = 信頼度 Medium（ナラティブが価格に先行する可能性）
• 定量的評価が Low ＋ ナラティブが弱い = 信頼度 Low

Step 5: 結果を分析し、推奨事項を提示する

検出結果をナレッジベースと照合します。

参照するドキュメント：

1. references/cross_sector_themes.md - テーマの定義と構成業種
2. references/thematic_etf_catalog.md - テーマ別の ETF エクスポージャーの選択肢
3. references/theme_detection_methodology.md - スコアリングモデルの詳細
4. references/finviz_industry_codes.md - 業種分類の参照情報

分析フレームワーク：

強い強気テーマ（Heat >= 70、Direction = Bullish）の場合：

• ライフサイクルの段階を特定します（Emerging = 機会、Mature/Exhausting = 注意）
• テーマ内でパフォーマンス上位の業種を列挙します
• エクスポージャーを得るための代理 ETF を推奨します
• ETF の数が多い場合は、過密な取引への警戒を促します

強い弱気テーマ（Heat >= 70、Direction = Bearish）の場合：

• 圧力を受けている業種を特定します
• 弱気モメンタムが加速しているか、減速しているかを評価します
• ヘッジ戦略または回避すべきセクターを推奨します
• ライフサイクルが Mature/Exhausting の場合は、平均回帰の可能性に言及します

新興テーマ（Heat 40-69、Lifecycle = Emerging）の場合：

• 早期の資金ローテーションの兆候である可能性があります
• ウォッチリストに追加して監視することを推奨します
• テーマを加速させる可能性のある触媒イベントを特定します

過熱が一巡したテーマ（Heat >= 60、Lifecycle = Exhausting）の場合：

• 過密な取引のリスクを警告します
• ETF 数が多い場合は、個人投資家の参加が過剰であることを確認できます
• 逆張りのポジションを検討するか、エクスポージャーの縮小を検討します

Step 6: 最終レポートを生成する

レポートテンプレートの構成に従って、ユーザーに最終レポートを提示します。

# Theme Detection Report
**Date:** YYYY-MM-DD
**Mode:** FINVIZ Elite / Public
**Themes Analyzed:** N
**Data Quality:** [note any limitations]

## Theme Dashboard
[Top themes table with Heat, Direction, Lifecycle, Confidence]

## Bullish Themes Detail
[Detailed analysis of bullish themes sorted by Heat]

## Bearish Themes Detail
[Detailed analysis of bearish themes sorted by Heat]

## All Themes Summary
[Complete theme ranking table]

## Industry Rankings
[Top performing and worst performing industries]

## Sector Uptrend Ratios
[Sector-level aggregation if uptrend data available]

## Methodology Notes
[Brief explanation of scoring model]

レポートを reports/ ディレクトリに保存します。

---

出力

このスキルは、reports/ ディレクトリに 2 つのファイルを出力します。

JSON 出力（theme_detector_YYYY-MM-DD_HHMMSS.json）：

{
  "report_type": "theme_detector",
  "generated_at": "2026-04-18 10:30:00",
  "metadata": {
    "generated_at": "2026-04-18 10:30:00",
    "data_mode": "full",
    "finviz_mode": "elite",
    "fmp_available": true,
    "max_themes": 14,
    "max_stocks_per_theme": 5,
    "data_sources": {
      "finviz_industries": 152,
      "yfinance_stocks": 68,
      "etf_volume": 24
    }
  },
  "summary": {
    "total_themes": 14,
    "bullish_count": 8,
    "bearish_count": 6,
    "top_bullish": "AI & Machine Learning",
    "top_bearish": "Regional Banks"
  },
  "themes": {
    "all": [
      {
        "name": "AI & Machine Learning",
        "direction": "bullish",
        "heat": 85.3,
        "maturity": 42.1,
        "stage": "Accelerating",
        "confidence": "Medium",
        "heat_label": "Hot",
        "industries": ["Software - Infrastructure", "Semiconductors"],
        "representative_stocks": [{"symbol": "NVDA"}, {"symbol": "MSFT"}],
        "proxy_etfs": ["BOTZ", "ROBO"],
        "theme_origin": "seed"
      }
    ],
    "bullish": [...],
    "bearish": [...]
  },
  "industry_rankings": {
    "top": [...],
    "bottom": [...]
  },
  "sector_uptrend": {...},
  "data_quality": {...}
}

Markdown レポート（theme_detector_YYYY-MM-DD_HHMMSS.md）：

• 並べ替え可能なランキングを含むテーマダッシュボード
• 強気・弱気テーマの詳細セクション
• 業種別パフォーマンスランキング
• セクターの上昇トレンド比率の概要
• 手法に関する注記

主な出力フィールド（テーマごと）：

フィールド	説明
heat	方向に依存しないテーマの強さ（0～100）
direction	"bullish"（LEAD）または "bearish"（LAG）
stage	Emerging / Accelerating / Trending / Mature / Exhausting
confidence	Low / Medium / High（スクリプトでは Medium が上限ですが、WebSearch によって引き上げられる場合があります）
representative_stocks	テーマを代表する上位銘柄（symbol と各種指標を含むオブジェクトのリスト）
proxy_etfs	テーマ別 ETF のティッカー（長さ = ETF 数。多いほど過密な取引の可能性が高まります）
theme_origin	"seed"（YAML 設定由来）または "discovered"（自動クラスタリングで発見）

---

リソース

スクリプトディレクトリ（scripts/）

主なスクリプト：

• theme_detector.py - メインのオーケストレータースクリプト

  • 業界データの収集、テーマの分類、スコアリングを調整します
  • JSON と Markdown の出力を生成します
  • 使用方法：python3 theme_detector.py [options]

• theme_classifier.py - 業界を複数セクターにまたがるテーマにマッピングします

  • cross_sector_themes.md からテーマ定義を読み込みます
  • テーマ単位の集計スコアを計算します
  • 構成業界から方向性（強気／弱気）を判定します
  • 表示マッピング：「bullish」→「LEAD」、「bearish」→「LAG」（report_generator.py::_direction_label() を参照）

• finviz_industry_scanner.py - FINVIZ の業界データを収集します

  • エリートモード：業界ごとの全銘柄データを含む CSV をエクスポートします
  • パブリックモード：レート制限付きでウェブスクレイピングを行います
  • 抽出項目：パフォーマンス、出来高、変化率、平均出来高、時価総額

• calculators/lifecycle_calculator.py - ライフサイクルの成熟度を評価します

  • 期間スコアリング、極端度のクラスタリング、バリュエーション分析
  • thematic_etf_catalog.md に基づく ETF の普及度スコアリング
  • ステージ分類：新興／加速／トレンド／成熟／衰退

• report_generator.py - レポート出力を生成します

  • テンプレートから Markdown レポートを生成します
  • 構造化された JSON 出力を生成します
  • テーマダッシュボードを整形します

参照ディレクトリ（references/）

ナレッジベース：

• cross_sector_themes.md - 業界、ETF、銘柄、照合基準を含むテーマ定義
• thematic_etf_catalog.md - テーマごとの件数を含む、包括的なテーマ ETF カタログ
• finviz_industry_codes.md - FINVIZ の業界とフィルターコードの完全な対応表
• theme_detection_methodology.md - 3D スコアリングモデルの技術ドキュメント

アセットディレクトリ（assets/）

• report_template.md - プレースホルダー形式を含むレポート生成用の Markdown テンプレート

---

重要な注意事項

FINVIZ モードの違い

機能	エリートモード	パブリックモード
業界の網羅範囲	約145の全業界	約145の全業界
業界あたりの銘柄数	全銘柄	約20銘柄（1ページ目）
レート制限	リクエスト間隔0.5秒	リクエスト間隔2.0秒
データの鮮度	リアルタイム	15分遅延
API キーが必要	はい（$39.50/月）	いいえ
実行時間	約2～3分	約5～8分

方向性の判定ロジック

テーマの方向性は、構成業界の相対順位による多数決で決まります。

1. 業界のランキング：約145の全業界を、複数の時間枠におけるモメンタムスコアで順位付けします
2. 順位に基づく方向性：ランキングの上位半分の業界を「強気」、下位半分を「弱気」に分類します
3. テーマの多数決：_majority_direction() が各テーマ内の強気業界と弱気業界を数え、多数派を採用します

表示マッピング：「bullish」→ LEAD、「bearish」→ LAG（report_generator.py::_direction_label() を参照）

LEAD テーマは、その構成業界が相対的に優れたパフォーマンスを示していることを意味します。LAG テーマの絶対リターンがプラスの場合もあります。これは相対的な低パフォーマンスを示すものであり、ショートシグナルではありません。

既知の制限事項

1. サバイバーシップバイアス：現在上場している銘柄と ETF のみを分析します
2. 遅延：FINVIZ のデータは、日中の値動きに対して15分遅れる場合があります（パブリックモード）
3. テーマの境界：複数のテーマに当てはまる銘柄もあります。分類には主要業界を使用します
4. ETF の普及度：カタログは静的なため、ごく最近の ETF が反映されていない場合があります
5. ナラティブスコアリング：WebSearch に基づいており、本質的に主観的です
6. パブリックモードの制限：業界あたり約20銘柄のため、小型株のシグナルを見落とす場合があります

免責事項

この分析は、教育および情報提供のみを目的としています。

• 投資助言ではありません
• 過去のテーマ別トレンドは、将来のパフォーマンスを保証するものではありません
• テーマの検出はモメンタムを特定するものであり、ファンダメンタル価値を示すものではありません
• 投資判断を行う前に、ご自身で調査してください

---

バージョン： 1.0 最終更新日： 2026-02-16 API 要件： FINVIZ Elite（推奨）またはパブリックモード（無料）；FMP API は任意 実行時間： モードに応じて約 2～8 分 出力形式： JSON + Markdown 対象テーマ： セクター横断型テーマ 14 件以上