vcp-screener

VCP スクリーナー - Minervini のボラティリティ収縮パターン

S&P 500 銘柄を対象に、Mark Minervini のボラティリティ収縮パターン（VCP）をスクリーニングし、ブレイクアウトのピボットポイント付近でボラティリティが収縮しているステージ 2 上昇トレンド銘柄を特定します。

使用する場面

• VCP スクリーニングや Minervini 流のセットアップを求めている場合
• 引き締まったベース／ボラティリティ収縮パターンを見つけたい場合
• ステージ 2 のモメンタム銘柄のスキャンを依頼された場合
• リスクが明確なブレイクアウト候補を求めている場合
• 「 で過去に形成された VCP をすべて見つけて」と依頼された場合、または 1 銘柄の過去の VCP セットアップとその後の結果を調べたい場合（--history --ticker SYM）

前提条件

• FMP API キー（環境変数 FMP_API_KEY を設定するか、--api-key を渡します）
• 無料プラン（1 日 250 回の呼び出し）で、デフォルトのスクリーニング（上位 100 候補）には十分です
• S&P 500 全銘柄のスクリーニングには有料プランを推奨します（--full-sp500）

ワークフロー

ステップ 1：スクリーニングの準備と実行

VCP スクリーナースクリプトを実行します。

# Default: S&P 500, top 100 candidates
python3 skills/vcp-screener/scripts/screen_vcp.py --output-dir skills/vcp-screener/scripts

# Custom universe
python3 skills/vcp-screener/scripts/screen_vcp.py --universe AAPL NVDA MSFT AMZN META --output-dir skills/vcp-screener/scripts

# Full S&P 500 (paid API tier)
python3 skills/vcp-screener/scripts/screen_vcp.py --full-sp500 --output-dir skills/vcp-screener/scripts

厳格モード（Minervini の純粋なセットアップ）

valid_vcp=True かつ execution_state が (Pre-breakout, Breakout) の銘柄のみを返します。

python3 skills/vcp-screener/scripts/screen_vcp.py --strict --output-dir reports/

過去の単一銘柄モード

1 銘柄の複数年にわたる履歴を確認し、過去に形成されたすべての VCP を検出して、検出ごとにその後の結果の統計（ブレイクアウト／ストップ到達／期限切れ、結果までの日数、最大上昇率、最大下落率）を付加します。パターンの調査やバックテストの参考に役立ちます。リアルタイムスクリーナーではありません。

# Default: scan ~5 years (1260 trading days), 5-day stride, 60-day outcome window
python3 skills/vcp-screener/scripts/screen_vcp.py \
  --history --ticker FIX --output-dir reports/

# Custom scan length: 750 trading days (~3 years), 90-day outcome window
python3 skills/vcp-screener/scripts/screen_vcp.py \
  --history 750 --ticker TSLA \
  --stride-days 5 --outcome-days 90 \
  --output-dir reports/

# Long scan: 10 years (2520 trading days)
python3 skills/vcp-screener/scripts/screen_vcp.py \
  --history 2520 --ticker NVDA --output-dir reports/

出力（タイムスタンプ付き）：

• vcp_history_<SYM>_<YYYY-MM-DD_HHMMSS>.json — 検出の全履歴と、各検出の完全なアナライザーペイロードおよび forward_outcome、さらに概要統計。
• vcp_history_<SYM>_<YYYY-MM-DD_HHMMSS>.md — 人が読みやすい形式の履歴。

モード固有のフラグ：

パラメーター	デフォルト	範囲	効果
--history [DAYS]	（オフ）／引数なしの場合は 1260	100-5040	過去履歴モードを有効化します。任意で取引日のスキャン期間を指定します（--ticker が必要です）
--ticker SYM	—	—	スキャンするティッカー
--stride-days	5	1-60	基準日カーソル位置間の取引日ステップ
--outcome-days	60	5-252	検出ごとに評価する将来の期間

注意：

• スキャンごとに必要な FMP API 呼び出しは 2 回（ティッカーと SPY の履歴）で、横断的なパイプラインのように 100 回以上は必要ありません。
• marketCap と絶対 RS パーセンタイルは、スクリーニング対象銘柄群との比較ではなく、対象銘柄単体を基準としています。このレポートはパターンの調査に使用し、ポートフォリオの配分判断には使用しないでください。
• 同じ VCP がカーソルの進行に伴って繰り返し報告されないよう、検出結果は (T1_high_date, last_low_date, pivot) で重複排除されます。

高度な調整（バックテスト用）

調査やバックテストのために、VCP 検出パラメーターを調整します。

python3 skills/vcp-screener/scripts/screen_vcp.py \
  --min-contractions 3 \
  --t1-depth-min 12.0 \
  --breakout-volume-ratio 2.0 \
  --trend-min-score 90 \
  --atr-multiplier 1.5 \
  --output-dir reports/

パラメーター	デフォルト	範囲	効果
--min-contractions	2	2-4	値を大きくすると、パターン数は減りますが品質が高まります
--t1-depth-min	10.0%	1-50	値を大きくすると、浅い第 1 調整局面が除外されます
--breakout-volume-ratio	1.5x	0.5-10	値を大きくすると、出来高確認の条件が厳しくなります
--trend-min-score	85	0-100	値を大きくすると、ステージ 2 フィルターが厳しくなります
--atr-multiplier	1.5	0.5-5	値を小さくすると、スイング検出の感度が高まります
--contraction-ratio	0.70	0.1-1	値を小さくすると、より引き締まった収縮が必要になります
--min-contraction-days	5	1-30	値を大きくすると、収縮の最小期間が長くなります
--lookback-days	120	30-365	値を大きくすると、より古いパターンが見つかります
--max-sma200-extension	50.0%	—	過度な上昇状態とペナルティを判定する SMA200 からの距離のしきい値
--wide-and-loose-threshold	15.0%	—	最終収縮の深さがこの値を超えると、幅広で緩いパターンのフラグが立ちます
--strict	オフ	—	Minervini 厳格モード：有効な VCP を伴う Pre-breakout または Breakout のみ

ステップ 2：結果の確認

1. 生成された JSON レポートと Markdown レポートを読みます
2. パターン解釈の参考情報として references/vcp_methodology.md を読み込みます
3. スコアのしきい値に関する指針として references/scoring_system.md を読み込みます

ステップ 3：分析結果を提示する

各有力候補について、次の情報を提示します。

• 品質（composite_score／評価）— VCP パターンがどの程度適切に形成されているか
• 実行状態（execution_state）— 今すぐ購入可能か（Pre-breakout／Breakout はアクション可能）
• パターンタイプ（pattern_type）— 教科書的な VCP／VCP に近いパターン／ブレイクアウト後／上昇が続く銘柄／損傷あり
• State Cap が適用された場合（元のスコアが引き下げられた場合）は ★ マーカー
• 収縮の詳細（T1／T2／T3 の深さと比率）
• トレード設定：ピボット価格、損切り価格、リスク率
• 出来高の枯渇比率と breakout_volume_score
• 相対力強度ランク

ステップ 4：実行可能なガイダンスを提示する

実行状態別（優先フィルター）：

• Pre-breakout／Breakout： パターンは有効なエントリー期間にあります。評価に基づいてポジションサイズを設定します
• Early-post-breakout： ブレイクアウトが進行中ですが、理想的なエントリーポイントを上回っています。ポジションサイズを減らすか、押し目を待ちます
• Extended／Overextended： トレードの機会を逃しています。次のベース形成に備えてウォッチリストに追加します
• Damaged／Invalid： セットアップは無効です。エントリーしないでください

評価別（実行可能性を状態で確認した後の二次判断）：

• 教科書的な VCP（90 以上）： ピボットで買い、積極的なポジションサイズ（1.5～2 倍）
• 強い VCP（80～89）： ピボットで買い、標準のポジションサイズ（1 倍）
• 良好な VCP（70～79）： ピボットを上回り、出来高で確認できたら買い（0.75 倍）
• 形成中（60～69）： ウォッチリストに追加し、さらに収縮するのを待ちます
• 弱い／VCP なし（60 未満）： 監視のみ、または見送ります

3 フェーズのパイプライン

1. 事前フィルター - 株価、出来高、52 週レンジに基づくスクリーニング（約 101 回の API 呼び出し）
2. トレンドテンプレート - 260 日分の履歴を使用した 7 項目の Stage 2 フィルター（約 100 回の API 呼び出し）
3. VCP 検出 - パターン分析、スコアリング、レポート生成（追加の API 呼び出しなし）

出力

• vcp_screener_YYYY-MM-DD_HHMMSS.json - 構造化された結果
• vcp_screener_YYYY-MM-DD_HHMMSS.md - 人が読める形式のレポート

リソース

• references/vcp_methodology.md - VCP 理論とトレンドテンプレートの解説
• references/scoring_system.md - スコアのしきい値と構成要素の重み
• references/fmp_api_endpoints.md - API エンドポイントとレート制限