This is an automated email from the ASF dual-hosted git repository.
asf-gitbox-commits pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/commons-statistics.git
The following commit(s) were added to refs/heads/master by this push:
new 0c000e5e Document possible long runtime within the hypergeometric
distribution
0c000e5e is described below
commit 0c000e5e125e11d0f7526669bc7ad8bd9222390d
Author: Alex Herbert <[email protected]>
AuthorDate: Thu Aug 27 11:26:14 2026 +0100
Document possible long runtime within the hypergeometric distribution
---
.../statistics/distribution/HypergeometricDistribution.java | 12 ++++++++++++
.../apache/commons/statistics/inference/FisherExactTest.java | 12 ++++++++++++
src/changes/changes.xml | 7 +++++++
3 files changed, 31 insertions(+)
diff --git
a/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/HypergeometricDistribution.java
b/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/HypergeometricDistribution.java
index c5dae67d..5f1b0b81 100644
---
a/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/HypergeometricDistribution.java
+++
b/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/HypergeometricDistribution.java
@@ -35,6 +35,18 @@ import java.util.function.DoublePredicate;
*
* <p>is the binomial coefficient.
*
+ * <p><strong>Note:</strong> The cumulative probability functions
+ * {@link #cumulativeProbability(int) cumulativeProbability} and
+ * {@link #survivalProbability(int) survivalProbability}, and the inverse
probability
+ * functions {@link #inverseCumulativeProbability(double)
inverseCumulativeProbability}
+ * and {@link #inverseSurvivalProbability(double) inverseSurvivalProbability},
are
+ * computed by summation of the probability mass function over the support.
The cost of
+ * a call is {@code O(min(K, n))}. Parameters that create a very large support
width,
+ * for example a population size of order 2<sup>31</sup> with a comparable
number of
+ * successes and sample size, may require in the order of 10<sup>9</sup>
function
+ * evaluations per call. Take this run-time cost into account when the
parameters are
+ * derived from untrusted input, and bound the parameter magnitudes
accordingly.
+ *
* @see <a
href="https://en.wikipedia.org/wiki/Hypergeometric_distribution";>Hypergeometric
distribution (Wikipedia)</a>
* @see <a
href="https://mathworld.wolfram.com/HypergeometricDistribution.html";>Hypergeometric
distribution (MathWorld)</a>
*/
diff --git
a/commons-statistics-inference/src/main/java/org/apache/commons/statistics/inference/FisherExactTest.java
b/commons-statistics-inference/src/main/java/org/apache/commons/statistics/inference/FisherExactTest.java
index c3914646..0c733c51 100644
---
a/commons-statistics-inference/src/main/java/org/apache/commons/statistics/inference/FisherExactTest.java
+++
b/commons-statistics-inference/src/main/java/org/apache/commons/statistics/inference/FisherExactTest.java
@@ -28,6 +28,14 @@ import
org.apache.commons.statistics.distribution.HypergeometricDistribution;
* <p>Fisher's test applies in the case that the row sums and column sums are
fixed in advance
* and not random.
*
+ * <p><strong>Note:</strong> The p-value is computed using the hypergeometric
+ * distribution conditioned on the table margins. The computation sums the
probability
+ * mass function over the support of the distribution; the run time of
+ * {@link #test(int[][]) test} scales linearly with the magnitude of the table
entries
+ * and a table with a sum approaching 2<sup>31</sup> may require in the order
of
+ * 10<sup>9</sup> function evaluations. Take this cost into account when the
table
+ * counts are derived from untrusted input, and bound the table sum
accordingly.
+ *
* @see <a
href="https://en.wikipedia.org/wiki/Fisher%27s_exact_test";>Fisher's exact
test (Wikipedia)</a>
* @since 1.1
*/
@@ -126,6 +134,10 @@ public final class FisherExactTest {
* is the probability that a random table has {@code x <= a}.</li>
* </ul>
*
+ * <p><strong>Note:</strong> The run time scales linearly with the
magnitude of the
+ * table entries. See the {@linkplain FisherExactTest class-level}
documentation
+ * for details.
+ *
* @param table 2-by-2 contingency table.
* @return test result
* @throws IllegalArgumentException if the {@code table} is not a 2-by-2
table; any
diff --git a/src/changes/changes.xml b/src/changes/changes.xml
index 737ed284..d8aa96ad 100644
--- a/src/changes/changes.xml
+++ b/src/changes/changes.xml
@@ -53,6 +53,13 @@ If the output is not quite correct, check for invisible
trailing spaces!
</properties>
<body>
<release version="1.4" date="TBD" description="Adds new features (requires
Java 8).">
+ <action dev="aherbert" type="update" due-to="Security scan, Aex Herbert">
+ "FisherExactTest/HypergeometricDistribution": Update documentation
+ on possible long runtime when the hypergeometric distribution
+ cumulative probability functions are evaluated with parameters that
+ create a very large support width. Users are advised to guard the
+ arguments to the FisherExactTest and HypergeometricDistribution.
+ </action>
<action dev="aherbert" type="fix" due-to="Security scan, Aex Herbert"
issue="STATISTICS-96">
"commons-statistics-distribution": Checks added to distribution factory
functions for NaN parameters that invalidate the distribution.
