Package jdistlib.disttest

Class MultipleTesting

java.lang.Object
jdistlib.disttest.MultipleTesting
public final class MultipleTesting extends Object
Multiple-testing adjustments and Storey q-values.

The returned adjusted p-values retain the input order. NaN denotes a missing p-value, is preserved in the result, and is not counted as a test unless the overload with an explicit number of tests is used. All other values must be finite probabilities in [0, 1].

This class is stateless and thread-safe.

  • Method Details

    • adjust

      public static double[] adjust(double[] pValues, MultipleTesting.Method method)
      Adjusts p-values, counting only non-missing inputs as tests.
      Parameters:
      pValues - raw p-values
      method - adjustment procedure
      Returns:
      adjusted p-values in the original order

    • adjust

      public static double[] adjust(double[] pValues, MultipleTesting.Method method, int numberOfTests)
      Adjusts p-values for a declared total number of comparisons.

      The declared count may exceed the number of observed non-missing p-values. Unobserved values are treated as larger than the observed values for Bonferroni and Holm and as one for the other stepwise procedures, in the same manner as R's p.adjust(..., n=) contract.

      Parameters:
      pValues - raw p-values
      method - adjustment procedure
      numberOfTests - total number of comparisons
      Returns:
      adjusted p-values in the original order

    • adjustLog

      public static double[] adjustLog(double[] logPValues, MultipleTesting.Method method)
      Adjusts natural-log p-values without exponentiating them.

      This is the preferred entry point for p-values that may underflow in ordinary floating-point representation. Inputs must be NaN, negative infinity, or finite values in [-infinity, 0]; outputs are natural logs of the adjusted p-values.

    • adjustLog

      public static double[] adjustLog(double[] logPValues, MultipleTesting.Method method, int numberOfTests)
      Adjusts natural-log p-values for a declared total family size.

    • adjustWeightedBenjaminiHochberg

      public static double[] adjustWeightedBenjaminiHochberg(double[] pValues, double[] weights)
      Computes weighted Benjamini-Hochberg adjusted p-values.

      Weights must be finite, strictly positive, and chosen independently of the p-values under their null hypotheses. They are rescaled over the non-missing family to have mean one, so multiplying every weight by the same positive constant does not change the result. Larger weights give a hypothesis greater priority.

      See Also:

    • adjustLogWeightedBenjaminiHochberg

      public static double[] adjustLogWeightedBenjaminiHochberg(double[] logPValues, double[] weights)
      Computes weighted BH adjusted values directly from natural-log p-values. The output remains in natural-log form.

    • adjustWeightedBenjaminiYekutieli

      public static double[] adjustWeightedBenjaminiYekutieli(double[] pValues, double[] weights)
      Computes weighted Benjamini-Yekutieli adjusted p-values.

      This is weighted BH with the harmonic family-size correction and therefore retains FDR control under arbitrary dependence. Weight requirements and normalization are identical to weighted BH.

    • adjustLogWeightedBenjaminiYekutieli

      public static double[] adjustLogWeightedBenjaminiYekutieli(double[] logPValues, double[] weights)
      Weighted BY adjustment for natural-log p-values.

    • adjustWeightedBonferroni

      public static double[] adjustWeightedBonferroni(double[] pValues, double[] weights)
      Computes weighted Bonferroni adjusted p-values.

    • adjustLogWeightedBonferroni

      public static double[] adjustLogWeightedBonferroni(double[] logPValues, double[] weights)
      Weighted Bonferroni adjustment for natural-log p-values.

    • adjustWeightedHolm

      public static double[] adjustWeightedHolm(double[] pValues, double[] weights)
      Computes weighted Holm adjusted p-values.

      Hypotheses are ordered by p[i] / weight[i]. At each step the multiplier is the sum of weights still under consideration. This strongly controls FWER and reduces exactly to ordinary Holm for equal weights.

    • adjustLogWeightedHolm

      public static double[] adjustLogWeightedHolm(double[] logPValues, double[] weights)
      Weighted Holm adjustment for natural-log p-values.

    • rejectWeightedBenjaminiHochberg

      public static boolean[] rejectWeightedBenjaminiHochberg(double[] pValues, double[] weights, double level)
      Returns weighted-BH rejection flags at the requested FDR level.

    • rejectLogWeightedBenjaminiHochberg

      public static boolean[] rejectLogWeightedBenjaminiHochberg(double[] logPValues, double[] weights, double level)
      Returns weighted-BH rejection flags for natural-log p-values.

    • rejectWeightedBenjaminiYekutieli

      public static boolean[] rejectWeightedBenjaminiYekutieli(double[] pValues, double[] weights, double level)
      Returns weighted-BY rejection flags.

    • rejectWeightedBonferroni

      public static boolean[] rejectWeightedBonferroni(double[] pValues, double[] weights, double level)
      Returns weighted-Bonferroni rejection flags.

    • rejectWeightedHolm

      public static boolean[] rejectWeightedHolm(double[] pValues, double[] weights, double level)
      Returns weighted-Holm rejection flags.

    • rejectLogWeightedBenjaminiYekutieli

      public static boolean[] rejectLogWeightedBenjaminiYekutieli(double[] logPValues, double[] weights, double level)
      Returns log-scale weighted-BY rejection flags.

    • rejectLogWeightedBonferroni

      public static boolean[] rejectLogWeightedBonferroni(double[] logPValues, double[] weights, double level)
      Returns log-scale weighted-Bonferroni rejection flags.

    • rejectLogWeightedHolm

      public static boolean[] rejectLogWeightedHolm(double[] logPValues, double[] weights, double level)
      Returns log-scale weighted-Holm rejection flags.

    • rejectLog

      public static boolean[] rejectLog(double[] logPValues, double level, MultipleTesting.Method method)
      Returns rejection flags for natural-log p-values.

    • rejectLog

      public static boolean[] rejectLog(double[] logPValues, double level, MultipleTesting.Method method, int numberOfTests)
      Returns log-p rejection flags for a declared total family size.

    • benjaminiKriegerYekutieli

      public static MultipleTesting.AdaptiveFdrResult benjaminiKriegerYekutieli(double[] pValues, double level)
      Runs the Benjamini-Krieger-Yekutieli two-stage linear step-up test.

      Unlike ordinary adjusted p-values, BKY depends on the requested FDR level, so the result reports the stage levels and rejection decisions rather than pretending to provide level-independent adjusted values. Its proven FDR guarantee is for independent test statistics.

      See Also:

    • gavrilovBenjaminiSarkar

      public static MultipleTesting.StepDownFdrResult gavrilovBenjaminiSarkar(double[] pValues, double level)
      Runs the Gavrilov-Benjamini-Sarkar adaptive step-down FDR procedure.

      Sorted hypotheses are rejected only while every p-value through rank i is at most i*q/(m+1-i*(1-q)). The proven finite-sample FDR guarantee is for independent test statistics.

      See Also:

    • gavrilovBenjaminiSarkar

      public static MultipleTesting.StepDownFdrResult gavrilovBenjaminiSarkar(double[] pValues, double level, int numberOfTests)
      Runs GBS for a declared total family size.

    • benjaminiKriegerYekutieli

      public static MultipleTesting.AdaptiveFdrResult benjaminiKriegerYekutieli(double[] pValues, double level, int numberOfTests)
      Runs two-stage BKY for a declared total family size.

    • testRightCensored

      public static MultipleTesting.CensoredTestResult testRightCensored(double[] observedPValues, double censoringThreshold, int numberOfTests, double level, MultipleTesting.Method method)
      Tests a right-censored family, where every unrecorded p-value is known to be greater than censoringThreshold.

      The total family size must be known. Unrecorded values are completed conservatively with one. areDecisionsExact() is true when the censoring threshold is at least the largest possible rejection boundary; otherwise the reported rejections remain conservative, but additional discoveries cannot be ruled out without the censored values.

    • reject

      public static boolean[] reject(double[] pValues, double level, MultipleTesting.Method method)
      Returns one rejection flag per input, with missing values marked false.

    • reject

      public static boolean[] reject(double[] pValues, double level, MultipleTesting.Method method, int numberOfTests)
      Returns rejection flags for a declared total family size.

    • countRejected

      public static int countRejected(double[] pValues, double level, MultipleTesting.Method method)
      Returns the number of hypotheses rejected at the requested level.

    • countRejected

      public static int countRejected(double[] pValues, double level, MultipleTesting.Method method, int numberOfTests)
      Returns the rejection count for a declared total family size.

    • countRejectedLog

      public static int countRejectedLog(double[] logPValues, double level, MultipleTesting.Method method)
      Returns the rejection count for natural-log p-values.

    • countRejectedLog

      public static int countRejectedLog(double[] logPValues, double level, MultipleTesting.Method method, int numberOfTests)
      Returns the log-p rejection count for a declared total family size.

    • threshold

      public static double threshold(double[] pValues, double level, MultipleTesting.Method method)
      Returns the largest observed raw p-value rejected at the requested level.
      Returns:
      the raw cutoff, or NaN when no hypothesis is rejected

    • threshold

      public static double threshold(double[] pValues, double level, MultipleTesting.Method method, int numberOfTests)
      Returns the raw rejection threshold for a declared total family size.

    • thresholdLog

      public static double thresholdLog(double[] logPValues, double level, MultipleTesting.Method method)
      Returns the largest rejected natural-log p-value, or NaN.

    • thresholdLog

      public static double thresholdLog(double[] logPValues, double level, MultipleTesting.Method method, int numberOfTests)
      Returns the log rejection threshold for a declared total family size.

    • selectiveGroupedBenjaminiHochberg

      public static MultipleTesting.GroupedFdrResult selectiveGroupedBenjaminiHochberg(double[] pValues, int[] groups, double groupLevel, double withinGroupLevel)
      Selects groups with BH on Simes p-values and tests selected groups with selection-adjusted BH.

      Group labels may be any integers and need not be contiguous. All p-values must be observed. If R of G groups are selected, each selected group is tested at withinGroupLevel * R / G. The guarantee concerns the expected average FDR over selected families under the assumptions of Benjamini and Bogomolov (2014), rather than pooled FDR across every hypothesis.

      See Also:

    • qValues

      public static double[] qValues(double[] pValues)
      Computes Storey q-values using the default smoothing-spline estimate of the true-null proportion.

    • qValues

      public static double[] qValues(double[] pValues, double nullProportion)
      Computes Storey q-values for a caller-supplied true-null proportion.

    • qValues

      public static double[] qValues(double[] pValues, double[] lambdas, double smoothingDegreesOfFreedom)
      Computes Storey q-values with caller-controlled spline settings.

    • qValuesQuantile

      public static double[] qValuesQuantile(double[] pValues, double quantile)
      Computes q-values using the quantile-based estimate of pi-zero.

    • qValuesQuantile

      public static double[] qValuesQuantile(double[] pValues, double[] lambdas, double quantile)
      Computes quantile-estimated q-values with a caller-supplied lambda grid.

    • qValuesQuantile

      public static double[] qValuesQuantile(double[] pValues)
      Computes q-values using the default 0.10 quantile pi-zero estimate.

    • estimateNullProportion

      public static double estimateNullProportion(double[] pValues)
      Estimates pi-zero with the default lambda grid and three spline degrees of freedom.

    • estimateNullProportion

      public static double estimateNullProportion(double[] pValues, double[] lambdas, double smoothingDegreesOfFreedom)
      Estimates the true-null proportion by smoothing the Storey estimates over lambda and predicting at the largest lambda.

    • estimateNullProportionQuantile

      public static double estimateNullProportionQuantile(double[] pValues, double[] lambdas, double quantile)
      Estimates pi-zero as a quantile of the estimates across lambda values.

    • estimateNullProportionQuantile

      public static double estimateNullProportionQuantile(double[] pValues, double quantile)
      Uses the default lambda grid for the quantile pi-zero estimator.

    • estimatedFalseDiscoveryRate

      public static double estimatedFalseDiscoveryRate(double[] pValues, double rawThreshold)
      Estimates FDR at a raw p-value cutoff using the default spline pi-zero estimate.

    • estimatedFalseDiscoveryRate

      public static double estimatedFalseDiscoveryRate(double[] pValues, double rawThreshold, double nullProportion)
      Estimates FDR at a raw cutoff for a caller-supplied pi-zero.

    • defaultLambdas

      public static double[] defaultLambdas()
      Returns a defensive copy of the default q-value lambda grid.