Java Statistical Classes

jsc.tests
Class PermutationTest

java.lang.Object
  |
  +--jsc.tests.PermutationTest
All Implemented Interfaces:
SignificanceTest

public class PermutationTest
extends Object
implements SignificanceTest

General permutation test.

Given any statistic that can be recalculated for permutations of its data (i.e. that implements the PermutableStatistic interface), this class calculates the significance probability of the permutation test using the original statistic value t. That is, it calculates the statistic for permutations of the original data, and finds the proportion of these that are less than or equal to t (Tail.LOWER), greater than or equal to t (Tail.UPPER), or either (Tail.TWO), where t is the original observed statistic value.

If all permutations are used, and the statistic is a distribution-free test statistic, this proportion often provides the exact SP of the distribution-free test. If the statistic is a parametric test, it provides a SP that is independent of the distribution of the observations assumed under the null hypothesis of the original test. Alternatively, these calculations can be performed for random samples of permutations, in which case the proportion is an approximation to the exact SP.

Note that calculating the test statistic for all permutations is suitable only for small samples. The time taken to perform the calculations for moderate or large samples may be unacceptable, depending on the computations involved in calculating the statistic. This general class should not be used where algorithms or classes are available for specific statistics, when it is often the case that the calculations can be streamlined, or good approximations are available.

If access to the individual permutation statistics are required (e.g. to examine their distribution or for teaching purposes), a StatisticListener object can be supplied in the constructor. Alternatively, add appropriate listeners to the object that implements the PermutableStatistic interface, which may also give access to the permutation samples.

Reference:
Efron,B. and Tibshirani,R.J.(1993). An Introduction to the Bootstrap. Chapman & Hall.

Version:
1.0
Author:
A. J. Bertie.

Constructor Summary
PermutationTest(PermutableStatistic statistic)
          Create permutation test.
PermutationTest(PermutableStatistic statistic, Tail tail)
          Create permutation test.
PermutationTest(PermutableStatistic statistic, Tail tail, boolean monteCarlo, int repCount)
          Create permutation test.
PermutationTest(PermutableStatistic statistic, Tail tail, boolean monteCarlo, int repCount, double tolerance)
          Create permutation test.
PermutationTest(PermutableStatistic permutableStatistic, Tail tail, boolean monteCarlo, int repCount, double tolerance, StatisticListener listener)
          Create permutation test.
 
Method Summary
 double calculateSP()
          Calculate the significance probability using all possible permutations.
 double calculateSP(int repCount)
          Estimate the significance probability by taking a random sample of permutations.
 double calculateSP(int repCount, double tolerance)
          Estimate the significance probability by taking random samples of permutations.
 double getPermutationCount()
          Returns the total number of possible permutations.
 double getSP()
          Returns the achieved significance level of the permutation test.
 double getTestStatistic()
          Returns value of the original observed statistic.
 double getTotalRepCount()
          Returns the total number of permutations used.
 void setSeed(long seed)
          Initialize the random number generator with a seed value.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

PermutationTest

public PermutationTest(PermutableStatistic permutableStatistic,
                       Tail tail,
                       boolean monteCarlo,
                       int repCount,
                       double tolerance,
                       StatisticListener listener)
Create permutation test. For small samples the exact significance probability can be calculated using all possible permutations; otherwise a Monte Carlo estimate of the SP is calculated from random samples of permutations. If tolerance is greater than zero, samples of size repCount are repeatedly generated until the absolute difference between successive estimates of SP is less than the tolerance. If tolerance is less than or equal to zero, just one sample of size repCount is generated to estimate the SP.

Parameters:
tail - indicates which tail of the distribution is to be used to calculate the SP.
monteCarlo - if true, a Monte Carlo estimate of the SP; if false, all permutations are used.
repCount - the size of a sample of random permutations (ignored if monteCarlo is false).
tolerance - the tolerance for stopping Monte Carlo sampling (ignored if monteCarlo is false).
listener - a listener for accessing permutatation statistics; or null.

PermutationTest

public PermutationTest(PermutableStatistic statistic,
                       Tail tail,
                       boolean monteCarlo,
                       int repCount,
                       double tolerance)
Create permutation test. For small samples the exact significance probability can be calculated using all possible permutations; otherwise a Monte Carlo estimate of the SP is calculated from random samples of permutations. If tolerance is greater than zero, samples of size repCount are repeatedly generated until the absolute difference between successive estimates of SP is less than the tolerance. If tolerance is less than or equal to zero, just one sample of size repCount is generated to estimate the SP.

Parameters:
statistic - the permutable statistic.
tail - indicates which tail of the distribution is to be used to calculate the SP.
monteCarlo - if true, a Monte Carlo estimate of the SP; if false, all permutations are used.
repCount - the size of a sample of random permutations (ignored if monteCarlo is false).
tolerance - the tolerance for stopping Monte Carlo sampling (ignored if monteCarlo is false).

PermutationTest

public PermutationTest(PermutableStatistic statistic,
                       Tail tail,
                       boolean monteCarlo,
                       int repCount)
Create permutation test. For small samples the exact significance probability can be calculated using all possible permutations; otherwise a Monte Carlo estimate of the SP is calculated from a random sample of repCount permutations.

Parameters:
statistic - the permutable statistic.
tail - indicates which tail of the distribution is to be used to calculate the SP.
monteCarlo - if true, a Monte Carlo estimate of the SP; if false, all permutations are used.
repCount - the size of the sample of random permutations (ignored if monteCarlo is false).

PermutationTest

public PermutationTest(PermutableStatistic statistic,
                       Tail tail)
Create permutation test. The exact significance probability is calculated using all possible permutations. This should be used for small samples only.

Parameters:
statistic - the permutable statistic.
tail - indicates which tail of the distribution is to be used to calculate the SP.

PermutationTest

public PermutationTest(PermutableStatistic statistic)
Create permutation test. The exact upper tail significance probability is calculated using all possible permutations. This should be used for small samples only.

Parameters:
statistic - the permutable statistic.
Method Detail

calculateSP

public double calculateSP()
Calculate the significance probability using all possible permutations. Note that this is suitable only for small samples. The time taken to perform the calculations for moderate or large samples may be unacceptable.

Returns:
the SP.

calculateSP

public double calculateSP(int repCount)
Estimate the significance probability by taking a random sample of permutations. Calls to this method are cumulative: i.e. the SP is recalculated using all previous samples. Repeated calls could be used to assess the convergence of the SP to some value. No calculations are made if all permutations have been sampled.

Parameters:
repCount - the number of random permutation replications.
Returns:
the recalculated approximate SP.

calculateSP

public double calculateSP(int repCount,
                          double tolerance)
Estimate the significance probability by taking random samples of permutations. Samples of size repCount are repeatedly generated until the absolute difference between successive estimates of the SP is less than the tolerance. No calculations are made if all permutations have been sampled.

Parameters:
repCount - the number of random permutation replications.
tolerance - the tolerance for stopping sampling.
Returns:
the estimated SP.

getPermutationCount

public double getPermutationCount()
Returns the total number of possible permutations. The return value is double to allow for very large numbers.

Returns:
the number of permutations.

getSP

public double getSP()
Returns the achieved significance level of the permutation test.

Specified by:
getSP in interface SignificanceTest
Returns:
the achieved significance level.

getTestStatistic

public double getTestStatistic()
Returns value of the original observed statistic.

Specified by:
getTestStatistic in interface SignificanceTest
Returns:
the value of statistic.

getTotalRepCount

public double getTotalRepCount()
Returns the total number of permutations used.

Returns:
the total number of replications.

setSeed

public void setSeed(long seed)
Initialize the random number generator with a seed value. The random number generator is used to generate random permutations. Setting the seed is necessary if the same random samples are to be repeated.

Parameters:
seed - a seed value.

Java Statistical Classes

Copyright © Andrew James Bertie, 2005, all rights reserved. Updated 12th Aug 2005