portfolioSpec           package:fPortfolio           R Documentation

_S_p_e_c_i_f_i_c_a_t_i_o_n _o_f _P_o_r_t_f_o_l_i_o_s

_D_e_s_c_r_i_p_t_i_o_n:

     Specifies a portfolio from scratch.

_U_s_a_g_e:

     portfolioSpec(
         model = list(type = "MV", optimize = "minRisk",
             estimator = "covEstimator", tailRisk = list(), 
             params = list(alpha = 0.05, a = 1)), 
         portfolio = list(weights = NULL, targetReturn = NULL, 
             targetRisk = NULL, riskFreeRate = 0, nFrontierPoints = 50, 
             status = NA),
         optim = list(solver = "solveRquadprog", objective = NULL,
             options = list(meq = 2), control = list(), trace = FALSE),
         messages = list())

_A_r_g_u_m_e_n_t_s:

   model: a list, containing different arguments: type, estimator,
          params. See these arguments for further explanation. 

portfolio: a list, containing different arguments: weights,
          targetReturn, riskFreeRate, nFrontierPoints. See these
          arguments for further explanation. 

   optim: a list with four entries, a character string 'solver'
          denoting  the type of the solver to be used, a 'params' list
          to pass further arguments to the objective function to
          optimize, a 'control' list for all control settings of the
          solver, and a logical flag, 'trace' denoting if the
          optimization should be traced. 

messages: a list, for optional messages. 

_D_e_t_a_i_l_s:

     To optimize a portfolio of assets we first have to specify it. All
     settings which specify a portfolio of assets are respresented by a
     S4 class named 'fPFOLIOSPEC'.


         setClass("fPFOLIOSPEC", 
           representation(
             model = "list",
             portfolio = "list",
             optim = "list") )

     An object of class 'fPFOLIOSPEC' has three slots, named '@model',
     '@portfolio', and '@optim'. The first  slot '@model' holds the
     model information, the second slot '@portfolio' the portfolio
     information, and the last  slot '@optim' the information about the
     solver used for  optimization.

     The default settings are as follows:


         model = list(
             type = "MV",
             optimize = "minRisk",    
             estimator = "covEstimator",     
             tailRisk = list(),               
             params = list(alpha = 0.05, a = 2)),
         portfolio = list(
             weights = NULL, 
             targetReturn = NULL, 
             targetRisk = NULL,
             riskFreeRate = 0, 
             nFrontierPoints = 50,
             status = NA),
         optim = list(
             solver = "solveRquadprog",    
             objective = NULL,  
             parames = list(),
             control = list(meq = 2),   
             trace = FALSE)

     *Model Slot:*

     _Type of Model:_
      The list entry 'type' from the '@model' slot describes  the type
     of the desired portfolio. The current implementation  supports
     three types of portfolios. This may be  a Markowitz mean -
     variance portfolio named '"MV"',  a mean - lower partial moment
     portfolio named '"LPM"', or  a mean - CVaR condititional
     value-at-risk portfolio named '"CVaR"'.  One can use the function
     'getType' to retrieve the current setting and the function
     'setType' to modify this selection.

     _What to optimize?_
      The list entry 'optimize' from the '@model' slot describes  what
     should be optimized. Two choices are psssible. Either


             \code{"minRisk"}


     which minimizes the risk if the target returns is given, or 


             \code{"maxReturn"}


     which maximizes the return if the target risk is given. One can
     use the function 'getOptimize' to retrieve the current setting and
     the function 'setOptimize' to modify this selection.

     _How to estimate mean and covariance?_
      The list entry 'estimator' from the '@model' slot requests  for a
     string that denotes the function name of the covariance  estimator
     which should be used for the estimation of risk. 

     In Markowitz' mean-variance portfolio model, 'type="MV"', the 
     default function 


             \code{"covEstimator"} 

     is used which computes the standard column means  of the
     multivariate assets data series and the standard covariance 
     matrix. Alternative robust estimators include 


             \code{"covMcdEstimator"}
             \code{"covOGKEstimator"}
             \code{"mveEstimator"}
             \code{"nnveEstimator"}
             \code{"mcdEstimator"}

     In addition a shrinkage covariance estimator named


             \code{"shrinkEstimator"},

     and a bagged covariance estimator named


             \code{"baggedEstimator"} 

     are also available. Note, the experienced user can add his own
     function to estimate in any alternative way the mean and the
     covariance of the multivariate assets data series. In this case
     (s)he has to write a function, e.g. named


             \code{myEstimator=function(x,spec=NULL,...)}

     where 'x' is a multivariate time series, 'spec' optionally  the
     portfolio specification, if rquired, and '...' additional
     arguments passed to the users code. Note, 'myEstimator' must a
     return a named list, with at least the following two entries
     '\$mu' and '\$Sigma', which represent estimators for the mean and
     covariance, respectively. 

     In the case of the Mean - Lower-Partial-Moment portfolio, 
     'type="LPM"' we make use of the equivalence to Markowitz' 
     mean-variance portfolio with a modified covariance estimator, i.e. 


             \code{"lpmEstimator"},

     Note, in this case the setting of 'type="LPM"'  changes the
     covariance estimator function name  from any selection previously
     made to the function automatically to '"lpmEstimator"' which
     returns the LPM mean and covariance  estimates.   

     One can use the function 'getEstimator' to retrieve the current
     setting and the function 'setEstimator' to modify this selection.

     _Tail Risk List:_
      The list entry 'tailRisk' from the '@model' slot is an empty 
     list. It can be used to add tail risk budget constrains to the 
     optimization. In this case a square matrix of the size of the 
     number of assets is expected as list entry, which contains
     bivariate  tail risk measures, i.e. the tail dependence
     coefficients estaimated  via a copulae approach.    Use the
     function 'setType' to modify this selection.

     The list entry 'parameters' from the '@model' slot is a  list with
     additional parameters used in different situations. It can  be
     ebhanced by the user if needed.  By default it contains the
     exponent 'a=2', the parameter needed  for "LPM" portfolio
     optimization, and it contains the 'targetAlpha=0.05', the
     confidence level for "CVaR" portfolio optimization. Use the
     function 'setParams' to modify this selection.

     *Portfolio Slot:*

     The values 'weights', 'targetReturn', and 'targetRisk' from the
     'portfolio' slot have to be considered in common. By default all
     three are set to 'NULL'. If this is the case, then  it is assumed
     that an equal weight portfolio should be calculated. If only one
     of the three values is different from 'NULL' then the following
     procedure will be startet.  If the weights are specified then it
     is assumed that a feasible  portfolio should be considered. If the
     target return is fixed then it is assumed that the efficient 
     portfolio with the minimal risk will be considered.  And finally
     if the risk is fixed, then the return should be maximized. Use the
     functions 'setWeights', 'setTargetReturn', and 'setTargetRisk' to
     modify this selection.Note, the change in of the three functions
     will influence the settings of the other two.

     The 'riskFreeRate=0' is also stored in the 'portfolio' slot. Its
     value defaults to zero. It can be changed by the user. Use the
     function 'setRiskFreeRate' to modify this selection.

     The number of frontier points reqauired by the calculation of the
     'portfolioFrontier' is obtained from the value of
     'nFrontierPoints=50' hold in the 'portfolio' slot. Its value
     defaults to 50. It can be changed by the user. Use the function
     'setNFrontierPoints' to modify this selection.

     The final 'status' of portfolio optimization is returned  and
     stored in the 'portfolio' slot. Before optimization the value is
     unset to 'NA', after optimization a value of  'status=0' means a
     successful termination. For other values we recommend to inspect
     the help page of the selected solver, the name of the solver can
     be returned by the function 'getSolver'. Use the function
     'setSolver' to reset the value to 'NA' if it should be required.

     *Optim Slot:*

     The name of the default solver used for optimization can be
     retrieved calling the function 'getSolver'. The default value for
     the value 'solver' in the specification is set to 'NULL'  which
     means that the best solver availalbe will be autoselected  and
     used. Before optimization the user can change the setting to
     another solver. Be aware, that a possible personal change will  be
     overwritten by the function 'setType', so call  'setSolver' after
     setting the type of the portfolio.

     The logical flag 'trace' in the slot 'optim' allows to trace
     optionally the portfolio optimization process. By  default this
     will not be the case since the default value is  'trace=FALSE'.
     Use the fanction 'setTrace' to modify the selection.

     *Retrieving and Modifying Specification Settings:*

     Information about the current portfolio specification can be
     retrieved  by '"get"' functions. These include:

       'getType'             Extracts portfolio type from specification,
       'getOptimize'         Extracts what to optimize from specification,
       'getEstimator'        Extracts type of covariance estimator,
       'getTailRisk'         Extracts list of tail dependency risk matrixes,
       'getParams'           Extracts parameters from specification,
       'getWeights'          Extracts weights from a portfolio object,
       'getTargetReturn'     Extracts target return from specification,
       'getTargetRisk'       Extracts target riks from specification,
       'getAlpha'            Extracts target VaR-alpha specification,
       'getRiskFreeRate'     Extracts risk free rate from specification,
       'getNFrontierPoints'  Extracts number of frontier points,
       'getStatus'           Extracts the status of optimization,
       'getSolver'           Extracts solver from specification,
       'getTrace'            Extracts solver's trace flag.

     For details we refer to 'link{getSpec}'.

     To modify the setting from a portfolio specification use the 
     '"set"' functions:

       'setType'             Sets type of portfolio optimization,
       'setOptimize'         Sets what to optimize, min risk or max return,
       'setEstimator'        Sets names of mean and covariance estimators,
       'setParams'           Sets optional model parameters,
       'setWeights'          Sets weights vector,
       'setTargetReturn'     Sets target return value,
       'setTargetRisk'       Sets target risk value,
       'setTargetAlpha'      Sets CVaR target alpha value,
       'setRiskFreeRate'     Sets risk-free rate value,
       'setNFrontierPoints'  Sets number of frontier points,
       'setStatus'           Sets status value,
       'setSolver'           Sets the type of solver to be used,
       'setTrace'            Sets the logical trace flag.

     For details we refer to 'link{setSpec}'.

     *Printing Specification Settings:*

     There is a generic print function to print information from
     specification. What is printed depends on the values of the
     settings. For example 'print(portfolioSpec())' returns the type of
     portfolio, the name of the covariance estimator, the portfolios
     risk free rate, and the desired solver.

_V_a_l_u_e:

     'portfolioSpec'

      returns an S4 object of class '"fPFOLIOSPEC"'.

_R_e_f_e_r_e_n_c_e_s:

     Wuertz, D., Chalabi, Y., Chen W., Ellis A. (2009); _Portfolio
     Optimization with R/Rmetrics_,  Rmetrics eBook, Rmetrics
     Association and Finance Online, Zurich.

_E_x_a_m_p_l_e_s:

     ## portfolioSpec -
        spec = portfolioSpec()
        
     ## getRiskFreeRate -
        getRiskFreeRate(spec) 
        spec
        
     ## setRiskFreeRate -
        setRiskFreeRate(spec) <- 2.5

