Package de.cuioss.benchmarking.common.report

Class StatisticsCalculator

java.lang.Object
de.cuioss.benchmarking.common.report.StatisticsCalculator
public final class StatisticsCalculator extends Object
Provides pure statistical computation utilities for benchmark metrics.

This class is responsible for all statistical calculations including:

  • Basic statistics (min, max, mean, median)
  • Moving averages
  • Percentage changes and trends
  • Standard deviation and variance

Use this class when you need to perform mathematical/statistical operations on benchmark data. For metric-specific calculations (performance scores, grades), use MetricsComputer. For time-series analysis and trend detection, use TrendDataProcessor.

See Also:

  • Field Details

  • Method Details

    • calculateMean

      public static double calculateMean(Collection<Double> values)
      Calculates the arithmetic mean (average) of a collection of values.
      Parameters:
      values - collection of numeric values
      Returns:
      the mean value, or 0.0 if the collection is empty
      Throws:
      NullPointerException - if values is null

    • findMin

      public static double findMin(Collection<Double> values)
      Finds the minimum value in a collection.
      Parameters:
      values - collection of numeric values
      Returns:
      the minimum value, or Double.MAX_VALUE if the collection is empty
      Throws:
      NullPointerException - if values is null

    • findMax

      public static double findMax(Collection<Double> values)
      Finds the maximum value in a collection.
      Parameters:
      values - collection of numeric values
      Returns:
      the maximum value, or Double.MIN_VALUE if the collection is empty
      Throws:
      NullPointerException - if values is null

    • calculateMedian

      public static double calculateMedian(Collection<Double> values)
      Calculates the median value of a collection.
      Parameters:
      values - collection of numeric values
      Returns:
      the median value, or 0.0 if the collection is empty
      Throws:
      NullPointerException - if values is null

    • calculatePercentageChange

      public static double calculatePercentageChange(double oldValue, double newValue)
      Calculates the percentage change between two values.

      Formula: ((newValue - oldValue) / oldValue) * 100

      Parameters:
      oldValue - the original value
      newValue - the new value
      Returns:
      the percentage change

    • calculateMovingAverage

      public static double calculateMovingAverage(List<Double> values, int windowSize)
      Calculates a simple moving average for the most recent N values.
      Parameters:
      values - list of values (assumed to be in chronological order)
      windowSize - the number of most recent values to include
      Returns:
      the moving average
      Throws:
      NullPointerException - if values is null
      IllegalArgumentException - if windowSize is less than 1

    • calculateStandardDeviation

      public static double calculateStandardDeviation(Collection<Double> values)
      Calculates the standard deviation of a collection of values.
      Parameters:
      values - collection of numeric values
      Returns:
      the standard deviation, or 0.0 if the collection has less than 2 elements
      Throws:
      NullPointerException - if values is null

    • calculateEWMA

      public static double calculateEWMA(List<Double> values, double lambda)
      Calculates an Exponentially Weighted Moving Average (EWMA) baseline from historical values.

      EWMA gives more weight to recent values while still considering historical context, making it ideal for performance monitoring and trend detection. The decay factor (lambda) determines how quickly older values lose influence.

      Formula: EWMA = Σ(value_i × λ^i) / Σ(λ^i) where i=0 is the most recent value, i=1 is second most recent, etc.

      Parameters:
      values - list of historical values, ordered from newest to oldest
      lambda - decay factor (typically 0.2-0.3 for performance monitoring). Smaller values = more weight on recent data.
      Returns:
      the weighted baseline value
      Throws:
      NullPointerException - if values is null
      IllegalArgumentException - if lambda is not in (0, 1] range

    • determineTrendDirection

      public static String determineTrendDirection(double percentageChange, double stabilityThreshold)
      Determines the trend direction based on percentage change and a stability threshold.
      Parameters:
      percentageChange - the percentage change value
      stabilityThreshold - the threshold (as a percentage) below which the trend is considered stable
      Returns:
      "up", "down", or "stable"

    • computeStatistics

      public static StatisticsCalculator.Statistics computeStatistics(Collection<Double> values)
      Computes comprehensive statistics for a dataset.
      Parameters:
      values - collection of numeric values
      Returns:
      a Statistics object containing min, max, mean, median, standard deviation, and count
      Throws:
      NullPointerException - if values is null