UnitSequenceAgnosticMetrics.java

  1. package org.drip.sequence.metrics;

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

  7. /*!
  8.  * Copyright (C) 2019 Lakshmi Krishnamurthy
  9.  * Copyright (C) 2018 Lakshmi Krishnamurthy
  10.  * Copyright (C) 2017 Lakshmi Krishnamurthy
  11.  * Copyright (C) 2016 Lakshmi Krishnamurthy
  12.  * Copyright (C) 2015 Lakshmi Krishnamurthy
  13.  * 
  14.  *  This file is part of DROP, an open-source library targeting risk, transaction costs, exposure, margin
  15.  *      calculations, and portfolio construction within and across fixed income, credit, commodity, equity,
  16.  *      FX, and structured products.
  17.  *  
  18.  *      https://lakshmidrip.github.io/DROP/
  19.  *  
  20.  *  DROP is composed of three main modules:
  21.  *  
  22.  *  - DROP Analytics Core - https://lakshmidrip.github.io/DROP-Analytics-Core/
  23.  *  - DROP Portfolio Core - https://lakshmidrip.github.io/DROP-Portfolio-Core/
  24.  *  - DROP Numerical Core - https://lakshmidrip.github.io/DROP-Numerical-Core/
  25.  * 
  26.  *  DROP Analytics Core implements libraries for the following:
  27.  *  - Fixed Income Analytics
  28.  *  - Asset Backed Analytics
  29.  *  - XVA Analytics
  30.  *  - Exposure and Margin Analytics
  31.  * 
  32.  *  DROP Portfolio Core implements libraries for the following:
  33.  *  - Asset Allocation Analytics
  34.  *  - Transaction Cost Analytics
  35.  * 
  36.  *  DROP Numerical Core implements libraries for the following:
  37.  *  - Statistical Learning Library
  38.  *  - Numerical Optimizer Library
  39.  *  - Machine Learning Library
  40.  *  - Spline Builder Library
  41.  * 
  42.  *  Documentation for DROP is Spread Over:
  43.  * 
  44.  *  - Main                     => https://lakshmidrip.github.io/DROP/
  45.  *  - Wiki                     => https://github.com/lakshmiDRIP/DROP/wiki
  46.  *  - GitHub                   => https://github.com/lakshmiDRIP/DROP
  47.  *  - Javadoc                  => https://lakshmidrip.github.io/DROP/Javadoc/index.html
  48.  *  - Technical Specifications => https://github.com/lakshmiDRIP/DROP/tree/master/Docs/Internal
  49.  *  - Release Versions         => https://lakshmidrip.github.io/DROP/version.html
  50.  *  - Community Credits        => https://lakshmidrip.github.io/DROP/credits.html
  51.  *  - Issues Catalog           => https://github.com/lakshmiDRIP/DROP/issues
  52.  *  - JUnit                    => https://lakshmidrip.github.io/DROP/junit/index.html
  53.  *  - Jacoco                   => https://lakshmidrip.github.io/DROP/jacoco/index.html
  54.  * 
  55.  *  Licensed under the Apache License, Version 2.0 (the "License");
  56.  *      you may not use this file except in compliance with the License.
  57.  *   
  58.  *  You may obtain a copy of the License at
  59.  *      http://www.apache.org/licenses/LICENSE-2.0
  60.  *  
  61.  *  Unless required by applicable law or agreed to in writing, software
  62.  *      distributed under the License is distributed on an "AS IS" BASIS,
  63.  *      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  64.  *  
  65.  *  See the License for the specific language governing permissions and
  66.  *      limitations under the License.
  67.  */

  69. /**
  70.  * <i>UnitSequenceAgnosticMetrics</i> contains the Sample Distribution Metrics and Agnostic Bounds related to
  71.  * the specified Bounded [0, 1] Sequence.
  72.  * 
  73.  * <br><br>
  74.  *  <ul>
  75.  *      <li><b>Module </b> = <a href = "https://github.com/lakshmiDRIP/DROP/tree/master/NumericalCore.md">Numerical Core Module</a></li>
  76.  *      <li><b>Library</b> = <a href = "https://github.com/lakshmiDRIP/DROP/tree/master/StatisticalLearningLibrary.md">Statistical Learning Library</a></li>
  77.  *      <li><b>Project</b> = <a href = "https://github.com/lakshmiDRIP/DROP/tree/master/src/main/java/org/drip/sequence">Sequence</a></li>
  78.  *      <li><b>Package</b> = <a href = "https://github.com/lakshmiDRIP/DROP/tree/master/src/main/java/org/drip/sequence/metrics">Metrics</a></li>
  79.  *  </ul>
  80.  * <br><br>
  81.  *
  82.  * @author Lakshmi Krishnamurthy
  83.  */

  85. public class UnitSequenceAgnosticMetrics extends org.drip.sequence.metrics.BoundedSequenceAgnosticMetrics
  86. {
  87.     private double _dblPopulationMean = java.lang.Double.NaN;

  89.     /**
  90.      * UnitSequenceAgnosticMetrics Constructor
  91.      * 
  92.      * @param adblSequence The Random Sequence
  93.      * @param dblPopulationMean The Mean of the Underlying Distribution
  94.      * 
  95.      * @throws java.lang.Exception Thrown if UnitSequenceAgnosticMetrics cannot be constructed
  96.      */

  98.     public UnitSequenceAgnosticMetrics (
  99.         final double[] adblSequence,
  100.         final double dblPopulationMean)
  101.         throws java.lang.Exception
  102.     {
  103.         super (adblSequence, null, 1.);

  105.         _dblPopulationMean = dblPopulationMean;
  106.     }

  108.     /**
  109.      * Retrieve the Mean of the Underlying Distribution
  110.      * 
  111.      * @return The Mean of the Underlying Distribution
  112.      */

  114.     public double populationMean()
  115.     {
  116.         return _dblPopulationMean;
  117.     }

  119.     /**
  120.      * Compute the Chernoff Binomial Upper Bound
  121.      * 
  122.      * @param dblLevel The Level at which the Bound is sought
  123.      * 
  124.      * @return The Chernoff Binomial Upper Bound
  125.      * 
  126.      * @throws java.lang.Exception Thrown if the Chernoff Binomial Upper Bound cannot be computed
  127.      */

  129.     public double chernoffBinomialUpperBound (
  130.         final double dblLevel)
  131.         throws java.lang.Exception
  132.     {
  133.         if (!org.drip.numerical.common.NumberUtil.IsValid (dblLevel) || 1. < dblLevel)
  134.             throw new java.lang.Exception
  135.                 ("UnitSequenceAgnosticMetrics::chernoffBinomialUpperBound => Invalid Inputs");

  137.         int iNumEntry = sequence().length;

  139.         double dblPopulationMean = org.drip.numerical.common.NumberUtil.IsValid (_dblPopulationMean) ?
  140.             _dblPopulationMean : empiricalExpectation();

  142.         double dblBound = java.lang.Math.pow (dblPopulationMean / dblLevel, iNumEntry * dblLevel) *
  143.             java.lang.Math.pow ((1. - dblPopulationMean) / (1. - dblLevel), iNumEntry * (1. - dblLevel));

  145.         if (!org.drip.numerical.common.NumberUtil.IsValid (dblBound)) return 0.;

  147.         return dblBound > 1. ? 1. : dblBound;
  148.     }

  150.     /**
  151.      * Compute the Chernoff-Poisson Binomial Upper Bound
  152.      * 
  153.      * @param dblLevel The Level at which the Bound is sought
  154.      * 
  155.      * @return The Chernoff-Poisson Binomial Upper Bound
  156.      * 
  157.      * @throws java.lang.Exception Thrown if the Chernoff-Poisson Binomial Upper Bound cannot be computed
  158.      */

  160.     public double chernoffPoissonUpperBound (
  161.         final double dblLevel)
  162.         throws java.lang.Exception
  163.     {
  164.         if (!org.drip.numerical.common.NumberUtil.IsValid (dblLevel) || 1. < dblLevel)
  165.             throw new java.lang.Exception
  166.                 ("UnitSequenceAgnosticMetrics::ChernoffBinomialUpperBound => Invalid Inputs");

  168.         int iNumEntry = sequence().length;

  170.         double dblPopulationMean = org.drip.numerical.common.NumberUtil.IsValid (_dblPopulationMean) ?
  171.             _dblPopulationMean : empiricalExpectation();

  173.         double dblBound = java.lang.Math.pow (dblPopulationMean / dblLevel, iNumEntry * dblLevel) *
  174.             java.lang.Math.exp (iNumEntry * (dblLevel - dblPopulationMean));

  176.         if (!org.drip.numerical.common.NumberUtil.IsValid (dblBound)) return 0.;

  178.         return dblBound > 1. ? 1. : dblBound;
  179.     }

  181.     /**
  182.      * Compute the Karp/Hagerup/Rub Pivot Departure Bounds outlined below:
  183.      * 
  184.      *  - Karp, R. M. (1988): Probabilistic Analysis of Algorithms, University of California, Berkeley.
  185.      *  - Hagerup, T., and C. Rub (1990): A Guided Tour of Chernoff Bounds, Information Processing Letters,
  186.      *      33:305-308.
  187.      * 
  188.      * @param dblLevel The Level at which the Bound is sought
  189.      * 
  190.      * @return The Karp/Hagerup/Rub Pivot Departure Bounds
  191.      */

  193.     public org.drip.sequence.metrics.PivotedDepartureBounds karpHagerupRubBounds (
  194.         final double dblLevel)
  195.     {
  196.         if (!org.drip.numerical.common.NumberUtil.IsValid (dblLevel) || 1. < dblLevel) return null;

  198.         int iNumEntry = sequence().length;

  200.         double dblPopulationMean = org.drip.numerical.common.NumberUtil.IsValid (_dblPopulationMean) ?
  201.             _dblPopulationMean : empiricalExpectation();

  203.         double dblScaledLevel = dblLevel / dblPopulationMean;

  205.         double dblLowerBound = java.lang.Math.exp (-0.5 * dblPopulationMean * iNumEntry * dblScaledLevel *
  206.             dblScaledLevel);

  208.         if (!org.drip.numerical.common.NumberUtil.IsValid (dblLowerBound)) dblLowerBound = 0.;

  210.         double dblUpperBound = java.lang.Math.exp (-1. * dblPopulationMean * iNumEntry * (1. +
  211.             dblScaledLevel) * java.lang.Math.log (1. + dblScaledLevel) - dblScaledLevel);

  213.         if (!org.drip.numerical.common.NumberUtil.IsValid (dblUpperBound)) dblUpperBound = 0.;

  215.         try {
  216.             return new org.drip.sequence.metrics.PivotedDepartureBounds
  217.                 (org.drip.sequence.metrics.PivotedDepartureBounds.PIVOT_ANCHOR_TYPE_MEAN,
  218.                     java.lang.Double.NaN, dblLowerBound > 1. ? 1. : dblLowerBound, dblUpperBound > 1. ? 1. :
  219.                         dblUpperBound);
  220.         } catch (java.lang.Exception e) {
  221.             e.printStackTrace();
  222.         }

  224.         return null;
  225.     }
  226. }
Created with JaCoCo 0.7.9.201702052155