Return to hgm.cwishart.Rd CVS log

Up to [local] / OpenXM / src / R / r-packages / hgm / man

Annotation of OpenXM/src/R/r-packages/hgm/man/hgm.cwishart.Rd, Revision 1.10

1.10    ! takayama    1: % $OpenXM: OpenXM/src/R/r-packages/hgm/man/hgm.cwishart.Rd,v 1.9 2015/03/26 11:54:13 takayama Exp $
1.4       takayama    2: \name{hgm.pwishart}
                      3: \alias{hgm.pwishart}
1.1       takayama    4: %- Also NEED an '\alias' for EACH other topic documented here.
                      5: \title{
1.4       takayama    6:     The function hgm.pwishart evaluates the cumulative distribution function
1.7       takayama    7:   of random wishart matrices.
1.1       takayama    8: }
                      9: \description{
1.4       takayama   10:     The function hgm.pwishart evaluates the cumulative distribution function
1.7       takayama   11:   of random wishart matrices of size m times m.
1.1       takayama   12: }
                     13: \usage{
1.9       takayama   14: hgm.pwishart(m,n,beta,q0,approxdeg,h,dp,q,mode,method,
                     15:             err,automatic,assigned_series_error,verbose)
1.1       takayama   16: }
                     17: %- maybe also 'usage' for other objects documented here.
                     18: \arguments{
1.2       takayama   19:   \item{m}{The dimension of the Wishart matrix.}
                     20:   \item{n}{The degree of freedome (a parameter of the Wishart distribution)}
1.3       takayama   21:   \item{beta}{The eigenvalues of the inverse of the covariant matrix /2
                     22: (a parameter of the Wishart distribution).
                     23:     The beta is equal to inverse(sigma)/2.
1.1       takayama   24:   }
1.4       takayama   25:   \item{q0}{The point to evaluate the matrix hypergeometric series. q0>0}
1.1       takayama   26:   \item{approxdeg}{
1.2       takayama   27:     Zonal polynomials upto the approxdeg are calculated to evaluate
                     28:    values near the origin. A zonal polynomial is determined by a given
                     29:    partition (k1,...,km). We call the sum k1+...+km the degree.
1.1       takayama   30:   }
                     31:   \item{h}{
1.2       takayama   32:    A (small) step size for the Runge-Kutta method. h>0.
1.1       takayama   33:   }
                     34:   \item{dp}{
1.2       takayama   35:     Sampling interval of solutions by the Runge-Kutta method.
                     36:   }
1.4       takayama   37:   \item{q}{
                     38:     The second value y[0] of this function is the Prob(L1 < q)
1.2       takayama   39:     where L1 is the first eigenvalue of the Wishart matrix.
1.1       takayama   40:   }
1.3       takayama   41:   \item{mode}{
                     42:     When mode=c(1,0,0), it returns the evaluation
                     43:     of the matrix hypergeometric series and its derivatives at x0.
                     44:     When mode=c(1,1,(m^2+1)*p), intermediate values of P(L1 < x) with respect to
                     45:     p-steps of x are also returned.  Sampling interval is controled by dp.
                     46:   }
                     47:   \item{method}{
1.5       takayama   48:     a-rk4 is the default value.
1.3       takayama   49:     When method="a-rk4", the adaptive Runge-Kutta method is used.
                     50:     Steps are automatically adjusted by err.
                     51:   }
                     52:   \item{err}{
                     53:     When err=c(e1,e2), e1 is the absolute error and e2 is the relative error.
                     54:     As long as NaN is not returned, it is recommended to set to
                     55:     err=c(0.0, 1e-10), because initial values are usually very small.
                     56:   }
1.5       takayama   57:   \item{automatic}{
                     58:     automatic=1 is the default value.
                     59:     If it is 1, the degree of the series approximation will be increased until
                     60:     |(F(i)-F(i-1))/F(i-1)| < assigned_series_error where
                     61:     F(i) is the degree i approximation of the hypergeometric series
                     62:     with matrix argument.
1.6       takayama   63:     Step sizes for the Runge-Kutta method are also set automatically from
                     64:     the assigned_series_error if it is 1.
1.5       takayama   65:   }
                     66:   \item{assigned_series_error}{
                     67:     assigned_series_error=0.00001 is the default value.
                     68:   }
                     69:   \item{verbose}{
                     70:     verbose=0 is the default value.
                     71:     If it is 1, then steps of automatic degree updates and several parameters
                     72:     are output to stdout and stderr.
                     73:   }
1.1       takayama   74: }
                     75: \details{
1.2       takayama   76:   It is evaluated by the Koev-Edelman algorithm when x is near the origin and
                     77:   by the HGM when x is far from the origin.
1.3       takayama   78:   We can obtain more accurate result when the variables h is smaller,
                     79:   x0 is relevant value (not very big, not very small),
1.2       takayama   80:   and the approxdeg is more larger.
1.3       takayama   81:   A heuristic method to set parameters x0, h, approxdeg properly
                     82:   is to make x larger and to check if the y[0] approaches to 1.
1.1       takayama   83: %  \code{\link[RCurl]{postForm}}.
                     84: }
                     85: \value{
1.3       takayama   86: The output is x, y[0], ..., y[2^m] in the default mode,
1.2       takayama   87: y[0] is the value of the cumulative distribution
                     88: function P(L1 < x) at x.  y[1],...,y[2^m] are some derivatives.
                     89: See the reference below.
1.1       takayama   90: }
                     91: \references{
1.2       takayama   92: H.Hashiguchi, Y.Numata, N.Takayama, A.Takemura,
1.6       takayama   93: Holonomic gradient method for the distribution function of the largest root of a Wishart matrix,
                     94: Journal of Multivariate Analysis, 117, (2013) 296-312,
                     95: \url{http://dx.doi.org/10.1016/j.jmva.2013.03.011},
1.1       takayama   96: }
                     97: \author{
                     98: Nobuki Takayama
                     99: }
                    100: \note{
1.7       takayama  101: This function does not work well under the following cases:
                    102: 1. The beta (the set of eigenvalues)
                    103: is degenerated or is almost degenerated.
                    104: 2. The beta is very skew, in other words, there is a big eigenvalue
                    105: and there is also a small eigenvalue.
                    106: The error control is done by a heuristic method.
                    107: The obtained value is not validated automatically.
1.1       takayama  108: }
                    109:
                    110: %% ~Make other sections like Warning with \section{Warning }{....} ~
                    111:
1.10    ! takayama  112: %\seealso{
        !           113: %%%\code{\link{oxm.matrix_r2tfb}}
        !           114: %}
1.1       takayama  115: \examples{
                    116: ## =====================================================
1.3       takayama  117: ## Example 1.
1.1       takayama  118: ## =====================================================
1.4       takayama  119: hgm.pwishart(m=3,n=5,beta=c(1,2,3),q=10)
1.3       takayama  120: ## =====================================================
                    121: ## Example 2.
                    122: ## =====================================================
1.4       takayama  123: b<-hgm.pwishart(m=4,n=10,beta=c(1,2,3,4),q0=1,q=10,approxdeg=20,mode=c(1,1,(16+1)*100));
1.3       takayama  124: c<-matrix(b,ncol=16+1,byrow=1);
                    125: #plot(c)
1.1       takayama  126: }
                    127: % Add one or more standard keywords, see file 'KEYWORDS' in the
                    128: % R documentation directory.
                    129: \keyword{ Cumulative distribution function of random wishart matrix }
                    130: \keyword{ Holonomic gradient method }
                    131: \keyword{ HGM }
                    132: