Statistics.java

  1. /*
  2.  * Licensed to the Apache Software Foundation (ASF) under one or more
  3.  * contributor license agreements.  See the NOTICE file distributed with
  4.  * this work for additional information regarding copyright ownership.
  5.  * The ASF licenses this file to You under the Apache License, Version 2.0
  6.  * (the "License"); you may not use this file except in compliance with
  7.  * the License.  You may obtain a copy of the License at
  8.  *
  9.  *      http://www.apache.org/licenses/LICENSE-2.0
  10.  *
  11.  * Unless required by applicable law or agreed to in writing, software
  12.  * distributed under the License is distributed on an "AS IS" BASIS,
  13.  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14.  * See the License for the specific language governing permissions and
  15.  * limitations under the License.
  16.  */
  17. package org.apache.commons.statistics.descriptive;

  19. import java.util.function.DoubleConsumer;
  20. import java.util.function.IntConsumer;
  21. import java.util.function.LongConsumer;

  23. /**
  24.  * Utility methods for statistics.
  25.  *
  26.  * @since 1.1
  27.  */
  28. final class Statistics {
  29.     /** A no-operation double consumer. This is exposed for testing. */
  30.     static final DoubleConsumer DOUBLE_NOOP = new DoubleConsumer() {
  31.         @Override
  32.         public void accept(double value) {
  33.             // Do nothing
  34.         }

  36.         @Override
  37.         public DoubleConsumer andThen(DoubleConsumer after) {
  38.             // Delegate to the after consumer
  39.             return after;
  40.         }
  41.     };

  43.     /** A no-operation int consumer. This is exposed for testing. */
  44.     static final IntConsumer INT_NOOP = new IntConsumer() {
  45.         @Override
  46.         public void accept(int value) {
  47.             // Do nothing
  48.         }

  50.         @Override
  51.         public IntConsumer andThen(IntConsumer after) {
  52.             // Delegate to the after consumer
  53.             return after;
  54.         }
  55.     };

  57.     /** A no-operation long consumer. This is exposed for testing. */
  58.     static final LongConsumer LONG_NOOP = new LongConsumer() {
  59.         @Override
  60.         public void accept(long value) {
  61.             // Do nothing
  62.         }

  64.         @Override
  65.         public LongConsumer andThen(LongConsumer after) {
  66.             // Delegate to the after consumer
  67.             return after;
  68.         }
  69.     };

  71.     /** Error message for an incompatible statistics. */
  72.     private static final String INCOMPATIBLE_STATISTICS = "Incompatible statistics";

  74.     /** No instances. */
  75.     private Statistics() {}

  77.     /**
  78.      * Add all the {@code values} to the {@code statistic}.
  79.      *
  80.      * @param <T> Type of the statistic
  81.      * @param statistic Statistic.
  82.      * @param values Values.
  83.      * @return the statistic
  84.      */
  85.     static <T extends DoubleConsumer> T add(T statistic, double[] values) {
  86.         for (final double x : values) {
  87.             statistic.accept(x);
  88.         }
  89.         return statistic;
  90.     }

  92.     /**
  93.      * Add all the {@code values} to the {@code statistic}.
  94.      *
  95.      * @param <T> Type of the statistic
  96.      * @param statistic Statistic.
  97.      * @param values Values.
  98.      * @return the statistic
  99.      */
  100.     static <T extends DoubleConsumer> T add(T statistic, int[] values) {
  101.         for (final double x : values) {
  102.             statistic.accept(x);
  103.         }
  104.         return statistic;
  105.     }

  107.     /**
  108.      * Add all the {@code values} to the {@code statistic}.
  109.      *
  110.      * @param <T> Type of the statistic
  111.      * @param statistic Statistic.
  112.      * @param values Values.
  113.      * @return the statistic
  114.      */
  115.     static <T extends DoubleConsumer> T add(T statistic, long[] values) {
  116.         for (final double x : values) {
  117.             statistic.accept(x);
  118.         }
  119.         return statistic;
  120.     }

  122.     /**
  123.      * Add all the {@code values} to the {@code statistic}.
  124.      *
  125.      * @param <T> Type of the statistic
  126.      * @param statistic Statistic.
  127.      * @param values Values.
  128.      * @return the statistic
  129.      */
  130.     static <T extends IntConsumer> T add(T statistic, int[] values) {
  131.         for (final int x : values) {
  132.             statistic.accept(x);
  133.         }
  134.         return statistic;
  135.     }

  137.     /**
  138.      * Add all the {@code values} to the {@code statistic}.
  139.      *
  140.      * @param <T> Type of the statistic
  141.      * @param statistic Statistic.
  142.      * @param values Values.
  143.      * @return the statistic
  144.      */
  145.     static <T extends LongConsumer> T add(T statistic, long[] values) {
  146.         for (final long x : values) {
  147.             statistic.accept(x);
  148.         }
  149.         return statistic;
  150.     }

  152.     /**
  153.      * Returns {@code true} if the second central moment {@code m2} is effectively
  154.      * zero given the magnitude of the first raw moment {@code m1}.
  155.      *
  156.      * <p>This method shares the logic for detecting a zero variance among implementations
  157.      * that divide by the variance (e.g. skewness, kurtosis).
  158.      *
  159.      * @param m1 First raw moment (mean).
  160.      * @param m2 Second central moment (biased variance).
  161.      * @return true if the variance is zero
  162.      */
  163.     static boolean zeroVariance(double m1, double m2) {
  164.         // Note: Commons Math checks the variance is < 1e-19.
  165.         // The absolute threshold does not account for the magnitude of the sample.
  166.         // This checks the average squared deviation from the mean (m2)
  167.         // is smaller than the squared precision of the mean (m1).
  168.         // Precision is set to 15 decimal digits
  169.         // (1e-15 ~ 4.5 eps where eps = 2^-52).
  170.         final double meanPrecision = 1e-15 * m1;
  171.         return m2 <= meanPrecision * meanPrecision;
  172.     }

  174.     /**
  175.      * Chain the {@code consumers} into a single composite consumer. Ignore any {@code null}
  176.      * consumer. Returns {@code null} if all arguments are {@code null}.
  177.      *
  178.      * @param consumers Consumers.
  179.      * @return a composed consumer (or null)
  180.      */
  181.     static DoubleConsumer compose(DoubleConsumer... consumers) {
  182.         DoubleConsumer action = DOUBLE_NOOP;
  183.         for (final DoubleConsumer consumer : consumers) {
  184.             if (consumer != null) {
  185.                 action = action.andThen(consumer);
  186.             }
  187.         }
  188.         return action == DOUBLE_NOOP ? null : action;
  189.     }

  191.     /**
  192.      * Chain the {@code consumers} into a single composite consumer. Ignore any {@code null}
  193.      * consumer. Returns {@code null} if all arguments are {@code null}.
  194.      *
  195.      * @param consumers Consumers.
  196.      * @return a composed consumer (or null)
  197.      */
  198.     static IntConsumer compose(IntConsumer... consumers) {
  199.         IntConsumer action = INT_NOOP;
  200.         for (final IntConsumer consumer : consumers) {
  201.             if (consumer != null) {
  202.                 action = action.andThen(consumer);
  203.             }
  204.         }
  205.         return action == INT_NOOP ? null : action;
  206.     }

  208.     /**
  209.      * Chain the {@code consumers} into a single composite consumer. Ignore any {@code null}
  210.      * consumer. Returns {@code null} if all arguments are {@code null}.
  211.      *
  212.      * @param consumers Consumers.
  213.      * @return a composed consumer (or null)
  214.      */
  215.     static LongConsumer compose(LongConsumer... consumers) {
  216.         LongConsumer action = LONG_NOOP;
  217.         for (final LongConsumer consumer : consumers) {
  218.             if (consumer != null) {
  219.                 action = action.andThen(consumer);
  220.             }
  221.         }
  222.         return action == LONG_NOOP ? null : action;
  223.     }

  225.     /**
  226.      * Gets the statistic result using the {@code int} value.
  227.      * Return {@code null} is the statistic is {@code null}.
  228.      *
  229.      * @param s Statistic.
  230.      * @return the result or null
  231.      */
  232.     static StatisticResult getResultAsIntOrNull(StatisticResult s) {
  233.         if (s != null) {
  234.             return (IntStatisticResult) s::getAsInt;
  235.         }
  236.         return null;
  237.     }

  239.     /**
  240.      * Gets the statistic result using the {@code long} value.
  241.      * Return {@code null} is the statistic is {@code null}.
  242.      *
  243.      * @param s Statistic.
  244.      * @return the result or null
  245.      */
  246.     static StatisticResult getResultAsLongOrNull(StatisticResult s) {
  247.         if (s != null) {
  248.             return (LongStatisticResult) s::getAsLong;
  249.         }
  250.         return null;
  251.     }

  253.     /**
  254.      * Gets the statistic result using the {@code double} value.
  255.      * Return {@code null} is the statistic is {@code null}.
  256.      *
  257.      * @param s Statistic.
  258.      * @return the result or null
  259.      */
  260.     static StatisticResult getResultAsDoubleOrNull(StatisticResult s) {
  261.         if (s != null) {
  262.             return s::getAsDouble;
  263.         }
  264.         return null;
  265.     }

  267.     /**
  268.      * Gets the statistic result using the {@code BigInteger} value.
  269.      * Return {@code null} is the statistic is {@code null}.
  270.      *
  271.      * @param s Statistic.
  272.      * @return the result or null
  273.      */
  274.     static StatisticResult getResultAsBigIntegerOrNull(StatisticResult s) {
  275.         if (s != null) {
  276.             return (BigIntegerStatisticResult) s::getAsBigInteger;
  277.         }
  278.         return null;
  279.     }

  281.     /**
  282.      * Check left-hand side argument {@code a} is {@code null} or else the right-hand side
  283.      * argument {@code b} must also be non-{@code null} so the statistics can be combined.
  284.      *
  285.      * @param <T> {@link StatisticResult} being accumulated.
  286.      * @param a LHS.
  287.      * @param b RHS.
  288.      * @throws IllegalArgumentException if the objects cannot be combined
  289.      */
  290.     static <T extends StatisticResult & StatisticAccumulator<T>> void checkCombineCompatible(T a, T b) {
  291.         if (a != null && b == null) {
  292.             throw new IllegalArgumentException(INCOMPATIBLE_STATISTICS);
  293.         }
  294.     }

  296.     /**
  297.      * Check left-hand side argument {@code a} is {@code null} or else the right-hand side
  298.      * argument {@code b} must be run-time assignable to the same class as {@code a}
  299.      * so the statistics can be combined.
  300.      *
  301.      * @param a LHS.
  302.      * @param b RHS.
  303.      * @throws IllegalArgumentException if the objects cannot be combined
  304.      */
  305.     static void checkCombineAssignable(FirstMoment a, FirstMoment b) {
  306.         if (a != null && (b == null || !a.getClass().isAssignableFrom(b.getClass()))) {
  307.             throw new IllegalArgumentException(INCOMPATIBLE_STATISTICS);
  308.         }
  309.     }

  311.     /**
  312.      * If the left-hand side argument {@code a} is non-{@code null}, combine it with the
  313.      * right-hand side argument {@code b}.
  314.      *
  315.      * @param <T> {@link StatisticResult} being accumulated.
  316.      * @param a LHS.
  317.      * @param b RHS.
  318.      */
  319.     static <T extends StatisticResult & StatisticAccumulator<T>> void combine(T a, T b) {
  320.         if (a != null) {
  321.             a.combine(b);
  322.         }
  323.     }

  325.     /**
  326.      * If the left-hand side argument {@code a} is non-{@code null}, combine it with the
  327.      * right-hand side argument {@code b}. Assumes that the RHS is run-time assignable
  328.      * to the same class as LHS.
  329.      *
  330.      * @param a LHS.
  331.      * @param b RHS.
  332.      * @see #checkCombineAssignable(FirstMoment, FirstMoment)
  333.      */
  334.     static void combineMoment(FirstMoment a, FirstMoment b) {
  335.         // Avoid reflection and use the simpler instanceof
  336.         if (a instanceof SumOfFourthDeviations) {
  337.             ((SumOfFourthDeviations) a).combine((SumOfFourthDeviations) b);
  338.         } else if (a instanceof SumOfCubedDeviations) {
  339.             ((SumOfCubedDeviations) a).combine((SumOfCubedDeviations) b);
  340.         } else if (a instanceof SumOfSquaredDeviations) {
  341.             ((SumOfSquaredDeviations) a).combine((SumOfSquaredDeviations) b);
  342.         } else if (a != null) {
  343.             a.combine(b);
  344.         }
  345.     }
  346. }
Created with JaCoCo 0.8.12.202403310830