Swing strategy configuration

Swing metrics inside the zone analysis pipeline can now be tuned explicitly through presets or derived dynamically from the zone price range. This guide shows how to apply both options when orchestrating a run.

Applying a preset

bquant.core.config.SWING_PRESETS bundles consistent parameter sets for the ZigZag, Find Peaks, and Pivot Points strategies. Use ZoneAnalysisPipeline.with_swing_preset() (or the builder shortcut) to deploy one of the presets across all swing components before triggering the analysis.

from bquant.analysis.zones import analyze_zones
from bquant.data.samples import get_sample_data

df = get_sample_data("tv_xauusd_1h").set_index("time")

result = (
    analyze_zones(df)
    .with_cache(enable=False)
    .with_indicator("custom", "macd", fast_period=12, slow_period=26, signal_period=9)
    .detect_zones("zero_crossing", indicator_col="macd_hist")
    .with_strategies(swing="zigzag")
    .with_swing_preset("narrow_zone")
    .analyze(clustering=False)
    .build()
)

bull_zones = [zone for zone in result.zones if zone.type == "bull"]
print(bull_zones[0].features["metadata"]["swing_metrics"])  # preset parameters propagate here

The example above switches the pipeline to the narrow_zone preset, tightening ZigZag legs/deviation and the complementary thresholds so narrow bands register swing pivots.

Enabling adaptive thresholds

When working with instruments that span a wide price range, enable adaptive thresholds to recompute ZigZag deviation and prominence values on a per-zone basis. The fluent builder exposes .with_auto_swing_thresholds(True) while the ZoneAnalysisPipeline constructor provides the underlying strategy_auto_thresholds flag.

from bquant.analysis.zones.pipeline import ZoneAnalysisConfig, ZoneAnalysisPipeline

pipeline = ZoneAnalysisPipeline(
    config=my_config,
    enable_cache=False,
    strategy_auto_thresholds=True,
    auto_threshold_base_deviation=0.01,
)
pipeline.with_swing_preset("default")  # optional baseline
result = pipeline.run(df)

Adaptive mode falls back to the preset parameters whenever the computed range is smaller than auto_threshold_base_deviation, ensuring stability across thin zones. Combine the toggle with JSON exports from research/notebooks/validate_swing_pivots.py to compare KPI shifts before rolling the changes into production.