goldenChart/ta4j-master/ta4j-examples/docs/btc-ew-macro-demo-guide.md

BTC Macro Elliott Demo Guide

ElliottWaveBtcMacroCycleDemo is now the BTC reporting wrapper over the unified core Elliott engine. The historical BTC macro study and the live BTC preset no longer rely on a preferred demo-local interpretation path.

What you can run

• Historical truth-set validation:
  • uses the ossified BTC daily dataset plus the locked BTC anchor registry
  • scores the candidate profiles against the major macro turns
  • emits the macro-cycle JSON report and regression chart
• Live BTC preset:
  • uses only the BarSeries you provide at runtime
  • infers the current-cycle start from that supplied window alone
  • emits the current-cycle JSON summary plus the base case and alternate charts

Canonical entrypoints

• Generic canonical demo:
  • ElliottWaveMacroCycleDemo
  • owns the series-native historical study, live preset, and shared chart/report rendering flow
• Stable BTC wrapper:
  • ElliottWaveBtcMacroCycleDemo
  • keeps fixed BTC resources, default filenames, and BTC-oriented entrypoints for users and regression tests
• Calibration and compatibility harness:
  • ElliottWaveAnchorCalibrationHarness
  • owns truth-target scoring, routine/targeted calibration artifacts, and the temporary legacy anchored comparison path

The important line is that the legacy-anchored study is no longer a first-class runtime demo. If you need legacy-versus-canonical comparison, use the harness artifacts rather than treating the old anchored path as a second production engine.

What stays the same

• The BTC demo still writes the same chart/report artifacts.
• The live preset still keeps compatibility with the existing file naming and reporting flow.

Which entrypoint to use

• Use ElliottWaveBtcMacroCycleDemo when you want the fixed ossified BTC dataset, the locked BTC truth registry, and the stable BTC artifact names.
• Use ElliottWaveMacroCycleDemo when you already have a BarSeries and want the canonical historical study or live preset without BTC-specific resource loading.
• Use ElliottWaveAnchorCalibrationHarness when you are calibrating, benchmarking, or comparing canonical output against the committed BTC truth target.

What changed

• Historical anchor-to-anchor fits and live current-cycle fits now come from the same core-ranked Elliott logic.
• The BTC truth set is the regression guardrail for the core engine, not a second “smarter BTC-only engine.”
• The preferred BTC answer is no longer a legacy local-structure path. If the wrapper remains, it is there to load BTC resources, choose the prevalidated default profile, and render outputs.

BTC truth target

The BTC anchor registry is now a calibration asset, not a runtime input. It encodes the committed macro truth target the canonical engine must learn to reproduce from price alone.

• Reference early segment:
  • 2011-06-09 top
  • 2011-11-18 low
  • calibration-only evidence, not production runtime structure
• Accepted validation cycle turns:
  • 2013-11-30 top, expected WAVE5
  • 2015-08-19 low, expected CORRECTIVE_C
  • 2017-12-18 top, expected WAVE5
  • 2018-12-16 low, expected CORRECTIVE_C
• Holdout cycle turns:
  • 2021-11-11 top, expected WAVE5
  • 2022-11-22 low, expected CORRECTIVE_C

The harness resolves broad committed registry windows against the ossified BTC daily dataset, then converts the distance from the resolved extremum to each window edge into toleranceBefore and toleranceAfter. That keeps acceptable match windows pinned to the committed truth target instead of drifting via runtime heuristics.

Runtime contract

• Runtime historical decomposition must not depend on the BTC anchor registry.
• Live current-cycle analysis must not depend on the BTC anchor registry.
• ElliottWaveMacroCycleDemo is the canonical runtime controller/view surface.
• ElliottWaveBtcMacroCycleDemo may remain as a thin BTC convenience wrapper, but it must not own distinct structure inference logic.
• The registry is valid only for:
  • offline calibration
  • offline regression
  • holdout scoring
  • debugging and evidence output
• If a runtime chart or report needs anchors to decide structure, that path is still not the canonical engine.

Maintainer note

• Treat the BTC anchor registry and ossified BTC dataset as validation assets for core Elliott behavior.
• When changing Elliott ranking, swing preservation, or current-cycle fitting, rerun the real BTC macro regression and compare:
  • selected profile / hypothesis
  • accepted historical cycles / segments
  • current wave
  • phase and structural invalidation output
• Historical truth-set validation answers “does core still explain the locked BTC cycle turns?”
• Live runtime analysis answers “what does the unified core engine infer from the bars supplied right now?”
• Prefer these operating modes when validating changes:
  • --targeted for fast BTC window checks
  • routine for the default full-history BTC sanity lane
  • --exhaustive only when you explicitly need the broader profile search and portability sweep

Release validation

Before shipping changes that touch the canonical macro-cycle flow, rerun both the focused BTC regression slice and the quiet full build:

mvn -q -pl ta4j-examples -am -Dsurefire.failIfNoSpecifiedTests=false \
  -Dtest=ElliottWaveBtcMacroCycleDemoTest,ElliottWaveMacroCycleTruthTargetScoringTest,ElliottWaveMacroCycleDetectorTest,ElliottWavePresetDemoTest \
  test

scripts/run-full-build-quiet.sh

The focused slice proves truth-target recovery, canonical historical/live reuse, and chart/report persistence. The quiet full build is the production gate.