AttributeJointFactor.java

  1. package org.drip.portfolioconstruction.risk;

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

  79. /**
  80.  * <i>AttributeJointFactor</i> contains the Factor Based Loadings that determines the Joint Attributes
  81.  * between the Pair of Assets.
  82.  *
  83.  *  <br><br>
  84.  *  <ul>
  85.  *      <li><b>Module </b> = <a href = "https://github.com/lakshmiDRIP/DROP/tree/master/PortfolioCore.md">Portfolio Core Module</a></li>
  86.  *      <li><b>Library</b> = <a href = "https://github.com/lakshmiDRIP/DROP/tree/master/AssetAllocationAnalyticsLibrary.md">Asset Allocation Analytics</a></li>
  87.  *      <li><b>Project</b> = <a href = "https://github.com/lakshmiDRIP/DROP/tree/master/src/main/java/org/drip/portfolioconstruction/README.md">Portfolio Construction under Allocation Constraints</a></li>
  88.  *      <li><b>Package</b> = <a href = "https://github.com/lakshmiDRIP/DROP/tree/master/src/main/java/org/drip/portfolioconstruction/risk/README.md">Portfolio Construction Risk/Covariance Component</a></li>
  89.  *  </ul>
  90.  * <br><br>
  91.  *
  92.  * @author Lakshmi Krishnamurthy
  93.  */

  95. public class AttributeJointFactor
  96.     extends org.drip.portfolioconstruction.core.Block
  97. {
  98.     private java.util.Map<java.lang.String, java.lang.Double> _assetFactorLoadingMap =
  99.         new org.drip.analytics.support.CaseInsensitiveHashMap<java.lang.Double>();

  101.     private java.util.Map<java.lang.String, java.lang.Double> _factorAssetLoadingMap =
  102.         new org.drip.analytics.support.CaseInsensitiveHashMap<java.lang.Double>();

  104.     private java.util.Map<java.lang.String, java.lang.Double> _factorFactorAttributeMap =
  105.         new org.drip.analytics.support.CaseInsensitiveHashMap<java.lang.Double>();

  107.     private java.util.Map<java.lang.String, java.lang.Double> _mapAssetSpecificAttribute =
  108.         new org.drip.analytics.support.CaseInsensitiveHashMap<java.lang.Double>();

  110.     /**
  111.      * Generate a Standard Instance of AttributeJointFactor
  112.      * 
  113.      * @param name AttributeJointFactor Instance Name
  114.      * @param id AttributeJointFactor Instance ID
  115.      * @param description AttributeJointFactor Description
  116.      * @param assetIDArray Array of Asset IDs
  117.      * @param factorIDArray Array of FactorIDs
  118.      * @param assetFactorLoadingGrid Matrix of Asset-Factor Loadings
  119.      * @param crossFactorAttributeGrid Matrix of Factor-Factor Attributes
  120.      * @param assetSpecificAttributeArray Array of Specific Attributes
  121.      * 
  122.      * @return The Standard Instance of AttributeJointFactor
  123.      */

  125.     public static final AttributeJointFactor Standard (
  126.         final java.lang.String name,
  127.         final java.lang.String id,
  128.         final java.lang.String description,
  129.         final java.lang.String[] assetIDArray,
  130.         final java.lang.String[] factorIDArray,
  131.         final double[][] assetFactorLoadingGrid,
  132.         final double[][] crossFactorAttributeGrid,
  133.         final double[] assetSpecificAttributeArray)
  134.     {
  135.         if (null == assetIDArray ||
  136.             null == factorIDArray ||
  137.             null == assetFactorLoadingGrid ||
  138.             null == crossFactorAttributeGrid ||
  139.             null == assetSpecificAttributeArray)
  140.         {
  141.             return null;
  142.         }

  144.         int assetCount = assetIDArray.length;
  145.         int factorCount = factorIDArray.length;
  146.         AttributeJointFactor attributeJointFactor = null;

  148.         if (0 == assetCount ||
  149.             0 == factorCount ||
  150.             assetCount != assetFactorLoadingGrid.length ||
  151.             factorCount != crossFactorAttributeGrid.length ||
  152.             assetCount != assetSpecificAttributeArray.length)
  153.         {
  154.             return null;
  155.         }

  157.         try
  158.         {
  159.             attributeJointFactor = new AttributeJointFactor (
  160.                 name,
  161.                 id,
  162.                 description
  163.             );
  164.         }
  165.         catch (java.lang.Exception e)
  166.         {
  167.             e.printStackTrace();

  169.             return null;
  170.         }

  172.         for (int assetIndex = 0;
  173.             assetIndex < assetCount;
  174.             ++assetIndex)
  175.         {
  176.             for (int factorIndex = 0;
  177.                 factorIndex < factorCount;
  178.                 ++factorIndex)
  179.             {
  180.                 if (!attributeJointFactor.addAssetFactorLoading (
  181.                     assetIDArray[assetIndex],
  182.                     factorIDArray[factorIndex],
  183.                     assetFactorLoadingGrid[assetIndex][factorIndex]
  184.                 ))
  185.                 {
  186.                     return null;
  187.                 }
  188.             }

  190.             if (!attributeJointFactor.addSpecificAttribute (
  191.                 assetIDArray[assetIndex],
  192.                 assetSpecificAttributeArray[assetIndex]
  193.             ))
  194.             {
  195.                 return null;
  196.             }
  197.         }

  199.         for (int factorIndex1 = 0;
  200.             factorIndex1 < factorCount;
  201.             ++factorIndex1)
  202.         {
  203.             for (int factorIndex2 = 0;
  204.                 factorIndex2 < factorCount;
  205.                 ++factorIndex2)
  206.             {
  207.                 if (!attributeJointFactor.addFactorAttribute (
  208.                     factorIDArray[factorIndex1],
  209.                     factorIDArray[factorIndex2],
  210.                     crossFactorAttributeGrid[factorIndex1][factorIndex2]
  211.                 ))
  212.                 {
  213.                     return null;
  214.                 }
  215.             }
  216.         }

  218.         return attributeJointFactor;
  219.     }

  221.     /**
  222.      * AttributeJointFactor Constructor
  223.      * 
  224.      * @param name The Name
  225.      * @param id The ID
  226.      * @param description The Description
  227.      * 
  228.      * @throws java.lang.Exception Thrown if the Inputs are Invalid
  229.      */

  231.     public AttributeJointFactor (
  232.         final java.lang.String name,
  233.         final java.lang.String id,
  234.         final java.lang.String description)
  235.         throws java.lang.Exception
  236.     {
  237.         super (name, id, description);
  238.     }

  240.     /**
  241.      * Retrieve the Joint Asset-Factor Loading Map
  242.      * 
  243.      * @return The Joint Asset-Factor Loading Map
  244.      */

  246.     public java.util.Map<java.lang.String, java.lang.Double> assetFactorLoading()
  247.     {
  248.         return _assetFactorLoadingMap;
  249.     }

  251.     /**
  252.      * Retrieve the Joint Factor-Asset Loading Map
  253.      * 
  254.      * @return The Joint Factor-Asset Loading Map
  255.      */

  257.     public java.util.Map<java.lang.String, java.lang.Double> factorAssetLoading()
  258.     {
  259.         return _factorAssetLoadingMap;
  260.     }

  262.     /**
  263.      * Retrieve the Factor-to-Factor Attribute Map
  264.      * 
  265.      * @return The Factor-to-Joint Attribute Map
  266.      */

  268.     public java.util.Map<java.lang.String, java.lang.Double> factorJointAttribute()
  269.     {
  270.         return _factorFactorAttributeMap;
  271.     }

  273.     /**
  274.      * Retrieve the Asset Specific Attribute
  275.      * 
  276.      * @return The Asset Specific Attribute
  277.      */

  279.     public java.util.Map<java.lang.String, java.lang.Double> specificRisk()
  280.     {
  281.         return _mapAssetSpecificAttribute;
  282.     }

  284.     /**
  285.      * Add the Asset's Factor Loading Coefficient
  286.      * 
  287.      * @param assetID The Asset ID
  288.      * @param factorID The Factor ID
  289.      * @param factorLoading The Factor Loading Coefficient
  290.      * 
  291.      * @return TRUE - The Asset's Factor Loading Coefficient successfully added
  292.      */

  294.     public boolean addAssetFactorLoading (
  295.         final java.lang.String assetID,
  296.         final java.lang.String factorID,
  297.         final double factorLoading)
  298.     {
  299.         if (null == assetID || assetID.isEmpty() ||
  300.             null == factorID || factorID.isEmpty() ||
  301.             !org.drip.numerical.common.NumberUtil.IsValid (
  302.                 factorLoading
  303.             )
  304.         )
  305.         {
  306.             return false;
  307.         }

  309.         _assetFactorLoadingMap.put (
  310.             assetID + "::" + factorID,
  311.             factorLoading
  312.         );

  314.         _factorAssetLoadingMap.put (
  315.             factorID + "::" + assetID,
  316.             factorLoading
  317.         );

  319.         return true;
  320.     }

  322.     /**
  323.      * Add the Cross Factor Attribute
  324.      * 
  325.      * @param factorID1 The Factor #1 ID
  326.      * @param factorID2 The Factor #2 ID
  327.      * @param crossFactorAttribute The Cross Factor Attribute
  328.      * 
  329.      * @return TRUE - The Cross Factor Attribute successfully added
  330.      */

  332.     public boolean addFactorAttribute (
  333.         final java.lang.String factorID1,
  334.         final java.lang.String factorID2,
  335.         final double crossFactorAttribute)
  336.     {
  337.         if (null == factorID1 || factorID1.isEmpty() ||
  338.             null == factorID2 || factorID2.isEmpty() ||
  339.             !org.drip.numerical.common.NumberUtil.IsValid (
  340.                 crossFactorAttribute
  341.             )
  342.         )
  343.         {
  344.             return false;
  345.         }

  347.         _factorFactorAttributeMap.put (
  348.             factorID1 + "::" + factorID2,
  349.             crossFactorAttribute
  350.         );

  352.         _factorFactorAttributeMap.put (
  353.             factorID2 + "::" + factorID1,
  354.             crossFactorAttribute
  355.         );

  357.         return true;
  358.     }

  360.     /**
  361.      * Add the Asset's Specific Attribute
  362.      * 
  363.      * @param assetID The Asset ID
  364.      * @param specificAttribute The Asset's Specific Attribute
  365.      * 
  366.      * @return TRUE - The Asset's Specific Risk successfully added
  367.      */

  369.     public boolean addSpecificAttribute (
  370.         final java.lang.String assetID,
  371.         final double specificAttribute)
  372.     {
  373.         if (null == assetID || assetID.isEmpty() ||
  374.             !org.drip.numerical.common.NumberUtil.IsValid (
  375.                 specificAttribute
  376.             )
  377.         )
  378.         {
  379.             return false;
  380.         }

  382.         _mapAssetSpecificAttribute.put (
  383.             assetID,
  384.             specificAttribute
  385.         );

  387.         return true;
  388.     }

  390.     /**
  391.      * Check if the Asset is represented
  392.      * 
  393.      * @param assetID The Asset ID
  394.      * 
  395.      * @return TRUE - The Asset is represented
  396.      */

  398.     public boolean containsAsset (
  399.         final java.lang.String assetID)
  400.     {
  401.         return null != assetID && !assetID.isEmpty() &&
  402.             _assetFactorLoadingMap.containsKey (
  403.                 assetID
  404.             ) && _mapAssetSpecificAttribute.containsKey (
  405.                 assetID
  406.             );
  407.     }

  409.     /**
  410.      * Check if the Factor is available
  411.      * 
  412.      * @param factorID The Factor ID
  413.      * 
  414.      * @return TRUE - The Factor is available
  415.      */

  417.     public boolean containsFactor (
  418.         final java.lang.String factorID)
  419.     {
  420.         return null != factorID && !factorID.isEmpty() &&
  421.             _factorAssetLoadingMap.containsKey (
  422.                 factorID
  423.             ) && _factorFactorAttributeMap.containsKey (
  424.                 factorID
  425.             );
  426.     }

  428.     /**
  429.      * Retrieve the Factor Loading for the specified Asset
  430.      * 
  431.      * @param assetID The Asset ID
  432.      * 
  433.      * @return The Factor Loading for the specified Asset
  434.      */

  436.     public java.util.Map<java.lang.String, java.lang.Double> assetFactorLoading (
  437.         final java.lang.String assetID)
  438.     {
  439.         if (!containsAsset (
  440.             assetID
  441.         ))
  442.         {
  443.             return null;
  444.         }

  446.         java.util.Map<java.lang.String, java.lang.Double> assetFactorLoadingMap =
  447.             new org.drip.analytics.support.CaseInsensitiveHashMap<java.lang.Double>();

  449.         for (java.util.Map.Entry<java.lang.String, java.lang.Double> assetFactorLoadingEntry :
  450.             _assetFactorLoadingMap.entrySet())
  451.         {
  452.             if (assetFactorLoadingEntry.getKey().startsWith (
  453.                 assetID
  454.             ))
  455.             {
  456.                 assetFactorLoadingMap.put (
  457.                     assetID,
  458.                     assetFactorLoadingEntry.getValue()
  459.                 );
  460.             }
  461.         }

  463.         return assetFactorLoadingMap;
  464.     }

  466.     /**
  467.      * Retrieve the Loadings for the specified Factor
  468.      * 
  469.      * @param factorID The Factor ID
  470.      * 
  471.      * @return The Loadings for the specified Factor
  472.      */

  474.     public java.util.Map<java.lang.String, java.lang.Double> factorAssetLoading (
  475.         final java.lang.String factorID)
  476.     {
  477.         if (!containsFactor (
  478.             factorID
  479.         ))
  480.         {
  481.             return null;
  482.         }

  484.         java.util.Map<java.lang.String, java.lang.Double> factorAssetLoadingMap = new
  485.             org.drip.analytics.support.CaseInsensitiveHashMap<java.lang.Double>();

  487.         for (java.util.Map.Entry<java.lang.String, java.lang.Double> factorAssetLoadingEntry :
  488.             _factorAssetLoadingMap.entrySet())
  489.         {
  490.             if (factorAssetLoadingEntry.getKey().startsWith (
  491.                 factorID
  492.             ))
  493.             {
  494.                 factorAssetLoadingMap.put (
  495.                     factorID,
  496.                     factorAssetLoadingEntry.getValue()
  497.                 );
  498.             }
  499.         }

  501.         return factorAssetLoadingMap;
  502.     }

  504.     /**
  505.      * Retrieve the Cross Factor Attribute Entry
  506.      * 
  507.      * @param factorID1 The Factor ID #1
  508.      * @param factorID2 The Factor ID #2
  509.      * 
  510.      * @return The Cross Factor Attribute Entry
  511.      * 
  512.      * @throws java.lang.Exception Thrown if the Inputs are Invalid
  513.      */

  515.     public double crossFactorAttribute (
  516.         final java.lang.String factorID1,
  517.         final java.lang.String factorID2)
  518.         throws java.lang.Exception
  519.     {
  520.         if (!containsFactor (
  521.                 factorID1
  522.             ) || !containsFactor (
  523.                 factorID2
  524.             )
  525.         )
  526.         {
  527.             throw new java.lang.Exception (
  528.                 "AttributeJointFactor::crossFactorAttribute => Invalid Inputs"
  529.             );
  530.         }

  532.         return _factorFactorAttributeMap.get (
  533.             factorID1 + "::" + factorID2
  534.         );
  535.     }

  537.     /**
  538.      * Retrieve the Asset Specific Attribute
  539.      * 
  540.      * @param assetID The Asset ID
  541.      * 
  542.      * @return The Asset Specific Attribute
  543.      * 
  544.      * @throws java.lang.Exception Thrown if the Inputs are Invalid
  545.      */

  547.     public double assetSpecificAttribute (
  548.         final java.lang.String assetID)
  549.         throws java.lang.Exception
  550.     {
  551.         if (!containsFactor (
  552.             assetID
  553.         ))
  554.         {
  555.             throw new java.lang.Exception (
  556.                 "AttributeJointFactor::assetSpecificAttribute => Invalid Inputs"
  557.             );
  558.         }

  560.         return _mapAssetSpecificAttribute.get (
  561.             assetID
  562.         );
  563.     }

  565.     /**
  566.      * Compute the Cross Asset Attribute
  567.      * 
  568.      * @param assetID1 Asset ID #1
  569.      * @param assetID2 Asset ID #2
  570.      * 
  571.      * @return The Cross Asset Attribute
  572.      * 
  573.      * @throws java.lang.Exception Thrown if the Inputs are Invalid
  574.      */

  576.     public double crossAssetAttribute (
  577.         final java.lang.String assetID1,
  578.         final java.lang.String assetID2)
  579.         throws java.lang.Exception
  580.     {
  581.         java.util.Map<java.lang.String, java.lang.Double> asset1FactorLoadingMap = assetFactorLoading (
  582.             assetID1
  583.         );

  585.         java.util.Map<java.lang.String, java.lang.Double> asset2FactorLoadingMap = assetFactorLoading (
  586.             assetID2
  587.         );

  589.         if (null == asset1FactorLoadingMap || null == asset2FactorLoadingMap)
  590.         {
  591.             throw new java.lang.Exception (
  592.                 "AttributeJointFactor::crossAssetAttribute => Invalid Factor Loadings"
  593.             );
  594.         }

  596.         double crossAssetAttribute = 0.;

  598.         for (java.util.Map.Entry<java.lang.String, java.lang.Double> asset1FactorLoadingEntry :
  599.             asset1FactorLoadingMap.entrySet())
  600.         {
  601.             java.lang.String factorID = asset1FactorLoadingEntry.getKey();

  603.             if (!asset2FactorLoadingMap.containsKey (
  604.                     factorID
  605.                 ) || !_factorFactorAttributeMap.containsKey (
  606.                     factorID
  607.                 )
  608.             )
  609.             {
  610.                 throw new java.lang.Exception (
  611.                     "AttributeJointFactor::crossAssetAttribute => Loading not available for " + assetID2 +
  612.                         " for factor " + factorID
  613.                 );
  614.             }

  616.             crossAssetAttribute += asset1FactorLoadingMap.get (
  617.                 factorID
  618.             ) * asset2FactorLoadingMap.get (
  619.                 factorID
  620.             ) * crossFactorAttribute (
  621.                 factorID,
  622.                 factorID
  623.             );
  624.         }

  626.         return crossAssetAttribute;
  627.     }
  628. }
Created with JaCoCo 0.7.9.201702052155