ta4j Files

0.25.0 (2026-09-07)

Breaking

• morning/evening stars, three-black-crows, and three-white-soldiers lose their ratio/factor constructors; migrate to the default or (series, averagePeriod) forms ((series, averagePeriod, penetration) for stars).
• harami, kicker, dark-cloud-cover, and piercing-line lose their threshold/configuration constructors; harami and kicker replace their (series, Num) configuration constructors with (series, averagePeriod) overloads, and dark-cloud-cover and piercing-line replace their (series, Num, Num, Num) body-threshold, gap-threshold, and penetration-threshold constructors with (series, averagePeriod, penetration); engulfing construction is unchanged. DarkCloudIndicator/PiercingIndicator are deprecated; use DarkCloudCoverIndicator/PiercingLineIndicator.
• doji, marubozu, hammer, hanging man, inverted hammer, and shooting star lose their ratio/configuration constructors; migrate to (series, averagePeriod) forms ((series, averagePeriod, rangeFactor) for doji).
• RealBodyIndicator is deprecated; use CandleBodyIndicator plus Bar#isBullish()/Bar#isBearish() for direction.

• BaseBar now rejects OHLC candles whose high/low contradict their open/close.

• Expected failure diagnostics stay off the test console: failure-ledger (BacktestExecutor) and walk-forward synthetic-failure tests now silence their intentionally triggered WARN stack traces through the test logging configuration, keeping mvn verify output focused on real failures.

• Unified parameter research pipeline (CF-455): Added ParameterResearch, a budget-exact hyperparameter search workflow: typed integer, decimal, boolean, and categorical domains feed seeded grid, genetic, and particle-swarm engines (SearchPlan.grid / genetic / particleSwarm) through one objective seam with per-candidate metrics and explicit invalid/failure outcomes. A run-local cache keeps duplicates, cache hits, and re-proposed elites from consuming the unique-evaluation budget; an optional holdout window rebuilds and rescores the top-K training candidates out of sample; deterministic leaderboards and a TerminationReason-carrying report make every run reproducible. SimpleMovingAverageRangeBacktest demonstrates a backtest-style objective and RelationshipObjectiveSearchExample tunes a synchronization-F1 event-relationship objective with a one-line grid/GA/PSO switch.

• Advanced lead/lag, DTW, and event-dependence analysis (CF-454): Added LeadLagCorrelationIndicator, which scans an inclusive lag range and reports every best lag plus one deterministic selection in its full Profile; DynamicTimeWarpingDistanceIndicator, a bounded two-row-DP shape distance with z-score or raw normalization, an explicit Sakoe–Chiba band (unconstrained opt-in), and exact path-length normalization; and EventMutualInformationEvaluator, which measures how much a continuous predictor reduces uncertainty about a sparse Boolean event in an explicit future-bar window (raw/normalized MI in nats, target entropy, prevalence). Equal-frequency binning never splits tied predictor values, and target windows never cross the evaluation partition boundary.

• Windowed event synchronization and F1 evaluation (CF-453): Added EventSynchronizationIndicator, a rolling Indicator<Num> that matches two sparse Boolean event streams one-to-one within asymmetric lead/lag tolerances (maximum cardinality first, then minimum lag cost, then deterministic ties) and reports each trailing window's F1 score, with precision/recall/match-offset/unmatched diagnostics via getResult(index). Values are NaN until the window is fully available, windows never cross series boundaries so train/validation splits stay isolated, and a Net Momentum × ZigZag confirmation example ships with a 100,000-bar benchmark fixture.

• Robust correntropy Kalman smoothing with measurement weights (CF-558): Added CorrentropyKalmanFilterIndicator, a covariance-whitened maximum-correntropy-criterion (MCC) Kalman filter that solves the bounded fixed-point update of Chen et al. (2017) for ta4j's scalar random-walk state model. The kernel bandwidth is dimensionless and the source-unit-squared process/measurement noise variances may be dynamic indicators; measurements beyond the kernel's saturation bound are rejected outright instead of biasing the estimate, and non-converging updates yield NaN until the recursion recovers. CorrentropyKalmanWeightIndicator exposes the per-measurement kernel weight in [0, 1] (zero marks a rejected measurement) as a cached view that shares the filter's recursive state without rerunning the iteration.

• Event synchronization keeps rolling windows evicting at any window width (CF-453): the rolling event caches now cap their eviction threshold at half the matcher capacity, so a first evaluation far ahead of the current scan frontier with a window wider than the cache's growth ceiling still evicts stale events instead of throwing from the events-array capacity limit.

• RoMaD reports representation-neutral values for open positions: ReturnOverMaxDrawdownCriterion now returns the configured return representation's neutral value (for example, 1.0 under MULTIPLICATIVE) when a position is null or still open, consistent with its no-drawdown conversion path, instead of always returning zero.
• Pearson correlation stays well-defined on evicted windows: once bar eviction advances the series begin index, PearsonCorrelationIndicator normalizes by the number of retained values actually iterated rather than the requested window size, so partial windows keep producing valid correlations; warm-up behavior is unchanged.

• Lead/lag and event-dependence analysis hardened (CF-454): Pearson correlation now rescales and centers its window math, so extreme-but-finite values no longer overflow into undefined correlations and near-endpoint windows keep their deviations; z-score DTW normalization applies the same anchoring; equal-width event-MI bins handle subnormal and overflowing spans without shifting samples between bins; DTW path selection treats undefined predecessor cells as unreachable instead of reporting NaN on squared-cost underflow; and event-mutual-information evaluation returns undefined results for empty series and array-ceiling windows instead of throwing.

• Paired-window statistics indicators bound their sample windows (CF-454): CorrelationWindowSupport now rejects window lengths above ten million bars up front, so a hostile or mistyped window cannot allocate hundreds of megabytes of Num scratch arrays before the first evaluation; DTW distance keeps its stricter one-million-bar bound.

• Event synchronization honors retained-head warm-up and rejects far-out-of-domain requests (CF-453): the rolling event caches treat a source's unstable count as bars after the series' retained head (matching the anchoring convention of the other rolling statistics), so evaluation on trimmed or moved series no longer reads a source's unavailable lookback or caches its warm-up values; and getResult computes its window start in long and gates on the series domain first, so an extreme index such as Integer.MIN_VALUE reports an unavailable window instead of wrapping into one that throws from the event slice.
• Monte Carlo forecast techniques are swappable: MonteCarloReturnProjectionIndicator and MonteCarloPriceForecastIndicator accept a custom sampling technique through the new builder .monteCarloMethod(...) hook, backed by the public org.ta4j.core.analysis.montecarlo API (MonteCarloMethod, MonteCarloContext, and stock ShockPathMonteCarloMethod). The engine keeps gating, lookback-window construction, seeding, quantiles, and price mapping, while a technique returning null, a wrong sample count, or non-finite or foreign-precision samples degrades to an unstable forecast normalized through the series' NumFactory. Legacy seeded shock-path outputs are unchanged.

• Smoothed bootstrap shocks and Normal-Inverse-Gamma posterior-predictive forecasts: MonteCarloReturnProjectionIndicator.ShockModel.SMOOTHED_EMPIRICAL resamples Gaussian-kernel-smoothed standardized residuals with Silverman's reference bandwidth, extrapolating tails beyond the observed support and degenerating exactly to the standardized empirical sampler when the bandwidth collapses. New NormalInverseGammaForecastMethod samples horizon paths from the conjugate Normal-Inverse-Gamma posterior predictive of the lookback window, defaulting to data-driven weakly-informative priors and accepting explicit prior mean, strength, shape, and scale hyperparameters.

• AI release scheduling now weighs release recency against pending changes: release-scheduler.yml passes the last release's tag, creation date, and release link into the AI decision prompt. Recency is a judgment call instead of a fixed cooldown: the model defers (should_release=false) when the unreleased delta does not justify another release this soon, and the cadence input is omitted entirely when no prior release exists.

• Backtests isolate per-strategy failures instead of aborting the batch: BacktestExecutor records each strategy's runtime failure during evaluation and top-K ranking, keeps evaluating the remaining strategies, and throws only when every strategy fails, so one broken strategy no longer voids a whole scan. StopLimitExecutionModel synchronizes its pending/rejected order maps for safe sharing across parallel strategy batches.
• Walk-forward runs isolate per-fold failures and report them: WalkForwardEngine and StrategyWalkForwardExecutor record failed folds as FoldFailure entries and continue the remaining folds, while WalkForwardTuner skips failed candidates and WalkForwardLeaderboard reports a failedCount alongside kept and evaluated counts. WalkForwardConfig.configHash() now returns a collision-safe 64-character SHA-256 key instead of a truncated 32-bit hash, so persisted manifest keys from the old format must be regenerated. Undefined WalkForwardMetric values (clamp01, binaryF1) pass NaN through instead of coercing to zero.
• Statistics and rule lookback windows anchor at the series begin index: rolling statistics indicators (CovarianceIndicator, CorrelationCoefficientIndicator, MeanDeviationIndicator, PearsonCorrelationIndicator, SimpleLinearRegressionIndicator, StandardErrorIndicator, VarianceIndicator, SMAIndicator) and rules (AndWithThresholdRule, OrWithThresholdRule, ChainRule, IsRisingRule, IsFallingRule, RuleCopies) now anchor their windows at getBeginIndex() so trimmed or moved series compute over the retained bars, and clamp at zero for empty series.
• Stop rules report unavailable prices instead of failing: FixedAmountStopGainRule, FixedAmountStopLossRule, TrailingFixedAmountStopGainRule, and TrailingFixedAmountStopLossRule return false with a priceUnavailable trace reason and a null stop price when the entry, current, or extreme price is NaN or absent. TimeRangeRule rejects inverted ranges (from after to) at construction.
• Serialization fails loud on unresolvable types and non-finite parameters: StrategySerialization, IndicatorSerialization, and RuleSerialization now throw exceptions naming the offending type instead of silently substituting BaseStrategy or serializing NaN/infinite numeric parameters, and BarSeriesUtils.sortBarsByTime uses a stable comparator.
• VaR and expected-shortfall criteria share one tail-selection implementation: a package-private RiskTailSupport consolidates tail logic, ReturnOverMaxDrawdownCriterion always reports 1-based multiplicative values, and PositionsRatioCriterion honors its configured return representation at position level.
• Wyckoff and Renko transient caches follow series revisions: RenkoCounter and the Wyckoff detectors and tracker reconcile their index-keyed transient state against the series revision journal, so replaced-history edits and removed prefixes no longer leave stale signals.
• Elliott invalidation levels fold per scenario direction: ElliottInvalidationLevelIndicator computes bullish and bearish invalidation independently and resolves them against the close price instead of emitting one mixed-direction level.
• Bar and numeric contracts are validated: BaseBar rejects high-below-low prices, negative volume/amount, and negative trade counts. DecimalNum.hashCode() is now scale-insensitive to match its compareTo-based equals, and DoubleNum.equals is exact, consistent with compareTo and hashCode.
• Candle pattern indicators warm up consistently: ten pattern indicators now propagate their trend indicator's unstable-bar count, and ThreeBlackCrowsIndicator and ThreeWhiteSoldiersIndicator guard their warm-up windows.
• Analysis summaries define undefined moments: SampleSummary.sampleVariance(), sampleSkewness(), and sampleKurtosis() return NaN instead of a misleading zero when undefined, WeightedValue performs factory-safe weight/value conversion that preserves BigDecimal precision and throws on over/underflow, and SwingDetectorResult validates pivot/swing consistency on construction.
• Rule registration and named strategies remove atomically: NamedStrategy.unregisterImplementation removes registrations by full identity, so a class sharing a simple name from another package can no longer remove the wrong registration.
• Candle pattern foundation: shared adaptive thresholds: The replacement candle patterns share one consistent, causal, cached body/shadow sizing model, with documented runnable composition examples; the replacement patterns no longer apply ADX trend gates or hidden trend requirements, while the deprecated DarkCloudIndicator and PiercingIndicator compatibility indicators keep their trend gates.
• Stochastic and Klinger indicators discard their caches when the series head advances: the conditional flat-window carry no longer keeps pre-advance values on bounded series, so reads after the begin index moves recompute from the retained window instead of serving results computed from evicted bars. CachedIndicator exposes minimumCacheableIndexAfterHeadAdvance(int) so conditionally recursive indicators can opt into full-cache eviction; Klinger's trend direction and cumulative measurement apply it so an equal-basis carry cannot resurrect a direction computed from evicted bars.
• Stochastic and Klinger caches rebuild consistently after head advances: StochasticIndicator extends RecursiveCachedIndicator, so a fully evicted cache on a long flat retained window is rebuilt by the iterative prefill instead of a recursion deep enough to overflow the stack; and the Klinger volume oscillator evicts its whole downstream chain (volume force, both EMAs, and the outer oscillator) when the head advances, so post-advance reads cannot mix rebaselined cumulative measurements with stale pre-advance tail values.
• Doji thresholds decide body overflow consistently: with a finite prior-average range, an upward-overflowed threshold qualifies every body as a doji, including a body whose finite operands overflowed the numeric type, while a body missing because its inputs are genuinely unavailable stays conservatively not a doji.
• Overflowed candle magnitudes stay decidable: CandleThresholdSupport body and shadow classifiers no longer reject every non-finite measurement outright. A magnitude that overflows finite operands (for example a DoubleNum body spanning -Double.MAX_VALUE to Double.MAX_VALUE) still participates in the strict comparison, mirroring CandleBodyIndicator's operand-finiteness contract, while unavailable (NaN) measurements are never classified.
• SMMA, TR, ATR, and Keltner chains rebuild from the retained head after eviction: SMMAIndicator restarts its chained average at the series begin index instead of keeping averages seeded before the advance, TRIndicator evicts the stale head entry so the first retained bar recomputes as high-minus-low, and ATRIndicator and the Keltner channel middle line re-anchor on those rebaselined inputs, so post-advance reads never serve values computed from evicted bars.
• Hammer and hanging-man near-swing comparisons share the threshold model: CandleThresholdSupport exposes a package-private isNear(int, Num, Num) comparison that both patterns apply to their prior-swing proximity checks, keeping those decisions on the shared half-scale body/shadow sizing model instead of re-derived, polarity-flipped logic.
• Head-advance cache floors preserve unaffected values: RecursiveCachedIndicator defaults to retaining recursive histories, while fixed-window VolumeIndicator uses its ordinary unstable floor and calendar pivot points use a bounded current/next-period floor through CachedIndicator rather than clearing an entire cache or invoking recursive prefill. Indicators with genuinely recursive or cumulative state still opt into broader invalidation.
• Candle patterns normalize signed zero in gap, containment, and engulfing comparisons: dark-cloud-cover, piercing-line, harami, kicker, engulfing, morning-star, evening-star, and three-white-soldiers indicators no longer let the zero sign bit decide a match, so numerically equal endpoints behave identically on every Num implementation: DoubleNum orders -0.0 below +0.0, and the strict gap and anti-engulfing checks guard both-zero operands while the inclusive containment and engulfing checks treat both-zero endpoints as equal.
• Candle decisions and dependent caches retain precision under live inputs: standard one-tenth doji comparisons use the shared fused raw threshold; strict short-body ties are rechecked from canonical decimal values; dark-cloud-cover, piercing-line, morning-star, and evening-star use overflow-safe weighted endpoints; and CachedIndicator fingerprints a cross-series terminal bar so in-place price/trade changes invalidate dependent values.
• Candle indicator foundation: shared adaptive thresholds: Candle patterns now size bodies and shadows against recent history through one shared, cached model, keeping every pattern consistent and avoiding duplicate computation.
• Statistical process control monitors drift, volatility, and process capability: Added CusumIndicator, a winsorized one-sided CUSUM for detecting downward drift in residuals or returns (target mean, allowance, outlier clip factor, and scale decay are constructor-tunable; non-finite bars carry the previous statistic forward), and EwmaVarianceIndicator, an EWMA variance seeded from rolling population variance that self-heals after gap bars and composes with NumericIndicator into a dynamic control limit. ProcessCapabilityPositionSizer dampens position size inversely with a capability statistic evaluated at the entry bar (baseAmount / (1 + max(0, S/H)), fail-open to the base amount on non-finite statistics), and ProcessCapabilityCriterion ranks strategies by Cpk over closed-position gross returns with one- or two-sided specification limits, returning zero for empty records or zero-dispersion processes. All capability and deviation arithmetic is scale-aware: deviations are normalized against the largest magnitude before subtraction and squaring, and capability ratios are computed entirely in the deviation-normalized domain — same-sign mean-to-limit distances are subtracted before scaling so close limits keep their positive distance, and opposite-sign operands are scaled before subtracting — so extreme-but-finite returns never overflow or underflow into a zero or non-finite score. Specification limits that overflow the active representation are normalized against the deviation scale in raw decimal space before conversion, so a finite limit such as -1e400 on a DoubleNum series still yields its representable Cpk. CusumIndicator also validates scaleDecay against its raw pre-conversion value through exact BigDecimal comparison rather than double narrowing, and converts the 1 - scaleDecay complement in raw space, so in-range decays that a low-precision NumFactory rounds to a boundary, or that doubleValue() collapses to zero, are still accepted, and the separately converted complement is carried into the deviation-scale recursion so it is never recomputed from the already rounded decay and keeps a meaningful EWMA weight, and EwmaReturnForecastStateIndicator now reads its mean from the variance indicator's own estimator, keeping mean, drift, and variance consistent when a retained-head prune re-anchors the EWMA recursions, and invalidates its own state and observation-count caches on prune and re-anchors the count recursion at the retained head, so retained-index reads never return pre-prune moments or counts. The spec's kill switch needs no new rule type: NumericIndicator.of(cusum).isGreaterThan(limit) or OverIndicatorRule against a dynamic h * sqrt(variance) limit halts deployment at the boundary. The sizer coerces the statistic and the base amount through the backtest context’s exact NumFactory configuration rather than a class-level match, so distinct DecimalNum precisions cannot leak through sizing arithmetic. Into a BigDecimal-backed context the statistic and the base amount are coerced through their BigDecimal delegate, so magnitudes beyond the double range (for example a 1e400 statistic) size at the exact damped amount instead of the double-overflow epsilon floor. The raw scaleDecay now survives descriptor and JSON reconstruction as an exact BigDecimal even when a coarse NumFactory rounds the working copy to its boundary, and the winsorization ceiling probes the factory for the largest finite magnitude it can represent, falling back to the float range for float-backed delegates so the documented finite saturation holds for every factory. Likewise the capability ratios of ProcessCapabilityCriterion divide a limit that overflows the factory by the complete three-sigma denominator before narrowing and fall back to a single product denominator when an intermediate scale division overflows, so a representable Cpk stays finite, and the forecast observation count restarts past the retained head's artificial lookback zero so it always matches the observations folded into its moments.
• Subnormal SPC updates combine convex terms once: CusumIndicator's deviation-scale recursion and EwmaVarianceIndicator's shared mean and variance recursion now recombine exact finite operands whenever a low active-grid result—or, for a recursive mean or scale, its finite difference-form delta—can misround, including the minimum-normal boundary and one active-grid ULP above it for float-backed Num implementations. Recovery derives its first coefficient from the actually applied complement rather than separately rounded weights, preventing wrong control scales, means, or variances while preserving the fast difference form above the guard band.
• EWMA reanchors recursive values at retained heads: AbstractEMAIndicator seeds the recursion with the current value at the first addressable bar (index == beginIndex, reachable only when unstable bars are zero), so EWMAIndicator with barCount == 1 no longer throws StackOverflowError chasing getValue(index - 1) below the head. When a bounded series advances its retained head, all cached EMA values are invalidated and rebuilt from that head, so later-index reads cannot expose a pre-pruning recurrence or look ahead past retained warm-up bars.
• Cpk decimal recovery retains configured precision: ProcessCapabilityCriterion now carries a finite DecimalNum factory math context through raw limit recovery instead of collapsing results to DECIMAL128; DoubleNum and unlimited decimal contexts retain the safe DECIMAL128 division fallback.
• Cpk variance retains small scaled deviations: ProcessCapabilityCriterion now uses compensated accumulation for scaled squared deviations, so a low-precision DecimalNum no longer loses small variance terms merely because they follow large closed-position returns.
• SPC extreme-value and retained-head recovery stays exact and bounded: CusumIndicator and EwmaVarianceIndicator serialize retained-head resets with their full recursive reads to prevent prune-time lock inversion; CUSUM combines raw target and allowance parameters before narrowing, Cpk recovers over/underflowing finite returns and overflowing finite-return means in decimal space, and EWMA seed windows use overflow-safe counters through Integer.MAX_VALUE.
• SPC raw numeric inputs preserve magnitude and polarity: ProcessCapabilityPositionSizer validates arbitrary Number implementations for finite values before decimal conversion while retaining lossless BigDecimal/BigInteger inputs; CUSUM keeps the raw clipping factor through sign validation and scale multiplication; all-short Cpk recovery centers multiplicative returns at two so tiny finite cover/entry ratios remain distinct.
• SPC fallback arithmetic preserves representable residuals: CUSUM retains exact adaptive-scale state when the active Num grid underflows; CUSUM and EWMA retain raw positive decay weights when their complements round to one; EWMA seed recovery sums cancelling extremes before narrowing; and EWMA variance recovery retains a subnormal decayed prior term alongside a normal deviation contribution. Mixed long/short Cpk recovery centers exact returns before finite-context rounding. The quiet full-build watchdog now timestamps non-empty initial progress baselines, while its deterministic fixture publishes progress before advancing the virtual clock, eliminating timeout-boundary races.