ProbabilityIntegralTransformTest.java

  1. package org.drip.validation.hypothesis;

  3. /*
  4.  * -*- mode: java; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*-
  5.  */

  7. /*!
  8.  * Copyright (C) 2020 Lakshmi Krishnamurthy
  9.  * Copyright (C) 2019 Lakshmi Krishnamurthy
  10.  * 
  11.  *  This file is part of DROP, an open-source library targeting analytics/risk, transaction cost analytics,
  12.  *      asset liability management analytics, capital, exposure, and margin analytics, valuation adjustment
  13.  *      analytics, and portfolio construction analytics within and across fixed income, credit, commodity,
  14.  *      equity, FX, and structured products. It also includes auxiliary libraries for algorithm support,
  15.  *      numerical analysis, numerical optimization, spline builder, model validation, statistical learning,
  16.  *      and computational support.
  17.  *  
  18.  *      https://lakshmidrip.github.io/DROP/
  19.  *  
  20.  *  DROP is composed of three modules:
  21.  *  
  22.  *  - DROP Product Core - https://lakshmidrip.github.io/DROP-Product-Core/
  23.  *  - DROP Portfolio Core - https://lakshmidrip.github.io/DROP-Portfolio-Core/
  24.  *  - DROP Computational Core - https://lakshmidrip.github.io/DROP-Computational-Core/
  25.  * 
  26.  *  DROP Product Core implements libraries for the following:
  27.  *  - Fixed Income Analytics
  28.  *  - Loan Analytics
  29.  *  - Transaction Cost Analytics
  30.  * 
  31.  *  DROP Portfolio Core implements libraries for the following:
  32.  *  - Asset Allocation Analytics
  33.  *  - Asset Liability Management Analytics
  34.  *  - Capital Estimation Analytics
  35.  *  - Exposure Analytics
  36.  *  - Margin Analytics
  37.  *  - XVA Analytics
  38.  * 
  39.  *  DROP Computational Core implements libraries for the following:
  40.  *  - Algorithm Support
  41.  *  - Computation Support
  42.  *  - Function Analysis
  43.  *  - Model Validation
  44.  *  - Numerical Analysis
  45.  *  - Numerical Optimizer
  46.  *  - Spline Builder
  47.  *  - Statistical Learning
  48.  * 
  49.  *  Documentation for DROP is Spread Over:
  50.  * 
  51.  *  - Main                     => https://lakshmidrip.github.io/DROP/
  52.  *  - Wiki                     => https://github.com/lakshmiDRIP/DROP/wiki
  53.  *  - GitHub                   => https://github.com/lakshmiDRIP/DROP
  54.  *  - Repo Layout Taxonomy     => https://github.com/lakshmiDRIP/DROP/blob/master/Taxonomy.md
  55.  *  - Javadoc                  => https://lakshmidrip.github.io/DROP/Javadoc/index.html
  56.  *  - Technical Specifications => https://github.com/lakshmiDRIP/DROP/tree/master/Docs/Internal
  57.  *  - Release Versions         => https://lakshmidrip.github.io/DROP/version.html
  58.  *  - Community Credits        => https://lakshmidrip.github.io/DROP/credits.html
  59.  *  - Issues Catalog           => https://github.com/lakshmiDRIP/DROP/issues
  60.  *  - JUnit                    => https://lakshmidrip.github.io/DROP/junit/index.html
  61.  *  - Jacoco                   => https://lakshmidrip.github.io/DROP/jacoco/index.html
  62.  * 
  63.  *  Licensed under the Apache License, Version 2.0 (the "License");
  64.  *      you may not use this file except in compliance with the License.
  65.  *   
  66.  *  You may obtain a copy of the License at
  67.  *      http://www.apache.org/licenses/LICENSE-2.0
  68.  *  
  69.  *  Unless required by applicable law or agreed to in writing, software
  70.  *      distributed under the License is distributed on an "AS IS" BASIS,
  71.  *      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  72.  *  
  73.  *  See the License for the specific language governing permissions and
  74.  *      limitations under the License.
  75.  */

  77. /**
  78.  * <i>ProbabilityIntegralTransformTest</i> implements Comparison Tests post a PIT Transform on the Hypothesis
  79.  * and/or Test Sample.
  80.  *
  81.  *  <br><br>
  82.  *  <ul>
  83.  *      <li>
  84.  *          Bhattacharya, B., and D. Habtzghi (2002): Median of the p-value under the Alternate Hypothesis
  85.  *              American Statistician 56 (3) 202-206
  86.  *      </li>
  87.  *      <li>
  88.  *          Head, M. L., L. Holman, R, Lanfear, A. T. Kahn, and M. D. Jennions (2015): The Extent and
  89.  *              Consequences of p-Hacking in Science PLoS Biology 13 (3) e1002106
  90.  *      </li>
  91.  *      <li>
  92.  *          Wasserstein, R. L., and N. A. Lazar (2016): The ASA’s Statement on p-values: Context, Process,
  93.  *              and Purpose American Statistician 70 (2) 129-133
  94.  *      </li>
  95.  *      <li>
  96.  *          Wetzels, R., D. Matzke, M. D. Lee, J. N. Rouder, G, J, Iverson, and E. J. Wagenmakers (2011):
  97.  *          Statistical Evidence in Experimental Psychology: An Empirical Comparison using 855 t-Tests
  98.  *          Perspectives in Psychological Science 6 (3) 291-298
  99.  *      </li>
  100.  *      <li>
  101.  *          Wikipedia (2019): p-value https://en.wikipedia.org/wiki/P-value
  102.  *      </li>
  103.  *  </ul>
  104.  *
  105.  *  <br><br>
  106.  *  <ul>
  107.  *      <li><b>Module </b> = <a href = "https://github.com/lakshmiDRIP/DROP/tree/master/ComputationalCore.md">Computational Core Module</a></li>
  108.  *      <li><b>Library</b> = <a href = "https://github.com/lakshmiDRIP/DROP/tree/master/ModelValidationAnalyticsLibrary.md">Model Validation Analytics Library</a></li>
  109.  *      <li><b>Project</b> = <a href = "https://github.com/lakshmiDRIP/DROP/tree/master/src/main/java/org/drip/validation/README.md">Risk Factor and Hypothesis Validation, Evidence Processing, and Model Testing</a></li>
  110.  *      <li><b>Package</b> = <a href = "https://github.com/lakshmiDRIP/DROP/tree/master/src/main/java/org/drip/validation/hypothesis/README.md">Statistical Hypothesis Validation Test Suite</a></li>
  111.  *  </ul>
  112.  * <br><br>
  113.  *
  114.  * @author Lakshmi Krishnamurthy
  115.  */

  117. public class ProbabilityIntegralTransformTest
  118. {
  119.     private org.drip.validation.hypothesis.ProbabilityIntegralTransform _probabilityIntegralTransform = null;

  121.     /**
  122.      * ProbabilityIntegralTransformTest Constructor
  123.      * 
  124.      * @param probabilityIntegralTransform The Probability Integral Transform Instance
  125.      * 
  126.      * @throws java.lang.Exception Thrown if the Inputs are Invalid
  127.      */

  129.     public ProbabilityIntegralTransformTest (
  130.         final org.drip.validation.hypothesis.ProbabilityIntegralTransform probabilityIntegralTransform)
  131.         throws java.lang.Exception
  132.     {
  133.         if (null == (_probabilityIntegralTransform = probabilityIntegralTransform))
  134.         {
  135.             throw new java.lang.Exception ("ProbabilityIntegralTransformTest Constructor => Invalid Inputs");
  136.         }
  137.     }

  139.     /**
  140.      * Retrieve the ProbabilityIntegralTransform Instance
  141.      * 
  142.      * @return The ProbabilityIntegralTransform Instance
  143.      */

  145.     public org.drip.validation.hypothesis.ProbabilityIntegralTransform probabilityIntegralTransform()
  146.     {
  147.         return _probabilityIntegralTransform;
  148.     }

  150.     /**
  151.      * Run the Significance Test for the Realized Test Statistic
  152.      * 
  153.      * @param testStatistic The Realized Test Statistic
  154.      * @param pTestSetting The P-Test Setting
  155.      * 
  156.      * @return The Significance Test Result for the Realized Test Statistic
  157.      */

  159.     public org.drip.validation.hypothesis.SignificanceTestOutcome significanceTest (
  160.         final double testStatistic,
  161.         final org.drip.validation.hypothesis.SignificanceTestSetting pTestSetting)
  162.     {
  163.         if (!org.drip.numerical.common.NumberUtil.IsValid (testStatistic) || null == pTestSetting)
  164.         {
  165.             return null;
  166.         }

  168.         double pValue = java.lang.Double.NaN;

  170.         try
  171.         {
  172.             pValue = _probabilityIntegralTransform.pValue (testStatistic);
  173.         }
  174.         catch (java.lang.Exception e)
  175.         {
  176.             e.printStackTrace();

  178.             return null;
  179.         }

  181.         int tailCheck = pTestSetting.tailCheck();

  183.         double threshold = pTestSetting.threshold();

  185.         if (org.drip.validation.hypothesis.SignificanceTestSetting.LEFT_TAIL_CHECK == tailCheck)
  186.         {
  187.             try
  188.             {
  189.                 return new SignificanceTestOutcome (
  190.                     testStatistic,
  191.                     1. - pValue,
  192.                     pValue,
  193.                     pValue > threshold
  194.                 );
  195.             }
  196.             catch (java.lang.Exception e)
  197.             {
  198.                 e.printStackTrace();

  200.                 return null;
  201.             }
  202.         }

  204.         if (org.drip.validation.hypothesis.SignificanceTestSetting.RIGHT_TAIL_CHECK == tailCheck)
  205.         {
  206.             try
  207.             {
  208.                 return new SignificanceTestOutcome (
  209.                     testStatistic,
  210.                     1. - pValue,
  211.                     pValue,
  212.                     1. - pValue > threshold
  213.                 );
  214.             }
  215.             catch (java.lang.Exception e)
  216.             {
  217.                 e.printStackTrace();

  219.                 return null;
  220.             }
  221.         }

  223.         try
  224.         {
  225.             return new SignificanceTestOutcome (
  226.                 testStatistic,
  227.                 1. - pValue,
  228.                 pValue,
  229.                 2. * java.lang.Math.min (
  230.                     pValue,
  231.                     1. - pValue
  232.                 ) > threshold
  233.             );
  234.         }
  235.         catch (java.lang.Exception e)
  236.         {
  237.             e.printStackTrace();
  238.         }

  240.         return null;
  241.     }

  243.     /**
  244.      * Run a Distance Gap Test between the Hypothesis and the Sample
  245.      * 
  246.      * @param samplePIT The Sample Probability Integral Transform
  247.      * @param gapTestSetting The Distance Gap Test Setting
  248.      * 
  249.      * @return The Distance Gap Test Outcome
  250.      */

  252.     public org.drip.validation.distance.GapTestOutcome distanceTest (
  253.         final org.drip.validation.hypothesis.ProbabilityIntegralTransform samplePIT,
  254.         final org.drip.validation.distance.GapTestSetting gapTestSetting)
  255.     {
  256.         if (null == samplePIT || null == gapTestSetting)
  257.         {
  258.             return null;
  259.         }

  261.         double distance = 0.;
  262.         double hypothesisPValueLeft = 0.;

  264.         org.drip.validation.distance.GapLossFunction gapLossFunction = gapTestSetting.lossFunction();

  266.         org.drip.validation.distance.GapLossWeightFunction gapLossWeightFunction =
  267.             gapTestSetting.lossWeightFunction();

  269.         org.drip.validation.evidence.TestStatisticAccumulator weightedGapLossAccumulator = new
  270.             org.drip.validation.evidence.TestStatisticAccumulator();

  272.         org.drip.validation.evidence.TestStatisticAccumulator unweightedGapLossAccumulator = new
  273.             org.drip.validation.evidence.TestStatisticAccumulator();

  275.         for (java.util.Map.Entry<java.lang.Double, java.lang.Double> testStatisticPValueEntry :
  276.             samplePIT.testStatisticPValueMap().entrySet())
  277.         {
  278.             try
  279.             {
  280.                 double hypothesisPValueRight = _probabilityIntegralTransform.pValue
  281.                     (testStatisticPValueEntry.getKey());

  283.                 double gapLoss = gapLossFunction.loss (testStatisticPValueEntry.getValue() -
  284.                     hypothesisPValueRight);

  286.                 double weightedGapLoss = gapLoss * gapLossWeightFunction.weight (hypothesisPValueRight);

  288.                 distance = distance + weightedGapLoss * (hypothesisPValueRight - hypothesisPValueLeft);

  290.                 if (!unweightedGapLossAccumulator.addTestStatistic (gapLoss) ||
  291.                     !weightedGapLossAccumulator.addTestStatistic (weightedGapLoss))
  292.                 {
  293.                     return null;
  294.                 }

  296.                 hypothesisPValueLeft = hypothesisPValueRight;
  297.             }
  298.             catch (java.lang.Exception e)
  299.             {
  300.                 e.printStackTrace();

  302.                 return null;
  303.             }
  304.         }

  306.         try
  307.         {
  308.             return new org.drip.validation.distance.GapTestOutcome (
  309.                 unweightedGapLossAccumulator.probabilityIntegralTransform(),
  310.                 weightedGapLossAccumulator.probabilityIntegralTransform(),
  311.                 distance
  312.             );
  313.         }
  314.         catch (java.lang.Exception e)
  315.         {
  316.             e.printStackTrace();
  317.         }

  319.         return null;
  320.     }

  322.     /**
  323.      * Run a Histogram Test Corresponding to the Test Statistic and its p-Value
  324.      * 
  325.      * @param histogramTestSetting The Histogram Test Setting
  326.      * 
  327.      * @return The Histogram Test Corresponding to the Test Statistic and its p-Value
  328.      */

  330.     public org.drip.validation.hypothesis.HistogramTestOutcome histogramTest (
  331.         final org.drip.validation.hypothesis.HistogramTestSetting histogramTestSetting)
  332.     {
  333.         if (null == histogramTestSetting)
  334.         {
  335.             return null;
  336.         }

  338.         org.drip.validation.quantile.PlottingPositionGenerator plottingPositionGenerator =
  339.             histogramTestSetting.plottingPositionGenerator();

  341.         org.drip.validation.quantile.PlottingPosition[] plottingPositionArray =
  342.             plottingPositionGenerator.generate();

  344.         int qqVertexCount = plottingPositionArray.length + 2;
  345.         double[] testStatisticArray = new double[qqVertexCount];
  346.         double[] pValueCumulativeArray = new double[qqVertexCount];
  347.         double[] pValueIncrementalArray = new double[qqVertexCount];

  349.         try
  350.         {
  351.             pValueIncrementalArray[0] = 0.;

  353.             testStatisticArray[0] = _probabilityIntegralTransform.testStatistic
  354.                 (pValueCumulativeArray[0] = 0.);

  356.             testStatisticArray[qqVertexCount - 1] = _probabilityIntegralTransform.testStatistic
  357.                 (pValueCumulativeArray[qqVertexCount - 1] = 1.);
  358.         }
  359.         catch (java.lang.Exception e)
  360.         {
  361.             e.printStackTrace();

  363.             return null;
  364.         }

  366.         for (int qqVertexIndex = 1; qqVertexIndex < qqVertexCount - 1; ++qqVertexIndex)
  367.         {
  368.             try
  369.             {
  370.                 testStatisticArray[qqVertexIndex] = _probabilityIntegralTransform.testStatistic
  371.                     (pValueCumulativeArray[qqVertexIndex] =
  372.                         plottingPositionArray[qqVertexIndex - 1].quantile());

  374.                 pValueIncrementalArray[qqVertexIndex] = pValueCumulativeArray[qqVertexIndex] -
  375.                     pValueCumulativeArray[qqVertexIndex - 1];
  376.             }
  377.             catch (java.lang.Exception e)
  378.             {
  379.                 e.printStackTrace();

  381.                 return null;
  382.             }
  383.         }

  385.         pValueIncrementalArray[qqVertexCount - 1] = pValueCumulativeArray[qqVertexCount - 1] -
  386.             pValueCumulativeArray[qqVertexCount - 2];

  388.         try
  389.         {
  390.             return new org.drip.validation.hypothesis.HistogramTestOutcome (
  391.                 testStatisticArray,
  392.                 pValueCumulativeArray,
  393.                 pValueIncrementalArray,
  394.                 _probabilityIntegralTransform.testStatistic (histogramTestSetting.pValueThreshold())
  395.             );
  396.         }
  397.         catch (java.lang.Exception e)
  398.         {
  399.             e.printStackTrace();
  400.         }

  402.         return null;
  403.     }

  405.     /**
  406.      * Run the Quantile-Quantile Test
  407.      * 
  408.      * @param samplePIT The Sample Probability Integral Transform
  409.      * @param plottingPositionGenerator The Quantile-Quantile Test Plotting Position Generator
  410.      * 
  411.      * @return The Quantile-Quantile Test Outcome
  412.      */

  414.     public org.drip.validation.quantile.QQTestOutcome qqTest (
  415.         final org.drip.validation.hypothesis.ProbabilityIntegralTransform samplePIT,
  416.         final org.drip.validation.quantile.PlottingPositionGenerator plottingPositionGenerator)
  417.     {
  418.         if (null == samplePIT || null == plottingPositionGenerator)
  419.         {
  420.             return null;
  421.         }

  423.         org.drip.validation.quantile.PlottingPosition[] plottingPositionArray =
  424.             plottingPositionGenerator.generate();

  426.         if (null == plottingPositionArray)
  427.         {
  428.             return null;
  429.         }

  431.         int orderStatisticCount = plottingPositionArray.length;
  432.         org.drip.validation.quantile.QQVertex[] qqVertexArray = new
  433.             org.drip.validation.quantile.QQVertex[orderStatisticCount];

  435.         for (int orderStatisticIndex = 0; orderStatisticIndex < orderStatisticCount; ++orderStatisticIndex)
  436.         {
  437.             try
  438.             {
  439.                 double pValue = plottingPositionArray[orderStatisticIndex].quantile();
  440.         
  441.                 qqVertexArray[orderStatisticIndex] = new org.drip.validation.quantile.QQVertex (
  442.                     plottingPositionArray[orderStatisticIndex],
  443.                     samplePIT.testStatistic (pValue),
  444.                     _probabilityIntegralTransform.testStatistic (pValue)
  445.                 );
  446.             }
  447.             catch (java.lang.Exception e)
  448.             {
  449.                 e.printStackTrace();

  451.                 return null;
  452.             }
  453.         }

  455.         try
  456.         {
  457.             return new org.drip.validation.quantile.QQTestOutcome (qqVertexArray);
  458.         }
  459.         catch (java.lang.Exception e)
  460.         {
  461.             e.printStackTrace();
  462.         }

  464.         return null;
  465.     }
  466. }
Created with JaCoCo 0.7.9.201702052155