downtrend-duration-analyzer

下降トレンド期間分析ツール

概要

過去の価格データを分析して下降トレンド期間（ピークから谷まで）を特定し、調整期間の統計的な分布を作成します。セクターおよび時価総額別に区分したヒストグラムを含むインタラクティブな HTML ビジュアライゼーションを生成し、トレーダーが一般的な回復期間を把握し、平均回帰戦略に現実的な見通しを立てられるようにします。

使用するタイミング

• トレーダーが、特定のセクターまたは時価総額区分における一般的な調整期間について尋ねている
• ユーザーが過去のドローダウンからの回復期間を把握したい
• 現実的な保有期間の推定が必要な平均回帰戦略や押し目買い戦略を構築する
• 異なる市場セグメント間で調整の動きを比較する
• 損切りのタイムアウトやポジション保有期間の上限を設定する

前提条件

• Python 3.9+
• FMP API キー（環境変数 FMP_API_KEY を設定するか、--api-key を使用）
• 必要なパッケージ：requests、pandas、numpy（標準的なデータ分析スタック）

ワークフロー

ステップ 1: 過去の価格データを取得する

分析スクリプトを実行し、銘柄ユニバースの OHLC データを取得して下降トレンド期間を特定します。

python3 skills/downtrend-duration-analyzer/scripts/analyze_downtrends.py \
  --sector "Technology" \
  --lookback-years 5 \
  --output-dir reports/

ステップ 2: 下降トレンド期間を分析する

スクリプトは自動的に次の処理を行います。

1. ローリングウィンドウ分析で局所的なピークと谷を特定する
2. 各下降トレンドの期間（取引日数）と下落幅（下落率）を計算する
3. セクターおよび時価総額区分（メガ、ラージ、ミッド、スモール）別に結果を分類する
4. 要約統計量（中央値、平均値、パーセンタイル）を算出する

ステップ 3: インタラクティブな HTML ビジュアライゼーションを生成する

python3 skills/downtrend-duration-analyzer/scripts/generate_histogram_html.py \
  --input reports/downtrend_analysis_*.json \
  --output-dir reports/

これにより、次の内容を含むインタラクティブな HTML ファイルが作成されます。

• 下降トレンド期間のヒストグラム
• セクターと時価総額のフィルター
• パーセンタイル情報を含むホバーツールチップ
• 要約統計量テーブル

ステップ 4: 分布から得られる知見を確認する

生成された Markdown レポートを読み込み、結果を解釈します。

• 短期の調整（5～15 日）：上昇トレンド中に一般的な押し目
• 中期の調整（15～40 日）：標準的なセクターローテーション
• 長期の調整（40 日以上）：トレンド転換または弱気相場

出力形式

JSON レポート

{
  "schema_version": "1.0",
  "analysis_date": "2026-03-28T07:00:00Z",
  "parameters": {
    "lookback_years": 5,
    "sector_filter": "Technology",
    "peak_window": 20,
    "trough_window": 20
  },
  "summary": {
    "total_downtrends": 1234,
    "median_duration_days": 18,
    "mean_duration_days": 24.5,
    "p25_duration_days": 10,
    "p75_duration_days": 32,
    "p90_duration_days": 55
  },
  "by_sector": {
    "Technology": {
      "count": 456,
      "median_days": 15,
      "mean_days": 20.3
    }
  },
  "by_market_cap": {
    "Mega": {"count": 200, "median_days": 12},
    "Large": {"count": 300, "median_days": 16},
    "Mid": {"count": 400, "median_days": 22},
    "Small": {"count": 334, "median_days": 28}
  },
  "downtrends": [
    {
      "symbol": "AAPL",
      "sector": "Technology",
      "market_cap_tier": "Mega",
      "peak_date": "2025-01-15",
      "trough_date": "2025-02-10",
      "duration_days": 18,
      "depth_pct": -12.5
    }
  ]
}

Markdown レポート

# Downtrend Duration Analysis

**Date**: 2026-03-28
**Lookback**: 5 years
**Sector**: Technology

## Summary Statistics

| Metric | Value |
|--------|-------|
| Total Downtrends | 1,234 |
| Median Duration | 18 days |
| Mean Duration | 24.5 days |
| 25th Percentile | 10 days |
| 75th Percentile | 32 days |
| 90th Percentile | 55 days |

## By Market Cap Tier

| Tier | Count | Median | Mean |
|------|-------|--------|------|
| Mega ($200B+) | 200 | 12 days | 15.2 days |
| Large ($10-200B) | 300 | 16 days | 20.1 days |
| Mid ($2-10B) | 400 | 22 days | 28.4 days |
| Small (<$2B) | 334 | 28 days | 35.6 days |

## Key Insights

1. Larger companies recover faster from corrections
2. Technology sector shows shorter median correction than market average
3. 90% of corrections resolve within 55 trading days

HTML ビジュアライゼーション

インタラクティブなヒストグラムは reports/downtrend_histogram_YYYY-MM-DD.html に保存されます。次の内容を含みます。

• Plotly.js ベースのインタラクティブなチャート
• セクターと時価総額のドロップダウンフィルター
• ビン設定で調整できる期間分布
• パーセンタイルマーカー（P25、P50、P75、P90）

レポートは reports/ に次のファイル名で保存されます。

• downtrend_analysis_YYYY-MM-DD_HHMMSS.json
• downtrend_analysis_YYYY-MM-DD_HHMMSS.md
• downtrend_histogram_YYYY-MM-DD_HHMMSS.html

リソース

• scripts/analyze_downtrends.py -- データ取得と下降トレンド期間の算出を行うメイン分析スクリプト
• scripts/generate_histogram_html.py -- インタラクティブなヒストグラムを備えた HTML ビジュアライゼーション生成ツール
• references/downtrend_methodology.md -- ピークと谷の検出アルゴリズムおよび時価総額区分の定義

重要な原則

1. 統計的な厳密さ：ノイズによる誤検知を避けるため、堅牢なピークと谷の検出を使用します
2. 分類は重要です：常にセクターと時価総額別に分析します。平均値だけでは重要な違いが見えなくなります
3. 現実的な見通し：結果の分布全体を把握するには、平均値だけでなくパーセンタイルを使用します