EmpiricalPenaltySupremumEstimator.java

  1. package org.drip.learning.rxtor1;

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

  81. /**
  82.  * <i>EmpiricalPenaltySupremumEstimator</i> contains the Implementation of the Empirical Penalty Supremum
  83.  * Estimator dependent on Multivariate Random Variables where the Multivariate Function is a Linear
  84.  * Combination of Bounded Univariate Functions acting on each Random Variate.
  85.  *
  86.  *  <br><br>
  87.  *  <ul>
  88.  *      <li><b>Module </b> = <a href = "https://github.com/lakshmiDRIP/DROP/tree/master/ComputationalCore.md">Computational Core Module</a></li>
  89.  *      <li><b>Library</b> = <a href = "https://github.com/lakshmiDRIP/DROP/tree/master/StatisticalLearningLibrary.md">Statistical Learning</a></li>
  90.  *      <li><b>Project</b> = <a href = "https://github.com/lakshmiDRIP/DROP/tree/master/src/main/java/org/drip/learning">Agnostic Learning Bounds under Empirical Loss Minimization Schemes</a></li>
  91.  *      <li><b>Package</b> = <a href = "https://github.com/lakshmiDRIP/DROP/tree/master/src/main/java/org/drip/learning/rxtor1">Statistical Learning Empirical Loss Penalizer</a></li>
  92.  *  </ul>
  93.  *
  94.  * @author Lakshmi Krishnamurthy
  95.  */

  97. public class EmpiricalPenaltySupremumEstimator extends org.drip.sequence.functional.BoundedMultivariateRandom {

  99.     /**
  100.      * Supremum Penalty computed off of Empirical Loss
  101.      */

  103.     public static final int SUPREMUM_PENALTY_EMPIRICAL_LOSS = 1;

  105.     /**
  106.      * Supremum Penalty computed off of Structural Loss
  107.      */

  109.     public static final int SUPREMUM_PENALTY_STRUCTURAL_LOSS = 2;

  111.     /**
  112.      * Supremum Penalty computed off of Regularized Loss
  113.      */

  115.     public static final int SUPREMUM_PENALTY_REGULARIZED_LOSS = 4;

  117.     /**
  118.      * Supremum Penalty computed off of Empirical Risk
  119.      */

  121.     public static final int SUPREMUM_PENALTY_EMPIRICAL_RISK = 8;

  123.     /**
  124.      * Supremum Penalty computed off of Structural Risk
  125.      */

  127.     public static final int SUPREMUM_PENALTY_STRUCTURAL_RISK = 16;

  129.     /**
  130.      * Supremum Penalty computed off of Regularized Risk
  131.      */

  133.     public static final int SUPREMUM_PENALTY_REGULARIZED_RISK = 32;

  135.     private int _iSupremumPenaltyLossMode = -1;
  136.     private org.drip.measure.continuous.R1R1 _distR1R1 = null;
  137.     private org.drip.measure.continuous.RdR1 _distRdR1 = null;
  138.     private org.drip.spaces.rxtor1.NormedR1ToNormedR1[] _aR1ToR1 = null;
  139.     private org.drip.spaces.rxtor1.NormedRdToNormedR1[] _aRdToR1 = null;
  140.     private org.drip.spaces.instance.GeneralizedValidatedVector _gvviY = null;
  141.     private org.drip.learning.rxtor1.EmpiricalLearningMetricEstimator _elme = null;

  143.     /**
  144.      * EmpiricalPenaltySupremumEstimator Constructor
  145.      * 
  146.      * @param iSupremumPenaltyLossMode Supremum Loss Penalty Mode
  147.      * @param elme The Empirical Learning Metric Estimator Instance
  148.      * @param gvviY The Validated Outcome Instance
  149.      * @param distR1R1 R^1 R^1 Multivariate Measure
  150.      * @param distRdR1 R^d R^1 Multivariate Measure
  151.      * 
  152.      * @throws java.lang.Exception Thrown if the Inputs are Invalid
  153.      */

  155.     public EmpiricalPenaltySupremumEstimator (
  156.         final int iSupremumPenaltyLossMode,
  157.         final org.drip.learning.rxtor1.EmpiricalLearningMetricEstimator elme,
  158.         final org.drip.spaces.instance.GeneralizedValidatedVector gvviY,
  159.         final org.drip.measure.continuous.R1R1 distR1R1,
  160.         final org.drip.measure.continuous.RdR1 distRdR1)
  161.         throws java.lang.Exception
  162.     {
  163.         if (null == (_elme = elme))
  164.             throw new java.lang.Exception ("EmpiricalPenaltySupremumEstimator ctr: Invalid Inputs");

  166.         org.drip.spaces.rxtor1.NormedRxToNormedR1[] aRxToR1 = _elme.functionClass().functionSpaces();

  168.         if (null == aRxToR1)
  169.             throw new java.lang.Exception ("EmpiricalPenaltySupremumEstimator ctr: Invalid Inputs");

  171.         if (aRxToR1 instanceof org.drip.spaces.rxtor1.NormedR1ToNormedR1[])
  172.             _aR1ToR1 = (org.drip.spaces.rxtor1.NormedR1ToNormedR1[]) aRxToR1;
  173.         else
  174.             _aRdToR1 = (org.drip.spaces.rxtor1.NormedRdToNormedR1[]) aRxToR1;

  176.         _gvviY = gvviY;
  177.         _distR1R1 = distR1R1;
  178.         _distRdR1 = distRdR1;
  179.         int iNumRxToR1 = aRxToR1.length;
  180.         _iSupremumPenaltyLossMode = iSupremumPenaltyLossMode;

  182.         if (SUPREMUM_PENALTY_EMPIRICAL_LOSS == _iSupremumPenaltyLossMode && null == _gvviY)
  183.             throw new java.lang.Exception ("EmpiricalPenaltySupremumEstimator ctr: Invalid Inputs");

  185.         for (int i = 0; i < iNumRxToR1; ++i) {
  186.             if (null == aRxToR1[i])
  187.                 throw new java.lang.Exception ("EmpiricalPenaltySupremumEstimator ctr: Invalid Inputs");
  188.         }
  189.     }

  191.     /**
  192.      * The Supremum Penalty Loss Mode Flag
  193.      * 
  194.      * @return The Supremum Penalty Loss Mode Flag
  195.      */

  197.     public int supremumPenaltyLossMode()
  198.     {
  199.         return _iSupremumPenaltyLossMode;
  200.     }

  202.     /**
  203.      * Retrieve the Empirical Learning Metric Estimator Instance
  204.      * 
  205.      * @return The Empirical Learning Metric Estimator Instance
  206.      */

  208.     public org.drip.learning.rxtor1.EmpiricalLearningMetricEstimator elme()
  209.     {
  210.         return _elme;
  211.     }

  213.     /**
  214.      * Retrieve the Validated Outcome Instance
  215.      * 
  216.      * @return The Validated Outcome Instance
  217.      */

  219.     public org.drip.spaces.instance.GeneralizedValidatedVector empiricalOutcomes()
  220.     {
  221.         return _gvviY;
  222.     }

  224.     /**
  225.      * Compute the Empirical Penalty Supremum for the specified R^1 Input Space
  226.      * 
  227.      * @param gvviX The R^1 Input Space
  228.      * 
  229.      * @return The Empirical Penalty Supremum for the specified R^1 Input Space
  230.      */

  232.     public org.drip.learning.rxtor1.EmpiricalPenaltySupremum supremumR1 (
  233.         final org.drip.spaces.instance.GeneralizedValidatedVector gvviX)
  234.     {
  235.         if (null == _aR1ToR1) return null;

  237.         int iSupremumIndex  = 0;
  238.         int iNumR1ToR1 = _aR1ToR1.length;
  239.         double dblSupremumPenaltyLoss = 0.;

  241.         for (int i = 0 ; i < iNumR1ToR1; ++i) {
  242.             org.drip.function.definition.R1ToR1 funcR1ToR1 = _aR1ToR1[i].function();

  244.             if (null == funcR1ToR1) return null;

  246.             double dblPenaltyLoss = 0.;

  248.             try {
  249.                 if (SUPREMUM_PENALTY_EMPIRICAL_LOSS == _iSupremumPenaltyLossMode)
  250.                     dblPenaltyLoss += _elme.empiricalLoss (funcR1ToR1, gvviX, _gvviY);
  251.                 else if (SUPREMUM_PENALTY_STRUCTURAL_LOSS == _iSupremumPenaltyLossMode)
  252.                     dblPenaltyLoss += _elme.structuralLoss (funcR1ToR1, gvviX);
  253.                 else if (SUPREMUM_PENALTY_REGULARIZED_LOSS == _iSupremumPenaltyLossMode)
  254.                     dblPenaltyLoss += _elme.regularizedLoss (funcR1ToR1, gvviX, _gvviY);
  255.                 else if (SUPREMUM_PENALTY_EMPIRICAL_RISK == _iSupremumPenaltyLossMode)
  256.                     dblPenaltyLoss += _elme.empiricalRisk (_distR1R1, funcR1ToR1, gvviX, _gvviY);
  257.                 else if (SUPREMUM_PENALTY_STRUCTURAL_RISK == _iSupremumPenaltyLossMode)
  258.                     dblPenaltyLoss += _elme.structuralRisk (_distR1R1, funcR1ToR1, gvviX, _gvviY);
  259.                 else if (SUPREMUM_PENALTY_REGULARIZED_RISK == _iSupremumPenaltyLossMode)
  260.                     dblPenaltyLoss += _elme.regularizedRisk (_distR1R1, funcR1ToR1, gvviX, _gvviY);
  261.             } catch (java.lang.Exception e) {
  262.                 e.printStackTrace();

  264.                 return null;
  265.             }

  267.             if (dblPenaltyLoss > dblSupremumPenaltyLoss) {
  268.                 iSupremumIndex = i;
  269.                 dblSupremumPenaltyLoss = dblPenaltyLoss;
  270.             }
  271.         }

  273.         try {
  274.             return new org.drip.learning.rxtor1.EmpiricalPenaltySupremum (iSupremumIndex,
  275.                 dblSupremumPenaltyLoss / gvviX.sampleSize());
  276.         } catch (java.lang.Exception e) {
  277.             e.printStackTrace();
  278.         }

  280.         return null;
  281.     }

  283.     /**
  284.      * Compute the Empirical Penalty Supremum for the specified R^d Input Space
  285.      * 
  286.      * @param gvviX The R^d Input Space
  287.      * 
  288.      * @return The Empirical Penalty Supremum for the specified R^d Input Space
  289.      */

  291.     public org.drip.learning.rxtor1.EmpiricalPenaltySupremum supremumRd (
  292.         final org.drip.spaces.instance.GeneralizedValidatedVector gvviX)
  293.     {
  294.         if (null == _aRdToR1) return null;

  296.         int iSupremumIndex  = 0;
  297.         int iNumRdToR1 = _aRdToR1.length;
  298.         double dblSupremumPenaltyLoss = 0.;

  300.         for (int i = 0 ; i < iNumRdToR1; ++i) {
  301.             org.drip.function.definition.RdToR1 funcRdToR1 = _aRdToR1[i].function();

  303.             if (null == funcRdToR1) return null;

  305.             double dblPenaltyLoss = 0.;

  307.             try {
  308.                 if (SUPREMUM_PENALTY_EMPIRICAL_LOSS == _iSupremumPenaltyLossMode)
  309.                     dblPenaltyLoss += _elme.empiricalLoss (funcRdToR1, gvviX, _gvviY);
  310.                 else if (SUPREMUM_PENALTY_STRUCTURAL_LOSS == _iSupremumPenaltyLossMode)
  311.                     dblPenaltyLoss += _elme.structuralLoss (funcRdToR1, gvviX);
  312.                 else if (SUPREMUM_PENALTY_REGULARIZED_LOSS == _iSupremumPenaltyLossMode)
  313.                     dblPenaltyLoss += _elme.regularizedLoss (funcRdToR1, gvviX, _gvviY);
  314.                 else if (SUPREMUM_PENALTY_EMPIRICAL_RISK == _iSupremumPenaltyLossMode)
  315.                     dblPenaltyLoss += _elme.empiricalRisk (_distRdR1, funcRdToR1, gvviX, _gvviY);
  316.                 else if (SUPREMUM_PENALTY_STRUCTURAL_RISK == _iSupremumPenaltyLossMode)
  317.                     dblPenaltyLoss += _elme.structuralRisk (_distRdR1, funcRdToR1, gvviX, _gvviY);
  318.                 else if (SUPREMUM_PENALTY_REGULARIZED_RISK == _iSupremumPenaltyLossMode)
  319.                     dblPenaltyLoss += _elme.regularizedRisk (_distRdR1, funcRdToR1, gvviX, _gvviY);
  320.             } catch (java.lang.Exception e) {
  321.                 e.printStackTrace();

  323.                 return null;
  324.             }

  326.             if (dblPenaltyLoss > dblSupremumPenaltyLoss) {
  327.                 iSupremumIndex = i;
  328.                 dblSupremumPenaltyLoss = dblPenaltyLoss;
  329.             }
  330.         }

  332.         try {
  333.             return new org.drip.learning.rxtor1.EmpiricalPenaltySupremum (iSupremumIndex,
  334.                 dblSupremumPenaltyLoss / gvviX.sampleSize());
  335.         } catch (java.lang.Exception e) {
  336.             e.printStackTrace();
  337.         }

  339.         return null;
  340.     }

  342.     /**
  343.      * Compute the Empirical Penalty Supremum for the specified R^1/R^d Input Space
  344.      * 
  345.      * @param gvviX The R^1/R^d Input Space
  346.      * 
  347.      * @return The Empirical Penalty Supremum for the specified R^1/R^d Input Space
  348.      */

  350.     public org.drip.learning.rxtor1.EmpiricalPenaltySupremum supremum (
  351.         final org.drip.spaces.instance.GeneralizedValidatedVector gvviX)
  352.     {
  353.         org.drip.learning.rxtor1.EmpiricalPenaltySupremum epsR1 = supremumR1 (gvviX);

  355.         return null == epsR1 ? supremumRd (gvviX) : epsR1;
  356.     }

  358.     /**
  359.      * Retrieve the Supremum R^1 To R^1 Function Instance for the specified Variate Sequence
  360.      * 
  361.      * @param adblX The Predictor Instance
  362.      * 
  363.      * @return The Supremum R^1 To R^1 Function Instance
  364.      */

  366.     public org.drip.function.definition.R1ToR1 supremumR1ToR1 (
  367.         final double[] adblX)
  368.     {
  369.         org.drip.learning.rxtor1.EmpiricalPenaltySupremum eps = null;

  371.         try {
  372.             eps = supremumR1 (new org.drip.spaces.instance.ValidatedR1
  373.                 (org.drip.spaces.tensor.R1ContinuousVector.Standard(), adblX));
  374.         } catch (java.lang.Exception e) {
  375.             e.printStackTrace();

  377.             return null;
  378.         }

  380.         return _aR1ToR1[eps.index()].function();
  381.     }

  383.     /**
  384.      * Retrieve the Supremum R^d To R^1 Function Instance for the specified Variate Sequence
  385.      * 
  386.      * @param aadblX The Predictor Instance
  387.      * 
  388.      * @return The Supremum R^d To R^1 Function Instance
  389.      */

  391.     public org.drip.function.definition.RdToR1 supremumRdToR1 (
  392.         final double[][] aadblX)
  393.     {
  394.         org.drip.learning.rxtor1.EmpiricalPenaltySupremum eps = null;

  396.         try {
  397.             eps = supremumRd (new org.drip.spaces.instance.ValidatedRd
  398.                 (org.drip.spaces.tensor.RdContinuousVector.Standard (aadblX.length), aadblX));
  399.         } catch (java.lang.Exception e) {
  400.             e.printStackTrace();

  402.             return null;
  403.         }

  405.         return _aRdToR1[eps.index()].function();
  406.     }

  408.     @Override public int dimension()
  409.     {
  410.         return -1;
  411.     }

  413.     @Override public double evaluate (
  414.         final double[] adblX)
  415.         throws java.lang.Exception
  416.     {
  417.         org.drip.learning.rxtor1.EmpiricalPenaltySupremum eps = supremumR1 (new
  418.             org.drip.spaces.instance.ValidatedR1 (org.drip.spaces.tensor.R1ContinuousVector.Standard(),
  419.                 adblX));

  421.         if (null == eps)
  422.             throw new java.lang.Exception ("EmpiricalPenaltySupremumEstimator::evaluate => Invalid Inputs");

  424.         return eps.value();
  425.     }

  427.     /**
  428.      * Retrieve the Worst-case Loss over the Multivariate Sequence
  429.      * 
  430.      * @param aadblX The Multivariate Array
  431.      * 
  432.      * @return The Worst-case Loss over the Multivariate Sequence
  433.      * 
  434.      * @throws java.lang.Exception Thrown if the Worst-Case Loss cannot be computed
  435.      */

  437.     public double evaluate (
  438.         final double[][] aadblX)
  439.         throws java.lang.Exception
  440.     {
  441.         if (null == aadblX)
  442.             throw new java.lang.Exception ("EmpiricalPenaltySupremumEstimator::evaluate => Invalid Inputs");

  444.         org.drip.learning.rxtor1.EmpiricalPenaltySupremum eps = supremumRd (new
  445.             org.drip.spaces.instance.ValidatedRd (org.drip.spaces.tensor.RdContinuousVector.Standard
  446.                 (aadblX.length), aadblX));

  448.         if (null == eps)
  449.             throw new java.lang.Exception ("EmpiricalPenaltySupremumEstimator::evaluate => Invalid Inputs");

  451.         return eps.value();
  452.     }

  454.     @Override public double targetVariateVarianceBound (
  455.         final int iTargetVariateIndex)
  456.         throws java.lang.Exception
  457.     {
  458.         return 1. / (_gvviY.sampleSize() * _gvviY.sampleSize());
  459.     }
  460. }
Created with JaCoCo 0.7.9.201702052155