aidev
67 lines
4.4 KiB
Markdown
67 lines
4.4 KiB
Markdown
# 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
|