goldenChart/ta4j-master/release/0.21.0.md

0.21.0 (2025-11-29)

Changed

• Unified return representation system: Say goodbye to inconsistent return formats across your analysis! Return-based criteria now use a unified ReturnRepresentation system that lets you choose how returns are displayed—whether you prefer multiplicative (1.12 for +12%), decimal (0.12), percentage (12.0), or logarithmic formats. Set it once globally via ReturnRepresentationPolicy or customize per-criterion. No more mental math converting between formats—Ta4j handles it all automatically. Legacy addBase constructors are deprecated in favor of the more expressive ReturnRepresentation enum.

• Ratio criteria now speak your language: All ratio-producing criteria now support ReturnRepresentation, so you can format outputs consistently across your entire analysis pipeline. Whether you're comparing strategies, measuring risk, or tracking performance metrics, everything uses the same format. Updated criteria include:

  • VersusEnterAndHoldCriterion: Strategy vs. buy-and-hold comparison (e.g., 0.5 = 50% better, displayed as 0.5, 50.0, or 1.5 depending on your preference)
  • ReturnOverMaxDrawdownCriterion: Reward-to-risk ratio (e.g., 2.0 = return is 2x drawdown)
  • PositionsRatioCriterion: Win/loss percentage (e.g., 0.5 = 50% winning)
  • InPositionPercentageCriterion: Time in market (e.g., 0.5 = 50% of time)
  • CommissionsImpactPercentageCriterion: Trading cost impact (e.g., 0.05 = 5% impact)
  • AbstractProfitLossRatioCriterion (and subclasses): Profit-to-loss ratio (e.g., 2.0 = profit is 2x loss)

  All ratio criteria default to ReturnRepresentation.DECIMAL (the conventional format for ratios), but you can override per-criterion or globally. Perfect for dashboards, reports, or when you need to match external data formats. See each criterion's javadoc for detailed examples.

• Improved return representation tooling: Added factory-level exponential support to avoid premature double conversions, expanded representation parsing to accept flexible names, and aligned VaR/ES/average-return empty-record behaviour across representations.

• High-precision DecimalNum exponentials: DecimalNumFactory#exp now evaluates exponentials using the configured MathContext instead of delegating to {@code Math.exp}, preventing accidental loss of precision for high-precision numeric workflows.

• Simplified Returns class implementation: Removed unnecessary formatOnAccess complexity from Returns class, inlined trivial formatReturn() wrapper method, and improved documentation clarity. The class now has a cleaner separation of concerns with better cross-references between Returns, ReturnRepresentation, and ReturnRepresentationPolicy.

Breaking

• EMA indicators now return NaN during unstable period: EMAIndicator, MMAIndicator, and all indicators extending AbstractEMAIndicator now return NaN for indices within the unstable period (indices < beginIndex + getCountOfUnstableBars()). Previously, these indicators would return calculated values during the unstable period. Action required: Update any code that accesses EMA indicator values during the unstable period to handle NaN values appropriately, or wait until after the unstable period before reading values.
• DifferencePercentageIndicator deprecated: DifferencePercentageIndicator has been deprecated in favor of PercentageChangeIndicator, which now provides all the same functionality plus additional features. Action required: Migrate to PercentageChangeIndicator using the migration examples in the deprecation javadoc.

Added

• Added TrueStrengthIndexIndicator, SchaffTrendCycleIndicator, and ConnorsRSIIndicator to expand oscillator coverage
• Added PercentRankIndicator helper indicator to calculate the percentile rank of a value within a rolling window
• Added DifferenceIndicator helper indicator to calculate the difference between current and previous indicator values
• Added StreakIndicator helper indicator to track consecutive up or down movements in indicator values
• Added StochasticIndicator as a generic stochastic calculation indicator, extracted from SchaffTrendCycleIndicator for reuse
• AI-powered semantic release scheduler: Added automated GitHub workflow that uses AI to analyze changes, determine version bumps (patch/minor/major), and schedule releases every 14 days. Includes structured approval process for major version bumps and OIDC token-based authentication for AI model calls. Enhanced release workflows with improved error handling, tag checking, and logging.