org.opensha.commons.calc
Class GaussianDistCalc

java.lang.Object
  org.opensha.commons.calc.GaussianDistCalc

public final class GaussianDistCalc
extends Object

Title: GaussianDistCalc.java

Description:

This utility calculates the probability of exceedance assuming a gaussian distribution. The object edu.uah.math.psol.distributions.NormalDistribution is not used here because it was found to be ~3 times slower (see the getCDF_Alt() method commented out).

Version:

1.0

Author:

Edward Field

Constructor Summary

GaussianDistCalc()

Method Summary

static double	getCDF(double standRandVariable) This function calculates the cumulative density function for a Gaussian distribution (the area under the curve up to standRandVariable).
static double	getExceedProb(double standRandVariable)
static double	getExceedProb(double standRandVariable, double lowerTruncLevel, double upperTruncLevel) This function calculates the exceedance probability for a truncated Gaussian distribution.
static double	getExceedProb(double standRandVariable, int truncType, double truncLevel) This function calculates the exceedance probability for a truncated Gaussian distribution.
static double	getStandRandVar(double exceedProb, double lowerTruncLevel, double upperTruncLevel, double tolerance) This returns the standardized random variable (SRV) associated with the given exceedance probability.
static double	getStandRandVar(double exceedProb, int truncType, double truncLevel, double tolerance) This returns the standardized random variable (SRV) associated with the given exceedance probability.
static void	main(String[] args) main method for running tests
static void	test_symmetry_getStandRandVar()
static boolean	test1_getStandRandVar(double tol, int trTyp, double trLev) This method tests the getStandRandVar() method over a wide range of input probabilities for a given tolerance, truncation type, and truncation value (the range of probabilites tested are those computed from getExceedProb() for SRV from -7.5 to 7.5).
static void	test2_getStandRandVar() This runs test1_getStandRandVar() over a range of tolerances, truncation types, and trucation levels.
static void	testSpeed_getStandRandVar() This tests the influence of tolerance on performance.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

GaussianDistCalc

public GaussianDistCalc()

Method Detail

getExceedProb

public static double getExceedProb(double standRandVariable)

getExceedProb

public static double getExceedProb(double standRandVariable,
                                   int truncType,
                                   double truncLevel)

This function calculates the exceedance probability for a truncated Gaussian distribution.

Parameters:

standRandVariable -

truncType - set 0 for none, 1 for upper only, and 2 for two sided

truncLevel - in units of SRV (must be positive, and can't = 0.0 for truncType = 2)

Returns:

the exceedance probability

getExceedProb

public static double getExceedProb(double standRandVariable,
                                   double lowerTruncLevel,
                                   double upperTruncLevel)

This function calculates the exceedance probability for a truncated Gaussian distribution. The distribution is non-symmetrically truncated on both sides

Parameters:

standRandVariable -

lowerTruncLevel - in units of SRV

upperTruncLevel - in units of SRV

Returns:

the exceedance probability

getCDF

public static double getCDF(double standRandVariable)

This function calculates the cumulative density function for a Gaussian distribution (the area under the curve up to standRandVariable). This algorithm comes from Norm Abrahamson, who says he got it from a book by Abramowitz and Stegun.

Comparing the probabilities computed with this method between +/- 7.5 SRVs with those computed using Excel gives a difference of 0.3 % at SRV=-4, and grows to 364 % (a factor of 3.64) at SRV=-7.5. The difference is negligible for all positive CRVs (up to at least 7.5). Norm Abrahamson says this is good enough for seismic hazard calculations.

getStandRandVar

public static double getStandRandVar(double exceedProb,
                                     int truncType,
                                     double truncLevel,
                                     double tolerance)

This returns the standardized random variable (SRV) associated with the given exceedance probability. The tolerance specifies the accuracy of the result such that:

(prob_target-getExceedProb(SRV_found,trTyp, trLev))/prob_target < tolerance

There is another potential ambiguity in that there may be a wide range of SRVs that satisfy the above. For example, if the target probability is 1e-5, and the tolerance is 1e-3, then all SRVs greater than 4.26 satisfy the above. We solve this ambiguity by giving the first occurrence (generally the value closest to zero). Specifically, if the target probability is less than 0.5, we find an SRV such that the probability for (SRV_found-tolerance) does not satisfy the above condition (is not within tolerance of the target probability). For target probabilities greater than 0.5 we give the SRV such that the probability for (SRV_found+toloerance) will not be within tolerance of the target probability.

The cases where exceedProb = 0.0 or 1.0 are treated explicity (e.g., Double.POSITIVE_INFINITY or Double.NEGATIVE_INFINITY are returned if no truncation is applied).

Note that the result is not necessarily symmetric in that getStandRandVar(prob,*) may not exactly equal the negative of getStandRandVar((1-prob),*). This simply represents the lack of numerical precision under some conditions, with the problem worsening for greater tolerances and as the input probability approaches zero or one. For example,

getStandRandVar(0.0001,0,2,1e-6) = 3.72
getStandRandVar(0.9999,0,2,1e-6) = -3.72

getStandRandVar(0.000001,0,2,1e-6) = 4.76
getStandRandVar(0.999999,0,2,1e-6) = -4.62 This could simply call the other getStandRandVar method, but we're leaving this here because it's more efficient with untruncated cases (although this may not be significant)

Parameters:

exceedProb - The target exceedance probability

truncType - The truncation type

truncLevel - The truncation level (num SRVs)

tolerance - The tolerance

Returns:

The SRV found for the target exceedProb

getStandRandVar

public static double getStandRandVar(double exceedProb,
                                     double lowerTruncLevel,
                                     double upperTruncLevel,
                                     double tolerance)

This returns the standardized random variable (SRV) associated with the given exceedance probability. The tolerance specifies the accuracy of the result such that:

(prob_target-getExceedProb(SRV_found,trTyp, trLev))/prob_target < tolerance

There is another potential ambiguity in that there may be a wide range of SRVs that satisfy the above. For example, if the target probability is 1e-5, and the tolerance is 1e-3, then all SRVs greater than 4.26 satisfy the above. We solve this ambiguity by giving the first occurrence (generally the value closest to zero). Specifically, if the target probability is less than 0.5, we find an SRV such that the probability for (SRV_found-tolerance) does not satisfy the above condition (is not within tolerance of the target probability). For target probabilities greater than 0.5 we give the SRV such that the probability for (SRV_found+toloerance) will not be within tolerance of the target probability.

The cases where exceedProb = 0.0 or 1.0 are treated explicity (e.g., Double.POSITIVE_INFINITY or Double.NEGATIVE_INFINITY are returned if no truncation is applied).

Note that the result is not necessarily symmetric in that getStandRandVar(prob,*) may not exactly equal the negative of getStandRandVar((1-prob),*). This simply represents the lack of numerical precision under some conditions, with the problem worsening for greater tolerances and as the input probability approaches zero or one. For example,

getStandRandVar(0.0001,0,2,1e-6) = 3.72
getStandRandVar(0.9999,0,2,1e-6) = -3.72

getStandRandVar(0.000001,0,2,1e-6) = 4.76
getStandRandVar(0.999999,0,2,1e-6) = -4.62

Parameters:

exceedProb - The target exceedance probability

lowerTruncLevel - The lower truncation level must be < 0

upperTruncLevel - The upper truncation level must be ??? 0

tolerance - The tolerance

Returns:

The SRV found for the target exceedProb

test1_getStandRandVar

public static boolean test1_getStandRandVar(double tol,
                                            int trTyp,
                                            double trLev)

This method tests the getStandRandVar() method over a wide range of input probabilities for a given tolerance, truncation type, and truncation value (the range of probabilites tested are those computed from getExceedProb() for SRV from -7.5 to 7.5). Specifically, if

SRV_found = getStandRandVar(Prob_target, trTyp, trLev, tol)

and

Prob_implied = getExceedProb(SRV_found, trTyp, trLev)

this makes sure that

abs(Prob_target-Prob_implied) < tol*Prob_target

This also ensures that the probability for SRV_found+tol (or SRV_found-tol) is more than tolerance from Prob_target (the above test fails; to make sure whe have the SRV closest to zero, since some SRV's farther from zero will satisfy the first test as well.

Parameters:

tol - tolerance

trTyp - truncation type

trLev - truncation level

Returns:

boolean (true if all tests successful)

test2_getStandRandVar

public static void test2_getStandRandVar()

This runs test1_getStandRandVar() over a range of tolerances, truncation types, and trucation levels.

testSpeed_getStandRandVar

public static void testSpeed_getStandRandVar()

This tests the influence of tolerance on performance. Tolerances of 0.1 and 1e-3 take about the same amount of time; tolerance of 1e-6 takes a little less than twice as long.

test_symmetry_getStandRandVar

public static void test_symmetry_getStandRandVar()

main

public static void main(String[] args)

main method for running tests