MultivariateDistribution      package:fMultivar      R Documentation

_M_u_l_t_i_v_a_r_i_a_t_e _S_k_e_w _N_o_r_m_a_l _a_n_d _S_t_u_d_e_n_t-_t _D_i_s_t_r_i_b_u_t_i_o_n_s

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

     A collection and description of functions to compute  multivariate
     densities and probabilities from skew  normal and skew Student-t
     distribution functions.  Furthermore, multivariate random daviates
     can be  generated, and for multivariate data, the parameters  of
     the underlying distribution can be estimated  by the maximum
     log-likelihood estimation. 

     The functions are:

       'dmvsnorm'  Multivariate Skew Normal Density,
       'pmvsnorm'  Multivariate Skew Normal Probability,
       'rmvsnorm'  Random Deviates from MV Skew Normal Distribution,
       'dmvst'     Multivariate Skew Student Density,
       'pmvst'     Multivariate Skew Student Probability,
       'rmvst'     Random Deviates from MV Skew Student Distribution,
       'mvFit'     Fits a MV Skew Normal or Student-t Distribution,
       'print'     S3 print method for an object of class 'fMV',
       'plot'      S3 Plot method for an object of class 'fMV',
       'summary'   S3 summary method for an object of class 'fMV'.

     These functions are useful for portfolio selection and
     optimization if one likes to model the data by multivariate
     normal, skew normal, or skew Student-t distribution functions.

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

     dmvsnorm(x, dim = 2, mu = rep(0, dim), Omega = diag(dim), alpha = rep(0, dim))
     pmvsnorm(q, dim = 2, mu = rep(0, dim), Omega = diag(dim), alpha = rep(0, dim))
     rmvsnorm(n, dim = 2, mu = rep(0, dim), Omega = diag(dim), alpha = rep(0, dim))

     dmvst(x, dim = 2, mu = rep(0, dim), Omega = diag(dim), alpha = rep(0, dim), df = 4)
     pmvst(q, dim = 2, mu = rep(0, dim), Omega = diag(dim), alpha = rep(0, dim), df = 4)
     rmvst(n, dim = 2, mu = rep(0, dim), Omega = diag(dim), alpha = rep(0, dim), df = 4)

     mvFit(x, method = c("snorm", "st"), fixed.df = NA, title = NULL, 
         description = NULL, trace = FALSE, ...) 

     ## S4 method for signature 'fMV':
     show(object)    
         
     ## S3 method for class 'fMV':
     plot(x, which = "ask", ...)
     ## S3 method for class 'fMV':
     summary(object, which = "ask", doplot = TRUE, ...)

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

description: [mvFit] - 
           a character string, assigning a brief description to an 
          '"fMV"' object. 

  doplot: a logical value, by default TRUE. Should a plot be generated
          and displayed? 

     dim: [*mvsnorm][*mvst] - 
           the colum dimension of the matrix 'x'. If 'x' is  specified
          as a vector, 'dim=1' must be set to one. 

fixed.df: either 'NA', the default, or a numeric value assigning the
          number of degrees of freedom to the model. In the case that 
          'fixed.df=NA' the value of 'df' will be included in the
          optimization process, otherwise not. 

  method: [mvFit] - 
           a string value specifying the method applied in the
          optimizing  process. This can be either 'method="snorm"' or 
          'method="st"', in the first case the parameters for a skew
          normal distribution will be fitted and in the second case the
          parameters for a skew Student-t distribution.  

mu, Omega, alpha, df: [*mvsnorm][*mvst] - 
           the model parameters: 
           'mu' a vector of mean values, one for each column, 
           'Omega' the covariance matrix, 
           'alpha' the skewness vector, and 
           'df' the number of degrees of freedom which is a measure for
          the fatness of the tails (excess kurtosis). 
           For a symmetric distribution 'alpha' is a vector of zeros.
          For the normal distributions 'df' is not used and set to 
          infinity, 'Inf'. Note that all columns assume the same value 
          for 'df'. 

       n: [rmvsnorm][rmvst] - 
           number of data records to be simulated, an integer value. 

  object: [summary] - 
           an object of class 'fMV'. 

   title: [mvFit] - 
           a character string, assigning a title to an '"fMV"' object. 

   trace: a logical, if set to 'TRUE' the optimization process will be
          traced, otherwise not. The default setting is 'FALSE'. 

   which: which of the five plots should be displayed? 'which' can  be
          either a character string, '"all"' (displays all plots)  or
          '"ask"' (interactively asks which one to display), or a 
          vector of 5 logical values, for those elements which are set 
          'TRUE' the correponding plot will be displayed. 

    x, q: [*mvsnorm][*mvst][mvFit] - 
           a numeric matrix of quantiles (returns) or any other
          rectangular  object like a data.frame or a multivariate time
          series objects  which can be transformed by the function
          'as.matrix' to an  object of class 'matrix'. If 'x' is a
          vector, it will  be transformed into a matrix object with one
          column. 
           [plot][print] - 
           An object of class 'fMV'. 

     ...: optional arguments to be passed to the optimization or
          plotting functions. 

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

     These are "easy-to-use" functions which allow quickly to simulate 
     multivariate data sets and to fit their parameters assuming a 
     multivariate skew normal or skew Student-t distribution. The
     functions make use of the contributed R packages 'sn' and
     'mtvnorm'.

     For an extended functionality in modelling multivariate skew
     normal and Student-t distributions we recommend to download and
     use the  functions from the original package 'sn' which requires
     also the package 'mtvnorm'.

     The algorithm for the computation of the normal and Student-t 
     distribution functions is described by Genz (1992) and (1993), 
     and its implementation by Hothorn, Bretz, and Genz (2001).

     The parameter estimation is done by the maximum log-likelihood
     estimation. The algorithm and the implemantation was done by
     Azzalini (1985-2003). 

     The multivariate skew-normal distribution is discussed in detail
     by Azzalini and Dalla Valle (1996); the '(Omega,alpha)' 
     parametrization adopted here is the one of Azzalini and  Capitanio
     (1999). 

     The family of multivariate skew-t distributions is an extension of
      the multivariate Student's t family, via the introduction of a 
     shape parameter which regulates skewness; for a zero shape
     parameter the skew Student-t distribution reduces to the usual t
     distribution.  When 'df = Inf' the distribution reduces to the
     multivariate  skew-normal one.

     The plot facilities have been completely reimplemented. The S3
     plot method allows for selective batch and interactive plots. The 
     argument 'which' takes care for the desired operation.

     The contributed R package 'mvtnorm' is required, the contributed 
     R package 'sn' is builtin, since it is not available on the Debian
     Software Server.

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

     '[dp]mvsnorm' 
      '[dp]mvst' 
      return a vector of density and probability values computed from
     the matrix 'x'. 

     'mvFit'  
      returns a S4 object class of class '"fASSETS"', with the
     following  slots:

   @call: the matched function call. 

   @data: the input data in form of a data.frame. 

@description: allows for a brief project description. 

    @fit: the results as a list returned from the underlying fitting
          function.  

 @method: the selected method to fit the distribution, either 
          '"snorm"', or '"st"'. 

  @model: the model parameters describing the fitted parameters in 
          form of a list, 'model=list(mu, Omega, alpha, df'. 

  @title: a title string.

 @fit$dp: a list containing the direct parameters beta, Omega, alpha. 
          Here, beta is a matrix of regression coefficients with 
          'dim(beta)=c(nrow(X), ncol(y))', 'Omega' is a  covariance
          matrix of order 'dim', 'alpha' is  a vector of shape
          parameters of length 'dim'.   

 @fit$se: a list containing the components beta, alpha, info. Here, 
          beta and alpha are the standard errors for the corresponding 
          point estimates; info is the observed information matrix  for
          the working parameter, as explained below. 

@fit$optim: the list returned by the optimizer 'optim'; see the 
          documentation of this function for explanation of its 
          components.   


     'print'  
      is the S3 print method for objects of class '"fMV"' returned from
     the function 'mvFit'. If shows a summary report of the parameter
     fit.

     'plot'  
      is the S3 plot method for objects of class '"fMV"' returned from
     the function 'mvFit'. Five plots are produced.  The first plot
     produces a scatterplot and in one dimension an  histogram plot
     with the fitted distribution superimposed.  The second and third
     plot represent a QQ-plots of Mahalanobis  distances. The first of
     these refers to the fitting  of a multivariate normal
     distribution, a standard statistical  procedure; the second gives
     the corresponding QQ-plot of  suitable Mahalanobis distances for
     the multivariate skew-normal  fit. The fourth and fivth plots are
     similar to the previous ones,  except that PP-plots are produced.
     The plots can be displayed in several ways, depending an the
     argument 'which', for  details we refer to the arguments list
     above.

     'summary' 
      is the S3 summary method for objects of class '"fMV"' returned
     from the function 'mvFit'. The summary method prints and plots in
     one step the results as done by the 'print' and 'plot'  methods.

_A_u_t_h_o_r(_s):

     Torsten Hothorn for R's 'mvtnorm' package, 
      Alan Ganz and Frank Bretz for the underlying Fortran Code, 
      Adelchi Azzalini for R's 'sn' package, 
      Diethelm Wuertz for the Rmetrics port.

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

     Azzalini A. (1985); _A Class of Distributions Which Includes the
     Normal Ones_, Scandinavian Journal of Statistics 12, 171-178. 

     Azzalini A. (1986); _Further Results on a Class of Distributions
     Which Includes  the Normal Ones_, Statistica 46, 199-208. 

     Azzalini A., Dalla Valle A. (1996); _The Multivariate Skew-normal
     Distribution_, Biometrika 83, 715-726. 

     Azzalini A., Capitanio A. (1999); _Statistical Applications of the
     Multivariate Skew-normal  Distribution_, Journal Roy. Statist.
     Soc. B61, 579-602. 

     Azzalini A., Capitanio A. (2003); _Distributions Generated by
     Perturbation of Symmetry with  Emphasis on a Multivariate Skew-t
     Distribution_, Journal Roy. Statist. Soc. B65, 367-389. 

     Genz A., Bretz F. (1999); _Numerical Computation of Multivariate
     t-Probabilities with Application to Power Calculation of Multiple
     Contrasts_,  Journal of Statistical Computation and Simulation 63,
     361-378.

     Genz A. (1992); _Numerical Computation of Multivariate Normal
     Probabilities_, Journal of Computational and Graphical Statistics
     1, 141-149.

     Genz A. (1993);  _Comparison of Methods for the Computation of
     Multivariate Normal Probabilities_, Computing Science and
     Statistics 25, 400-405.

     Hothorn T., Bretz F., Genz A. (2001); _On Multivariate t and Gauss
     Probabilities in R_, R News 1/2, 27-29.

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

     ## rmvst - 
        par(mfcol = c(3, 1), cex = 0.7)
        r1 = rmvst(200, dim = 1)
        ts.plot(as.ts(r1), xlab = "r", main = "Student-t 1d")
        r2 = rmvst(200, dim = 2, Omega = matrix(c(1, 0.5, 0.5, 1), 2))
        ts.plot(as.ts(r2), xlab = "r", col = 2:3, main = "Student-t 2d")
        r3 = rmvst(200, dim = 3, mu = c(-1, 0, 1), alpha = c(1, -1, 1), df = 5)
        ts.plot(as.ts(r3), xlab = "r", col = 2:4, main = "Skew Student-t 3d")    
        
     ## mvFit - 
        # Generate Grid Points:
        n = 51
        x = seq(-3, 3, length = n)
        xoy = cbind(rep(x, n), as.vector(matrix(x, n, n, byrow = TRUE)))
        X = matrix(xoy, n * n, 2, byrow = FALSE)
        head(X)
        # The Bivariate Normal Case:
        Z = matrix(dmvsnorm(X, dim = 2), length(x))
        par (mfrow = c(2, 2), cex = 0.7)
        persp(x, x, Z, theta = -40, phi = 30, col = "steelblue") 
        title(main = "Bivariate Normal Plot")
        image(x, x, Z)
        title(main = "Bivariate Normal Contours")
        contour(x, x, Z, add = TRUE)
        # The Bivariate Skew-Student-t Case:
        mu = c(-0.1, 0.1)
        Omega = matrix(c(1, 0.5, 0.5, 1), 2)
        alpha = c(-1, 1)
        Z = matrix(dmvst(X, 2, mu, Omega, alpha, df = 3), length(x))
        persp(x, x, Z, theta = -40, phi = 30, col = "steelblue") 
        title(main = "Bivariate Student-t Plot")
        image(x, x, Z)
        contour(x, x, Z, add = TRUE)
        title(main = "Bivariate Student-t Contours")

