goldenChat base source add

2026-05-23 15:11:48 +09:00
commit a4ea7762b5
2081 changed files with 1155760 additions and 0 deletions
@@ -0,0 +1,66 @@
+# ta4j-core
+
+`ta4j-core` contains the production API surface for strategy modeling, backtesting, analysis, and live-style record management.
+
+## Start here
+
+- Series model: `BarSeries`, `BaseBarSeries`, `ConcurrentBarSeries`
+- Strategy model: `Indicator`, `Rule`, `Strategy`
+- Execution model: `BarSeriesManager`, `BacktestExecutor`, `TradeExecutionModel`
+- Trade/fill model: `TradingRecord`, `BaseTradingRecord`, `Trade`, `TradeFill`
+- Analysis model: `AnalysisCriterion` and criteria packages
+
+## Choose the right execution path
+
+- Single strategy over one series: use `BarSeriesManager`
+- Many candidates, tuning, weighted ranking: use `BacktestExecutor`
+- Broker-confirmed/partial-fill replay: use manual evaluation loop + `BaseTradingRecord.operate(fill)`
+
+## Live evaluation semantics (important)
+
+- ta4j evaluates the bar state you provide at the requested index; it does not force closed-candle-only evaluation.
+- If your feed uses `addBar(bar, true)` or equivalent replace-last-bar updates, you are evaluating a live (still-forming) candle.
+- If you evaluate only after adding a completed bar, you are evaluating closed candles.
+- For live execution, call `shouldEnter(index, tradingRecord)` / `shouldExit(index, tradingRecord)` and keep `tradingRecord` synchronized with broker-confirmed fills.
+- Add an integration guard (for example, one entry per bar index) to avoid duplicate orders when a live candle keeps the same rule state across multiple updates.
+
+## Trace rule decisions
+
+- To answer "why did this fire?" or "why did this not fire?", enable SLF4J `TRACE` on the relevant `Rule` or `Strategy` logger and run the normal `isSatisfied(...)`, `shouldEnter(...)`, or `shouldExit(...)` call.
+- TRACE logging is the off switch; there is no mutable trace mode to set on shared rule or strategy instances.
+- Default trace output is `Rule.TraceMode.VERBOSE`, which emits the evaluated rule plus child-rule path/depth fields where a composite rule evaluates children.
+- Use `Rule#isSatisfiedWithTraceMode(..., Rule.TraceMode.SUMMARY)` or `Strategy#shouldEnterWithTraceMode(...)` / `shouldExitWithTraceMode(...)` for a one-shot parent summary when child logs would be too noisy.
+- Price and numeric comparison rules include the values they compared, the operator or window, and a short `reason` so a single rule trace line explains the decision.
+- Stop rules include flat `key=value` decision fields such as `currentPrice`, `entryPrice`, `stopPrice`, `side`, trailing extremes, and configured amount or percentage fields.
+
+## Choose the right series type
+
+- Single-threaded backtests and deterministic local runs: `BaseBarSeries`
+- Concurrent ingestion/evaluation pipelines: `ConcurrentBarSeries`
+
+## Choose the right numeric model
+
+- Precision-first workflows: `DecimalNum`
+- Throughput-first workflows with accepted floating-point tradeoffs: `DoubleNum`
+
+## Choose the right correlation metric
+
+All rolling correlation indicators live under
+`org.ta4j.core.indicators.statistics` and return `NaN` when the requested
+window is not ready or the statistic is undefined.
+
+| Question | Indicator | Notes |
+| --- | --- | --- |
+| Are two continuous signals linearly related in the same window? | `CorrelationCoefficientIndicator` | Pearson-style baseline for dense, simultaneous numeric series |
+| Is the relationship monotonic but not necessarily linear? | `SpearmanRankCorrelationIndicator` | Uses average ranks for ties before applying Pearson correlation |
+| Do ordered samples agree when ties matter? | `KendallTauIndicator` | Rolling Kendall tau-b with tie correction |
+| Does one signal lead or trail another by a fixed number of bars? | `LaggedCorrelationIndicator` | Positive lag means the first indicator leads the second |
+| Do two signals share non-linear structure? | `DistanceCorrelationIndicator` | Builds centered pairwise distance matrices; `O(window^2)` per calculated index |
+| Does knowing one discretized state reduce uncertainty about another? | `MutualInformationIndicator` | Equal-width bins for v1; reports natural-log mutual information in nats |
+| Does correlation only matter inside a trend, volatility, or custom state? | `RegimeSegmentedCorrelationIndicator` | Filters each rolling window with an `Indicator<Boolean>` regime selector |
+
+## Companion user guides
+
+- Backtesting: https://ta4j.github.io/ta4j-wiki/Backtesting.html
+- Live trading: https://ta4j.github.io/ta4j-wiki/Live-trading.html
+- Risk/criteria: https://ta4j.github.io/ta4j-wiki/Analysis-Criteria-and-Risk-Metrics.html