| /* |
| * Licensed to the Apache Software Foundation (ASF) under one or more |
| * contributor license agreements. See the NOTICE file distributed with |
| * this work for additional information regarding copyright ownership. |
| * The ASF licenses this file to You under the Apache License, Version 2.0 |
| * (the "License"); you may not use this file except in compliance with |
| * the License. You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| */ |
| package org.apache.commons.math4.legacy.stat.inference; |
| |
| import org.apache.commons.statistics.distribution.NormalDistribution; |
| import org.apache.commons.math4.legacy.exception.ConvergenceException; |
| import org.apache.commons.math4.legacy.exception.MaxCountExceededException; |
| import org.apache.commons.math4.legacy.exception.NoDataException; |
| import org.apache.commons.math4.legacy.exception.NullArgumentException; |
| import org.apache.commons.math4.legacy.stat.ranking.NaNStrategy; |
| import org.apache.commons.math4.legacy.stat.ranking.NaturalRanking; |
| import org.apache.commons.math4.legacy.stat.ranking.TiesStrategy; |
| import org.apache.commons.math4.legacy.core.jdkmath.AccurateMath; |
| |
| import java.util.stream.IntStream; |
| |
| /** |
| * An implementation of the Mann-Whitney U test (also called Wilcoxon rank-sum test). |
| * |
| */ |
| public class MannWhitneyUTest { |
| |
| /** Ranking algorithm. */ |
| private NaturalRanking naturalRanking; |
| |
| /** |
| * Create a test instance using where NaN's are left in place and ties get |
| * the average of applicable ranks. Use this unless you are very sure of |
| * what you are doing. |
| */ |
| public MannWhitneyUTest() { |
| naturalRanking = new NaturalRanking(NaNStrategy.FIXED, |
| TiesStrategy.AVERAGE); |
| } |
| |
| /** |
| * Create a test instance using the given strategies for NaN's and ties. |
| * Only use this if you are sure of what you are doing. |
| * |
| * @param nanStrategy |
| * specifies the strategy that should be used for Double.NaN's |
| * @param tiesStrategy |
| * specifies the strategy that should be used for ties |
| */ |
| public MannWhitneyUTest(final NaNStrategy nanStrategy, |
| final TiesStrategy tiesStrategy) { |
| naturalRanking = new NaturalRanking(nanStrategy, tiesStrategy); |
| } |
| |
| /** |
| * Ensures that the provided arrays fulfills the assumptions. |
| * |
| * @param x first sample |
| * @param y second sample |
| * @throws NullArgumentException if {@code x} or {@code y} are {@code null}. |
| * @throws NoDataException if {@code x} or {@code y} are zero-length. |
| */ |
| private void ensureDataConformance(final double[] x, final double[] y) |
| throws NullArgumentException, NoDataException { |
| |
| if (x == null || |
| y == null) { |
| throw new NullArgumentException(); |
| } |
| if (x.length == 0 || |
| y.length == 0) { |
| throw new NoDataException(); |
| } |
| } |
| |
| /** Concatenate the samples into one array. |
| * @param x first sample |
| * @param y second sample |
| * @return concatenated array |
| */ |
| private double[] concatenateSamples(final double[] x, final double[] y) { |
| final double[] z = new double[x.length + y.length]; |
| |
| System.arraycopy(x, 0, z, 0, x.length); |
| System.arraycopy(y, 0, z, x.length, y.length); |
| |
| return z; |
| } |
| |
| /** |
| * Computes the <a |
| * href="http://en.wikipedia.org/wiki/Mann%E2%80%93Whitney_U"> Mann-Whitney |
| * U statistic</a> comparing mean for two independent samples possibly of |
| * different length. |
| * <p> |
| * This statistic can be used to perform a Mann-Whitney U test evaluating |
| * the null hypothesis that the two independent samples has equal mean. |
| * </p> |
| * <p> |
| * Let X<sub>i</sub> denote the i'th individual of the first sample and |
| * Y<sub>j</sub> the j'th individual in the second sample. Note that the |
| * samples would often have different length. |
| * </p> |
| * <p> |
| * <strong>Preconditions</strong>: |
| * <ul> |
| * <li>All observations in the two samples are independent.</li> |
| * <li>The observations are at least ordinal (continuous are also ordinal).</li> |
| * </ul> |
| * |
| * @param x the first sample |
| * @param y the second sample |
| * @return Mann-Whitney U statistic (minimum of U<sup>x</sup> and U<sup>y</sup>) |
| * @throws NullArgumentException if {@code x} or {@code y} are {@code null}. |
| * @throws NoDataException if {@code x} or {@code y} are zero-length. |
| */ |
| public double mannWhitneyU(final double[] x, final double[] y) |
| throws NullArgumentException, NoDataException { |
| |
| ensureDataConformance(x, y); |
| |
| final double[] z = concatenateSamples(x, y); |
| final double[] ranks = naturalRanking.rank(z); |
| |
| double sumRankX = 0; |
| |
| /* |
| * The ranks for x is in the first x.length entries in ranks because x |
| * is in the first x.length entries in z |
| */ |
| sumRankX = IntStream.range(0, x.length).mapToDouble(i -> ranks[i]).sum(); |
| |
| /* |
| * U1 = R1 - (n1 * (n1 + 1)) / 2 where R1 is sum of ranks for sample 1, |
| * e.g. x, n1 is the number of observations in sample 1. |
| */ |
| final double u1 = sumRankX - ((long) x.length * (x.length + 1)) / 2; |
| |
| /* |
| * It can be shown that U1 + U2 = n1 * n2 |
| */ |
| final double u2 = (long) x.length * y.length - u1; |
| |
| return AccurateMath.min(u1, u2); |
| } |
| |
| /** |
| * @param umin smallest Mann-Whitney U value |
| * @param n1 number of subjects in first sample |
| * @param n2 number of subjects in second sample |
| * @return two-sided asymptotic p-value |
| * @throws ConvergenceException if the p-value can not be computed |
| * due to a convergence error |
| * @throws MaxCountExceededException if the maximum number of |
| * iterations is exceeded |
| */ |
| private double calculateAsymptoticPValue(final double umin, |
| final int n1, |
| final int n2) |
| throws ConvergenceException, MaxCountExceededException { |
| |
| /* long multiplication to avoid overflow (double not used due to efficiency |
| * and to avoid precision loss) |
| */ |
| final long n1n2prod = (long) n1 * n2; |
| |
| // http://en.wikipedia.org/wiki/Mann%E2%80%93Whitney_U#Normal_approximation |
| final double eU = n1n2prod / 2.0; |
| final double varU = n1n2prod * (n1 + n2 + 1) / 12.0; |
| |
| final double z = (umin - eU) / AccurateMath.sqrt(varU); |
| |
| // No try-catch or advertised exception because args are valid |
| // pass a null rng to avoid unneeded overhead as we will not sample from this distribution |
| final NormalDistribution standardNormal = new NormalDistribution(0, 1); |
| |
| return 2 * standardNormal.cumulativeProbability(z); |
| } |
| |
| /** |
| * Returns the asymptotic <i>observed significance level</i>, or <a href= |
| * "http://www.cas.lancs.ac.uk/glossary_v1.1/hyptest.html#pvalue"> |
| * p-value</a>, associated with a <a |
| * href="http://en.wikipedia.org/wiki/Mann%E2%80%93Whitney_U"> Mann-Whitney |
| * U statistic</a> comparing mean for two independent samples. |
| * <p> |
| * Let X<sub>i</sub> denote the i'th individual of the first sample and |
| * Y<sub>j</sub> the j'th individual in the second sample. Note that the |
| * samples would often have different length. |
| * </p> |
| * <p> |
| * <strong>Preconditions</strong>: |
| * <ul> |
| * <li>All observations in the two samples are independent.</li> |
| * <li>The observations are at least ordinal (continuous are also ordinal).</li> |
| * </ul><p> |
| * Ties give rise to biased variance at the moment. See e.g. <a |
| * href="http://mlsc.lboro.ac.uk/resources/statistics/Mannwhitney.pdf" |
| * >http://mlsc.lboro.ac.uk/resources/statistics/Mannwhitney.pdf</a>.</p> |
| * |
| * @param x the first sample |
| * @param y the second sample |
| * @return asymptotic p-value |
| * @throws NullArgumentException if {@code x} or {@code y} are {@code null}. |
| * @throws NoDataException if {@code x} or {@code y} are zero-length. |
| * @throws ConvergenceException if the p-value can not be computed due to a |
| * convergence error |
| * @throws MaxCountExceededException if the maximum number of iterations |
| * is exceeded |
| */ |
| public double mannWhitneyUTest(final double[] x, final double[] y) |
| throws NullArgumentException, NoDataException, |
| ConvergenceException, MaxCountExceededException { |
| |
| ensureDataConformance(x, y); |
| |
| final double uMin = mannWhitneyU(x, y); |
| |
| return calculateAsymptoticPValue(uMin, x.length, y.length); |
| } |
| } |
