The hardware and bandwidth for this mirror is donated by METANET, the Webhosting and Full Service-Cloud Provider.
If you wish to report a bug, or if you are interested in having us mirror your free-software or open-source project, please feel free to contact us at mirror[@]metanet.ch.

Using the wishmom Package

Raymond Kan and Preston Liang

2024-08-25

Introduction

The wishmom package provides functions to compute the expectation of matrix-valued functions of \(\beta\)-Wishart and inverse \(\beta\)-Wishart distributions (\(\beta=1\): Real Wishart, \(\beta=2\): Complex Wishart, \(\beta=4\): Quaternion Wishart, \(\beta=8\): Octonion Wishart). The main functions in this package are wishmom() and iwishmom(), which handle the numerical computation of moments of \(\beta\)-Wishart and inverse \(\beta\)-Wishart distributions, respectively. The corresponding functions for generating analytical expressions of moments of \(\beta\)-Wishart and inverse \(\beta\)-Wishart distributions are wishmom_sym() and iwishmom_sym(). These programs are developed based on the results in Letac and Massam (2004) and Hillier and Kan (2024).

You can install the package and load it using:

install.packages("wishmom")
library("wishmom")


Mathematical Background

\(\beta\)-Wishart Distribution

The \(\beta\)-Wishart distribution is a fundamental distribution in multivariate statistics. When \(\beta=1,\;2,\;4,\;8\), it is the real Wishart, complex Wishart, quaternion Wishart, and octonion Wishart, respectively. The density function of \(W \sim W_m^\beta(n,\Sigma)\), i,e., a \(\beta\)-Wishart distribution with \(n\) degrees of freedom and an \(m \times m\) covariance matrix \(\Sigma\), is given by (when \(n > m-1\)) (see Díaz-García and Gutiérrez-Jáimez (2011, Corollary 1))

\[ f(W) = \frac{\left(\frac{\beta}{2}\right)^\frac{mn\beta}{2}}{\Gamma_m^{(\beta)}\left(\frac{n \beta}{2}\right) |\Sigma|^\frac{n \beta}{2}}|W|^{\frac{(n-m+1)\beta}{2}-1} \mbox{etr}\left(-\frac{\beta \Sigma^{-1}W}{2}\right), \]

where

\[ \Gamma_m^{(\beta)}(a) = \pi^\frac{m(m-1)\beta}{4}\prod_{i=1}^m \Gamma\left(a-\frac{(i-1)\beta}{2}\right). \]

Note that we do not require \(n\) to be an integer but the definition of the density of \(W\) requires \(\beta = 1,\;2,\;4\) or \(8\). However, if our interest is only on the functions of eigenvalues of \(W\), we can generalize this to any real \(\beta>0\). Therefore, for any symmetric functions (say power-sum) of the eigenvalues of \(W\), they can be well defined even when \(\beta\) is not equal to \(1,\; 2,\;4\) or \(8\). For \(W \sim W_m^\beta(n,\Sigma)\), the joint density of its eigenvalues \(\lambda_1 \geq \cdots \geq \lambda_m\) is given by (see Dresnky, Edelman, Genoar, Kan, and Koev (2021))

\[ f(\lambda_1,\ldots,\lambda_m) = \frac{| \Sigma|^{-\frac{n\beta}{2}}}{\mathcal{K}_m^ {(\beta)}\left(\frac{n\beta}{2}\right)} |\Lambda|^{\frac{(n-m+1)\beta}{2}-1} {}_0^{}F_0^{(\beta)}\left(-\frac{\beta}{2}\Lambda,\Sigma^{-1}\right)\prod_{1 \leq i < j \leq m}(\lambda_i-\lambda_j)^{\beta}, \] where \(\Lambda = \mbox{Diag}(\lambda_1,\ldots,\lambda_m)\),

\[ \mathcal{K}_m^{(\beta)}(a) = \frac{\left(\frac{2}{\beta}\right)^{ma}} {\pi^{\frac{m(m-1)\beta}{2}}} \frac{\Gamma_m^{(\beta)}\left(\frac{m\beta}{2}\right)\Gamma_m^{(\beta)}(a)}{\left[\Gamma\left(\frac{\beta}{2}\right)\right]^m}, \]

\[ {}_0^{}F_0^{(\beta)}(A,B) = \sum_{k=0}^\infty \sum_{\kappa \vdash k} \frac{C_\kappa^{(\beta)}(A)C_\kappa^{(\beta)}(B)} {k!C_\kappa^{(\beta)}(I_m)}, \]

and \(C_\kappa^{(\beta)}(X)\) is the Jack function of the eigenvalues of \(X\).

Instead of using \(\beta\), we use \(\alpha = 2/\beta\) in our programs to describe the type of Wishart distribution. Therefore, \(\alpha=2\) is for real Wishart, \(\alpha=1\) is for complex Wishart, and \(\alpha =1/2\) is for quaternion Wishart.

Moments of Matrix-valued Functions of \(\beta\)-Wishart and Inverse \(\beta\)-Wishart Distributions

Let \(\lambda = (\lambda_1,\ldots, \lambda_k)\) be an integer partition of a positive integer \(k\), where \(|\lambda|= \lambda_1+\ldots+\lambda_k=k\), with \(\lambda_1 \geq \lambda_2 \geq \cdots \geq \lambda_k \geq 0\). The power-sum symmetric function \(p_\lambda(W)\) of \(W\) corresponding to a partition \(\lambda\) is defined as

\[ p_{\lambda}(W) = \prod_{i=1}^{\ell(\lambda)}p_{\lambda_i}(W), \]

where \(\ell(\lambda)\) is the number of non-zero parts of \(\lambda\), and \(p_i(W) = \mbox{tr}(W^i)\). We are interested in computing

\[ \mathbb{E}[W^rp_{\lambda}(W)]\;\;\;\;\mbox{and} \;\;\;\; \mathbb{E}[W^{-r}p_{\lambda}(W^{-1})], \]

where \(W \sim W^{\beta}_m(n,\Sigma)\).

The method that we use is based on a generalization of the recurrence relations given in Hillier and Kan (2024) for which the cases of \(\beta = 1\) and \(2\) were developed. Specifically, we have the following recurrence relations:

\[\begin{align} \mathbb{E}[W^{r+1}p_{\lambda}(W)] & = \left[n+\left(\frac{2}{\beta}-1\right)r\right]\Sigma \mathbb{E}[W^{r} p_{\lambda}(W)]+ \sum_{j=1}^{r} \Sigma \mathbb{E}[W^{r-j}p_j(W)p_{\lambda}(W)] \nonumber \\ & \;\;\;\;{}+\frac{2}{\beta}\sum_{i=1}^{\ell(\lambda)}\lambda_i \Sigma \mathbb{E}\left[W^{r+\lambda_i}p_{\lambda_{(i)}}(W)\right], \\ \Sigma^{-1}\mathbb{E}[W^{-r}p_{\lambda}(W^{-1})] & = \left[\tilde{n}-\left(\frac{2}{\beta}-1\right)r\right]\mathbb{E}[W^{-(r+1)}p_{\lambda}(W^{-1})] -\sum_{j=1}^{r} \mathbb{E}[W^{-r-1+j}p_j(W^{-1})p_{\lambda}(W^{-1})] \nonumber \\ & \;\;\;\;{}-\frac{2}{\beta} \sum_{i=1}^{\ell(\lambda)}\lambda_i \mathbb{E}[W^{-r-1-\lambda_i}p_{\lambda_{(i)}}(W^{-1})], \end{align}\] where \(\tilde{n}= n-m+1-(2/\beta)\) and \(\lambda_{(i)}\) is \(\lambda\) with its \(i\)-th element removed. Together with the boundary conditions \(\mathbb{E}[W] = n\Sigma\) and \(\mathbb{E}[W^{-1}] = \Sigma^{-1}/\tilde{n}\), we can obtain \(\mathbb{E}[E^rp_{\lambda}(W)]\) and \(\mathbb{E}[W^{-r}p_{\lambda}(W^{-1})]\). Note that \(\mathbb{E}[W^{-r}p_{\lambda}(W^{-1})]\) exists if and only if \(\tilde{n}>2(r+|\lambda|)\).

Let \(k=r+|\lambda|\). Hillier and Kan (2024) show that \[\begin{align} \mathbb{E}[W^{r}p_{\lambda}(W)] & = \sum_{i=1}^k\left[\sum_{\rho \vdash k-i} c_{\lambda,\rho}p_{\rho}(\Sigma)\right]\Sigma^i, \\ \mathbb{E}[W^{-r}p_{\lambda}(W^{-1})] & = \sum_{i=1}^k\left[\sum_{\rho \vdash k-i}\tilde{c}_{\lambda,\rho}p_{\rho}(\Sigma^{-1})\right]\Sigma^{-i}, \end{align}\] where \(c_{\lambda,\rho}\) and \(\tilde{c}_{\lambda,\rho}\) are constants that depend on \(n\) and \(\tilde{n}\), respectively, but they do not depend on \(\Sigma\). In addition, we have \[\begin{align} \mathbb{E}[p_{\lambda}(W)] & = \sum_{\kappa \vdash k} h_{\kappa}p_{\kappa}(\Sigma), \\ \mathbb{E}[p_{\lambda}(W^{-1})] & = \sum_{\kappa \vdash k} \tilde{h}_{\kappa}p_{\kappa}(\Sigma^{-1}), \end{align}\] where \(h_{\kappa}\) and \(\tilde{h}_{\kappa}\) are constants that depend on \(n\) and \(\tilde{n}\), repsectively, but they do not depend on \(\Sigma\).

Using the recurrence relations, Hillier and Kan (2024) develop efficient algorithms for computing the constants \(c_{\lambda,\rho}\), \(\tilde{c}_{\lambda,\rho}\), \(h_{\kappa}\) and \(\tilde{h}_{\kappa}\).


Main Functions in the Package

There are four main functions in this package: wishmom(), iwishmom(), wishmom_sym(), and iwishmom_sym(). The first two are used to numerically compute \(\mathbb{E}[W^rp_{\lambda}(W)]\) and \(\mathbb{E}[W^{-r}p_{\lambda}(W^{-1})]\), respectively. The last two are used to generate an analytical expression of \(\mathbb{E}[W^rp_{\lambda}(W)]\) and \(\mathbb{E}[W^{-r}p_{\lambda}(W^{-1})]\), respectively.

Moments of \(\beta\)-Wishart:

wishmom()

The function wishmom() computes \(\mathbb{E}\left[\prod_{j=1}^r \mbox{tr}(W^j)^{f_j}W^{iw}\right]\) numerically, where \(W \sim W_m^\beta(n, \Sigma)\). When \(iw=0\), it computes \(\mathbb{E}[\prod_{j=1}^r \mbox{tr}(W^j)^{f_j}]\).

Arguments

  • n: degrees of freedom of the \(\beta\)-Wishart distribution
  • S: covariance matrix of the \(\beta\)-Wishart distribution
  • f: a vector of nonnegative integers \(f_j\) that represents the power for \(\mbox{tr}(W^j)\), \(j=1,\ldots, r\)
  • iw: Power of \(W\)
  • alpha: The type of Wishart distribution (\(\alpha=2/\beta\)):
    • 1/2: Quaternion Wishart
    • 1: Complex Wishart
    • 2: Real Wishart (default)

Output

When \(iw=0\), it returns \(\mathbb{E}[\prod_{j=1}^r \mbox{tr}(W^j)^{f_j}]\). When \(iw \neq 0\), it returns \(\mathbb{E}[\prod_{j=1}^r \mbox{tr}(W^j)^{f_j}W^{iw}]\).

Examples

# Example 1: For E[tr(W)^4] with W ~ W_m^1(n,S), where n and S are defined below:
n <- 20
S <- matrix(c(25, 49,
              49, 109), nrow=2, ncol=2)
wishmom(n, S, 4) # iw = 0, for real Wishart distribution
#> [1] 8.705084e+13

# Example 2: For E[tr(W)^2*tr(W^3)*W^2] with W ~ W_m^1(n,S), where n and S, are defined below:
n <- 20
S <- matrix(c(25, 49,
              49, 109), nrow=2, ncol=2)
wishmom(n, S, c(2, 0, 1), 2, 2) # iw = 2, for real Wishart distribution
#>              [,1]         [,2]
#> [1,] 9.039462e+23 1.956948e+24
#> [2,] 1.956948e+24 4.258714e+24

# Example 3: For E[tr(W)^2*tr(W^3)] with W ~ W_m^2(n,S), where n and S are defined below:
n <- 20
S <- matrix(c(25, 49 + 2i,
              49 - 2i, 109), nrow=2, ncol=2)
wishmom(n, S, c(2, 0, 1), 0, 1) # iw = 0, for complex Wishart distribution
#> [1] 2.078126e+17

# Example 4: For E[tr(W)*tr(W^2)^2*tr(W^3)^2*W] with W ~ W_m^2(n,S), where n, S, are defined below:
n <- 20
S <- matrix(c(25, 49 + 2i,
              49 - 2i, 109), nrow=2, ncol=2)
wishmom(n, S, c(1, 2, 2), 1, 1) # iw = 1, for complex Wishart distribution
#>                            [,1]                       [,2]
#> [1,] 3.418999e+41+5.014362e+20i 6.943130e+41-2.833930e+40i
#> [2,] 6.943130e+41+2.833930e+40i 1.532151e+42-2.882805e+22i

wishmom_sym()

The function wishmom_sym() generates an analytical expression of \(\mathbb{E}\left[\prod_{j=1}^r \mbox{tr}(W^j)^{f_j}W^{iw}\right]\), where \(W \sim W_m^\beta(n, \Sigma)\). When \(iw=0\), it generates an analytical expression of \(\mathbb{E}[\prod_{j=1}^r \mbox{tr}(W^j)^{f_j}]\).

Arguments

  • f: a vector of nonnegative integers \(f_j\) that represents the power for \(\mbox{tr}(W^j)\), \(j=1,\ldots, r\)
  • iw: Power of \(W\)
  • alpha: The type of Wishart distribution (\(\alpha=2/\beta\)):
    • 1/2: Quaternion Wishart
    • 1: Complex Wishart
    • 2: Real Wishart (default)
  • latex: The type of output
    • TRUE: LaTeX expression
    • FALSE: Dataframe (default)

Output

When \(iw = 0\), the output is an analytical expression of \(\mathbb{E}[\prod_{j=1}^r \mbox{tr}(W^j)^{f_j}]\). When \(iw \neq 0\), the output is an analytical expression of \(\mathbb{E}[\prod_{j=1}^r \mbox{tr}(W^j)^{f_j}W^{iw}]\). If latex = FALSE (default), the output is a data frame that stores the coefficients for the analytical expression. If latex = TRUE, the output is a \(\LaTeX\) formatted string of the result in terms of \(n\) and \(\Sigma\).

Examples

# Example 1: For E[tr(W)^4] with W ~ W_m^1(n,Sigma), represented as a dataframe:
wishmom_sym(4) # iw = 0, for real Wishart distribution
#>     kappa h_kappa
#> 1       4      48
#> 2     3,1     32n
#> 3     2,2     12n
#> 4   2,1,1   12n^2
#> 5 1,1,1,1     n^3

# Example 2: For E[tr(W)*tr(W^2)W] with W ~ W_m^1(n,Sigma), represented as a dataframe:
wishmom_sym(c(1,1), 1) # iw = 1, for real Wishart distribution
#>   i   rho          c
#> 1 1     3    4n^2+4n
#> 2 1   2,1 n^3+n^2+4n
#> 3 1 1,1,1        n^2
#> 4 2     2  2n^2+2n+8
#> 5 2   1,1         6n
#> 6 3     1 4n^2+4n+16
#> 7 4  <NA>     24n+24

# Example 3: For E[tr(W)^4] with W ~ W_m^2(n,Sigma), represented as a LaTeX string:
writeLines(wishmom_sym(4, 0, 1, latex=TRUE)) # iw = 0, for complex Wishart distribution
#> (6)p_{(4)}(\Sigma)
#> +(8n)p_{(3,1)}(\Sigma)
#> +(3n)p_{(2,2)}(\Sigma)
#> +(6n^2)p_{(2,1,1)}(\Sigma)
#> +(n^3)p_{(1,1,1,1)}(\Sigma)

# Example 4: For E[tr(W)*tr(W^2)W] with W ~ W_m^2(n,Sigma), represented as a LaTeX string:
writeLines(wishmom_sym(c(1, 1), 1, 1, latex=TRUE)) # iw = 1, for complex Wishart distribution
#> [(2n^2)p_{(3)}(\Sigma)+(n^3+2n)p_{(2, 1)}(\Sigma)+(n^2)p_{(1, 1, 1)}(\Sigma)]\Sigma
#> +[(n^2+2)p_{(2)}(\Sigma)+(3n)p_{(1, 1)}(\Sigma)]\Sigma^2
#> +(2n^2+4)p_{(1)}(\Sigma)\Sigma^3
#> +(6n)\Sigma^4

Moments of Inverse \(\beta\)-Wishart:

iwishmom()

The function iwishmom() computes \(\mathbb{E}\left[\prod_{j=1}^r \mbox{tr}(W^{-j})^{f_j}W^{-iw}\right]\) numerically, where \(W \sim W_m^\beta(n, \Sigma)\). When \(iw=0\), it computes \(\mathbb{E}[\prod_{j=1}^r \mbox{tr}(W^{-j})^{f_j}]\).

Arguments

  • n: degrees of freedom of the \(\beta\)-Wishart distribution
  • S: covariance matrix of the \(\beta\)-Wishart distribution
  • f: a vector of nonnegative integers \(f_j\) that represents the power for \(\mbox{tr}(W^{-j})\), \(j=1,\ldots, r\)
  • iw: Power of \(W^{-1}\)
  • alpha: The type of Wishart distribution (\(\alpha=2/\beta\)):
    • 1/2: Quaternion Wishart
    • 1: Complex Wishart
    • 2: Real Wishart (default)

Output

When \(iw=0\), it returns \(\mathbb{E}[\prod_{j=1}^r \mbox{tr}(W^{-j})^{f_j}]\). When \(iw \neq 0\), it returns \(\mathbb{E}[\prod_{j=1}^r \mbox{tr}(W^{-j})^{f_j}W^{-iw}]\).

Examples

# Example 1: For E[tr(W^{-1})^2] with W ~ W_m^1(n,S), where n and S are defined below:
n <- 20
S <- matrix(c(25, 49,
              49, 109), nrow=2, ncol=2)
iwishmom(n, S, 2) # iw = 0, for real Wishart distribution
#> [1] 0.0006680892

# Example 2: For E[tr(W^{-1})^2*tr(W^{-3})W^{-2}] with W ~ W_m^1(n,S), where n and S are defined below:
n <- 20
S <- matrix(c(25, 49,
              49, 109), nrow=2, ncol=2)
iwishmom(n, S, c(2, 0, 1), 2, 2) # iw = 2, for real Wishart distribution
#>               [,1]          [,2]
#> [1,]  1.328434e-10 -6.101692e-11
#> [2,] -6.101692e-11  2.824292e-11

# Example 3: For E[tr(W^{-1})^2*tr(W^{-3})] with W ~ W_m^2(n,S), where n and S are defined below:
n <- 20
S <- matrix(c(25, 49 + 2i,
              49 - 2i, 109), nrow=2, ncol=2)
iwishmom(n, S, c(2, 0, 1), 0, 1) # iw = 0, for complex Wishart distribution
#> [1] 1.17985e-08

# Example 4: For E[tr(W^{-1})*tr(W^{-2})^2*tr(W^{-3})^2*W^{-1}] with W ~ W_m^2(n,S), where n and S are defined below:
n <- 30
S <- matrix(c(25, 49 + 2i,
              49 -2i, 109), nrow=2, ncol=2)
iwishmom(n, S, c(1, 2, 2), 1, 1) # iw = 1, for complex Wishart distribution
#>                             [,1]                        [,2]
#> [1,]  1.348928e-21+0.000000e+00i -6.116211e-22+2.496413e-23i
#> [2,] -6.116211e-22-2.496413e-23i  3.004350e-22+0.000000e+00i

iwishmom_sym()

The function iwishmom_sym() generates an analytical expression of \(\mathbb{E}\left[\prod_{j=1}^r \mbox{tr}(W^{-j})^{f_j}W^{-iw}\right]\), where \(W \sim W_m^\beta(n, \Sigma)\). When \(iw=0\), it generates an analytical expression of \(\mathbb{E}[\prod_{j=1}^r \mbox{tr}(W^{-j})^{f_j}]\).

Arguments

  • f: a vector of nonnegative integers \(f_j\) that represents the power for \(\mbox{tr}(W^{-j})\), \(j=1,\ldots, r\)
  • iw: Power of \(W^{-1}\)
  • alpha: The type of Wishart distribution (\(\alpha=2/\beta\)):
    • 1/2: Quaternion Wishart
    • 1: Complex Wishart
    • 2: Real Wishart (default)
  • latex: The type of output
    • TRUE: LaTeX expression
    • FALSE: Dataframe (default)

Output

When \(iw = 0\), the output is an analytical expression of \(\mathbb{E}[\prod_{j=1}^r \mbox{tr}(W^{-j})^{f_j}]\). When \(iw \neq 0\), the output is an analytical expression of \(\mathbb{E}[\prod_{j=1}^r \mbox{tr}(W^{-j})^{f_j}W^{-iw}]\). If latex = FALSE (default), the output is a data frame that stores the coefficients for the analytical expression. If latex = TRUE, the output is a \(\LaTeX\) formatted string of the result in terms of \(\tilde{n}\) and \(\Sigma\), where \(\tilde{n} = n-m+1-\alpha\) and \(m\) is the dimension of the \(\beta\)-Wishart distribution.

Examples

# Example 1: For E[tr(W^{-1})^4] with W ~ W_m^1(n,Sigma), represented as a dataframe:
iwishmom_sym(4) # iw = 0, for real Wishart distribution
#> $dataframe
#>     kappa      h_kappa_numerator
#> 1       4              240n1-288
#> 2     3,1           64n1^2-256n1
#> 3     2,2        12n1^2-60n1+216
#> 4   2,1,1  12n1^3-72n1^2+36n1+72
#> 5 1,1,1,1 n1^4-7n1^3+n1^2+35n1-6
#> 
#> $denominator
#> [1] "n1^8-7n1^7-11n1^6+107n1^5+34n1^4-388n1^3-24n1^2+288n1"

# Example 2: For E[tr(W^{-1})*tr(W^{-2})W^{-1}] with W ~ W_m^1(n,Sigma), represented as a dataframe:
iwishmom_sym(c(1,1), 1) # iw = 1, for real Wishart distribution
#> $dataframe
#>   i   rho          c_numerator
#> 1 1     3 4n1^3-16n1^2-20n1+24
#> 2 1   2,1 n1^4-6n1^3+3n1^2+6n1
#> 3 1 1,1,1     n1^3-6n1^2+3n1+6
#> 4 2     2    2n1^3-10n1^2+36n1
#> 5 2   1,1       10n1^2-42n1+36
#> 6 3     1 4n1^3-16n1^2+60n1-72
#> 7 4  <NA>          40n1^2-48n1
#> 
#> $denominator
#> [1] "n1^8-7n1^7-11n1^6+107n1^5+34n1^4-388n1^3-24n1^2+288n1"

# Example 3: For E[tr(W^{-1})^4] with W ~ W_m^2(n,Sigma), represented as a LaTeX string:
writeLines(iwishmom_sym(4, 0, 1, latex=TRUE)) # iw = 0, for complex Wishart distribution
#> [(30\tilde{n})p_{(4)}(\Sigma^{-1})
#> +(16\tilde{n}^2-24)p_{(3,1)}(\Sigma^{-1})
#> +(3\tilde{n}^2+18)p_{(2,2)}(\Sigma^{-1})
#> +(6\tilde{n}^3-24\tilde{n})p_{(2,1,1)}(\Sigma^{-1})
#> +(\tilde{n}^4-8\tilde{n}^2+6)p_{(1,1,1,1)}(\Sigma^{-1})]
#> /(\tilde{n}^8-14\tilde{n}^6+49\tilde{n}^4-36\tilde{n}^2)

# Example 4: For E[tr(W^{-1})*tr(W^{-2})W^{-1}] with W ~ W_m^2(n,Sigma), represented as a LaTeX string:
writeLines(iwishmom_sym(c(1, 1), 1, 1, latex=TRUE)) # iw = 1, for complex Wishart distribution
#> [[(2\tilde{n}^3-8\tilde{n})p_{(3)}(\Sigma^{-1})+(\tilde{n}^4-4\tilde{n}^2)p_{(2,1)}(\Sigma^{-1})+(\tilde{n}^3-4\tilde{n})p_{(1,1,1)}(\Sigma^{-1})]\Sigma^{-1}
#> +[(\tilde{n}^3+6\tilde{n})p_{(2)}(\Sigma^{-1})+(5\tilde{n}^2)p_{(1,1)}(\Sigma^{-1})]\Sigma^{-2}
#> +(2\tilde{n}^3+12\tilde{n})p_{(1)}(\Sigma^{-1})\Sigma^{-3}
#> +(10\tilde{n}^2)\Sigma^{-4}]
#> /(\tilde{n}^8-14\tilde{n}^6+49\tilde{n}^4-36\tilde{n}^2)


Auxiliary Functions

Below is a list of auxiliary functions that are called by wishmom, iwishmom, wishmom_sym, and iwishmom_sym.

ip_desc()

The function ip_desc() generates all integer partitions of a given integer k in a reverse lexicographical order.

Arguments

  • k: A positive integer to be partitioned

Output

A matrix where each row represents an integer partition of k, listed in a reverse lexicographical order.

Examples

# Example 1: List of integer partitions of 3
ip_desc(3)
#>      [,1] [,2] [,3]
#> [1,]    3    0    0
#> [2,]    2    1    0
#> [3,]    1    1    1

# Example 2: List of integer partitions of 5
ip_desc(5)
#>      [,1] [,2] [,3] [,4] [,5]
#> [1,]    5    0    0    0    0
#> [2,]    4    1    0    0    0
#> [3,]    3    2    0    0    0
#> [4,]    3    1    1    0    0
#> [5,]    2    2    1    0    0
#> [6,]    2    1    1    1    0
#> [7,]    1    1    1    1    1

dkmap()

The function dkmap() computes the mapping matrix \(D_k\) discussed in Appendix B of Hillier and Kan (2024), modified for the general \(\beta\)-Wishart case. The returned matrix is \(D_k\) but with \(n\) in the diagonal elements removed.

Arguments

  • k: The order of the mapping matrix \(D_k\) (a positive integer)
  • alpha: The type of \(\beta\)-Wishart distribution (\(\alpha =2/\beta\)):
    • 1/2: Quaternion Wishart
    • 1: Complex Wishart
    • 2: Real Wishart (default)

Output

The mapping matrix \(D_k\) but with \(n\) removed from its diagonal.

Examples

# Example 1: Compute the mapping matrix for k = 2, real Wishart
dkmap(2)
#>      [,1] [,2] [,3] [,4]
#> [1,]    2    1    1    0
#> [2,]    2    1    0    1
#> [3,]    4    0    0    0
#> [4,]    0    4    0    0

# Example 2: Compute the mapping matrix for k = 1, complex Wishart
dkmap(1, 1)
#>      [,1] [,2]
#> [1,]    0    1
#> [2,]    1    0

# Example 3: Compute the mapping matrix for k = 2, quaternion Wishart
dkmap(2, 1/2)
#>      [,1] [,2] [,3] [,4]
#> [1,] -1.0  1.0    1    0
#> [2,]  0.5 -0.5    0    1
#> [3,]  1.0  0.0    0    0
#> [4,]  0.0  1.0    0    0

denpoly()

The function denpoly() computes the coefficients of the denominator polynomial for the elements \(\tilde{\mathcal{H}}_k\) and \(\tilde{\mathcal{C}}_k\). The function returns a vector containing the coefficients in descending powers of \(\tilde{n}\), with the last element being the coefficient of \(\tilde{n}\).

Arguments

  • k: The order of the polynomial (a positive integer)
  • alpha: The type of \(\beta\)-Wishart distribution (\(\alpha =2/\beta\)):
    • 1/2: Quaternion Wishart
    • 1: Complex Wishart
    • 2: Real Wishart (default)

Output

A vector containing the coefficients of the denominator polynomial in descending powers of \(\tilde{n}\) for the elements of \(\mathcal{\tilde{H}}_k\) and \(\tilde{\mathcal{C}}_k\).

Examples

# Example 1: Compute the denominator polynomial for k = 3 and alpha = 2
# Output corresponds to the polynomial n1^5-3n1^4-8n1^3+12n1^2+16n1,
# where n1 is \eqn{\tilde{n}}
denpoly(3)
#> [1]  1 -3 -8 12 16

# Example 2: Compute the denominator polynomial for k = 2 and alpha = 1
# Output corresponds to the polynomial n1^3-n1, where n1 is \eqn{\tilde{n}}
denpoly(2, alpha = 1)
#> [1]  1  0 -1

qk_coeff()

The function qk_coeff() computes the coefficient matrix \(\mathcal{C}_k\), which is obtained based on Corollary 1 of Hillier and Kan (2024), after a modification for the general \(\beta\)-Wishart case. \(\mathcal{C}_k\) is represented as a 3-dimensional array where each slice along the third dimension represents a coefficient matrix of the polynomial in descending powers of \(n\).

Arguments

  • k: The order of the \(\mathcal{C}_k\) matrix
  • alpha: The type of Wishart distribution (\(\alpha=2/\beta\)):
    • 1/2: Quaternion Wishart
    • 1: Complex Wishart
    • 2: Real Wishart (default)

Output

A 3-dimensional array representing \(\mathcal{C}_k\), a matrix of constants that allow us to obtain \(\mathbb{E}[p_{\lambda}(W)W^r]\), where \(r+|\lambda|=k\) and \(W \sim W_m^{\beta}(n,\Sigma)\).

Examples

# Example 1:
qk_coeff(2) # For real Wishart distribution with k = 2
#> , , 1
#> 
#>      [,1] [,2]
#> [1,]    1    0
#> [2,]    0    1
#> 
#> , , 2
#> 
#>      [,1] [,2]
#> [1,]    1    1
#> [2,]    2    0

# Example 2:
qk_coeff(3, 1) # For complex Wishart distribution with k = 3
#> , , 1
#> 
#>      [,1] [,2] [,3] [,4]
#> [1,]    1    0    0    0
#> [2,]    0    1    0    0
#> [3,]    0    0    1    0
#> [4,]    0    0    0    1
#> 
#> , , 2
#> 
#>      [,1] [,2] [,3] [,4]
#> [1,]    0    2    1    0
#> [2,]    2    0    0    1
#> [3,]    2    0    0    1
#> [4,]    0    2    1    0
#> 
#> , , 3
#> 
#>      [,1] [,2] [,3] [,4]
#> [1,]    1    0    0    1
#> [2,]    0    1    1    0
#> [3,]    0    2    0    0
#> [4,]    2    0    0    0

# Example 3:
qk_coeff(2, 1/2) # For quaternion Wishart distribution with k = 2
#> , , 1
#> 
#>      [,1] [,2]
#> [1,]    1    0
#> [2,]    0    1
#> 
#> , , 2
#> 
#>      [,1] [,2]
#> [1,] -0.5    1
#> [2,]  0.5    0

wish_ps()

The function wish_ps() computes the coefficient matrix \(\mathcal{H}_k\) that allows us to compute \(\mathbb{E}[p_{\kappa}(W)]\), which is obtained based on Proposition 5 of Hillier and Kan (2024), after a modification for the general \(\beta\)-Wishart case. \(\mathcal{H}_k\) is represented as a 3-dimensional array where each slice along the third dimension represents a coefficient matrix of the polynomial in descending powers of \(n\).

Arguments

  • k: The order of the \(\mathcal{H}_k\) matrix
  • alpha: The type of Wishart distribution (\(\alpha=2/\beta\)):
    • 1/2: Quaternion Wishart
    • 1: Complex Wishart
    • 2: Real Wishart (default)

Output

A 3-dimensional array representing \(\mathcal{H}_k\), a matrix of constants that allows us to obtain \(\mathbb{E}[p_{\kappa}(W)]\), where \(|\kappa|=k\) and \(W \sim W_m^{\beta}(n,\Sigma)\).

Examples

# Example 1:
wish_ps(3) # For real Wishart distribution with k = 3
#> , , 1
#> 
#>      [,1] [,2] [,3]
#> [1,]    1    0    0
#> [2,]    0    1    0
#> [3,]    0    0    1
#> 
#> , , 2
#> 
#>      [,1] [,2] [,3]
#> [1,]    3    3    0
#> [2,]    4    1    1
#> [3,]    0    6    0
#> 
#> , , 3
#> 
#>      [,1] [,2] [,3]
#> [1,]    4    3    1
#> [2,]    4    4    0
#> [3,]    8    0    0

# Example 2:
wish_ps(4, 1) # For complex Wishart distribution with k = 4
#> , , 1
#> 
#>      [,1] [,2] [,3] [,4] [,5]
#> [1,]    1    0    0    0    0
#> [2,]    0    1    0    0    0
#> [3,]    0    0    1    0    0
#> [4,]    0    0    0    1    0
#> [5,]    0    0    0    0    1
#> 
#> , , 2
#> 
#>      [,1] [,2] [,3] [,4] [,5]
#> [1,]    0    4    2    0    0
#> [2,]    3    0    0    3    0
#> [3,]    4    0    0    2    0
#> [4,]    0    4    1    0    1
#> [5,]    0    0    0    6    0
#> 
#> , , 3
#> 
#>      [,1] [,2] [,3] [,4] [,5]
#> [1,]    5    0    0    6    0
#> [2,]    0    7    3    0    1
#> [3,]    0    8    2    0    1
#> [4,]    6    0    0    5    0
#> [5,]    0    8    3    0    0
#> 
#> , , 4
#> 
#>      [,1] [,2] [,3] [,4] [,5]
#> [1,]    0    4    1    0    1
#> [2,]    3    0    0    3    0
#> [3,]    2    0    0    4    0
#> [4,]    0    4    2    0    0
#> [5,]    6    0    0    0    0

# Example 3:
wish_ps(2, 1/2) # For quaternion Wishart distribution with k = 2
#> , , 1
#> 
#>      [,1] [,2]
#> [1,]    1    0
#> [2,]    0    1
#> 
#> , , 2
#> 
#>      [,1] [,2]
#> [1,] -0.5    1
#> [2,]  0.5    0

qkn_coeff()

The function qkn_coeff() computes the inverse of the coefficient matrix \(\tilde{\mathcal{C}}_k\), which is obtained based on Corollary 2 of Hillier and Kan (2024), after a modification for the general \(\beta\)-Wishart case. \(\tilde{\mathcal{C}}_k^{-1}\) is represented as a 3-dimensional array where each slice along the third dimension represents a coefficient matrix of the polynomial in descending powers of \(\tilde{n}\).

Arguments

  • k: The order of the \(\tilde{\mathcal{C}}_k\) matrix
  • alpha: The type of Wishart distribution (\(\alpha=2/\beta\)):
    • 1/2: Quaternion Wishart
    • 1: Complex Wishart
    • 2: Real Wishart (default)

Output

A 3-dimensional array representing \(\tilde{\mathcal{C}}_k^{-1}\), a matrix of constants that allow us to obtain \(\mathbb{E}[p_{\lambda}(W^{-1})W^{-r}]\), where \(r+|\lambda|=k\) and \(W \sim W_m^{\beta}(n,\Sigma)\).

Examples

# Example 1:
qkn_coeff(2) # For real Wishart distribution with k = 2
#> , , 1
#> 
#>      [,1] [,2]
#> [1,]    1    0
#> [2,]    0    1
#> 
#> , , 2
#> 
#>      [,1] [,2]
#> [1,]   -1   -1
#> [2,]   -2    0

# Example 2:
qkn_coeff(3, 1) # For complex Wishart distribution with k = 3
#> , , 1
#> 
#>      [,1] [,2] [,3] [,4]
#> [1,]    1    0    0    0
#> [2,]    0    1    0    0
#> [3,]    0    0    1    0
#> [4,]    0    0    0    1
#> 
#> , , 2
#> 
#>      [,1] [,2] [,3] [,4]
#> [1,]    0   -2   -1    0
#> [2,]   -2    0    0   -1
#> [3,]   -2    0    0   -1
#> [4,]    0   -2   -1    0
#> 
#> , , 3
#> 
#>      [,1] [,2] [,3] [,4]
#> [1,]    1    0    0    1
#> [2,]    0    1    1    0
#> [3,]    0    2    0    0
#> [4,]    2    0    0    0

# Example 3:
qkn_coeff(2, 1/2) # For quaternion Wishart distribution with k = 2
#> , , 1
#> 
#>      [,1] [,2]
#> [1,]    1    0
#> [2,]    0    1
#> 
#> , , 2
#> 
#>      [,1] [,2]
#> [1,]  0.5   -1
#> [2,] -0.5    0

iwish_ps()

The function iwish_ps() computes the inverse of the coefficient matrix \(\tilde{\mathcal{H}}_k\) that allows us to compute \(\mathbb{E}[p_{\kappa}(W^{-1})]\), which is obtained based on Eq.(82) of Hillier and Kan (2024), after a modification for the general \(\beta\)-Wishart case. \(\tilde{\mathcal{H}}_k^{-1}\) is represented as a 3-dimensional array where each slice along the third dimension represents a coefficient matrix of the polynomial in descending powers of \(\tilde{n}\).

Arguments

  • k: The order of the \(\tilde{\mathcal{H}}_k\) matrix
  • alpha: The type of Wishart distribution (\(\alpha=2/\beta\)):
    • 1/2: Quaternion Wishart
    • 1: Complex Wishart
    • 2: Real Wishart (default)

Output

A 3-dimensional array representing \(\tilde{\mathcal{H}}_k^{-1}\), a matrix of constants that allows us to obtain \(\mathbb{E}[p_{\kappa}(W^{-1})]\), where \(|\kappa|=k\) and \(W \sim W_m^{\beta}(n,\Sigma)\).

Examples

# Example 1:
iwish_ps(3) # For real Wishart distribution with k = 3
#> , , 1
#> 
#>      [,1] [,2] [,3]
#> [1,]    1    0    0
#> [2,]    0    1    0
#> [3,]    0    0    1
#> 
#> , , 2
#> 
#>      [,1] [,2] [,3]
#> [1,]   -3   -3    0
#> [2,]   -4   -1   -1
#> [3,]    0   -6    0
#> 
#> , , 3
#> 
#>      [,1] [,2] [,3]
#> [1,]    4    3    1
#> [2,]    4    4    0
#> [3,]    8    0    0

# Example 2:
iwish_ps(4, 1) # For complex Wishart distribution with k = 4
#> , , 1
#> 
#>      [,1] [,2] [,3] [,4] [,5]
#> [1,]    1    0    0    0    0
#> [2,]    0    1    0    0    0
#> [3,]    0    0    1    0    0
#> [4,]    0    0    0    1    0
#> [5,]    0    0    0    0    1
#> 
#> , , 2
#> 
#>      [,1] [,2] [,3] [,4] [,5]
#> [1,]    0   -4   -2    0    0
#> [2,]   -3    0    0   -3    0
#> [3,]   -4    0    0   -2    0
#> [4,]    0   -4   -1    0   -1
#> [5,]    0    0    0   -6    0
#> 
#> , , 3
#> 
#>      [,1] [,2] [,3] [,4] [,5]
#> [1,]    5    0    0    6    0
#> [2,]    0    7    3    0    1
#> [3,]    0    8    2    0    1
#> [4,]    6    0    0    5    0
#> [5,]    0    8    3    0    0
#> 
#> , , 4
#> 
#>      [,1] [,2] [,3] [,4] [,5]
#> [1,]    0   -4   -1    0   -1
#> [2,]   -3    0    0   -3    0
#> [3,]   -2    0    0   -4    0
#> [4,]    0   -4   -2    0    0
#> [5,]   -6    0    0    0    0

# Example 3:
iwish_ps(2, 1/2) # For quaternion Wishart distribution with k = 2
#> , , 1
#> 
#>      [,1] [,2]
#> [1,]    1    0
#> [2,]    0    1
#> 
#> , , 2
#> 
#>      [,1] [,2]
#> [1,]  0.5   -1
#> [2,] -0.5    0

qkn_coeffr()

The function qkn_coeffr() computes the coefficient matrix \(\tilde{\mathcal{C}}_k\) for the general \(\beta\)-Wishart case. Elements of \(\tilde{\mathcal{C}}_k\) are rational polynomials of \(\tilde{n}\). The output contains two components: c and den. c is a 3-dimensional array where each slice along the third dimension represents a coefficient matrix of the numerator polynomial in descending powers of \(\tilde{n}\), and den is a vector that represents the coefficients of the denominator polynomial in descending power of \(\tilde{n}\).

Arguments

  • k: The order of the \(\tilde{\mathcal{C}}_k\) matrix
  • alpha: The type of Wishart distribution (\(\alpha=2/\beta\)):
    • 1/2: Quaternion Wishart
    • 1: Complex Wishart
    • 2: Real Wishart (default)

Output

The output has two components: c and den. c is a 3-dimensional array representing the numerator polynomial of \(\tilde{\mathcal{C}}_k\), and den is a vector representing the denominator polynomial of \(\tilde{\mathcal{C}}_k\), where \(\tilde{\mathcal{C}}_k\) is a matrix of constants that allow us to obtain \(\mathbb{E}[p_{\lambda}(W^{-1})W^{-r}]\), where \(r+|\lambda|=k\) and \(W \sim W_m^{\beta}(n,\Sigma)\).

Examples

# Example 1:
qkn_coeffr(2) # For real Wishart distribution with k = 2
#> $c
#> , , 1
#> 
#>      [,1] [,2]
#> [1,]    1    0
#> [2,]    0    1
#> 
#> , , 2
#> 
#>      [,1] [,2]
#> [1,]    0    1
#> [2,]    2   -1
#> 
#> 
#> $den
#> [1]  1 -1 -2
 
# Example 2:
qkn_coeffr(3, 1) # For complex Wishart distribution with k = 3
#> $c
#> , , 1
#> 
#>      [,1] [,2] [,3] [,4]
#> [1,]    1    0    0    0
#> [2,]    0    1    0    0
#> [3,]    0    0    1    0
#> [4,]    0    0    0    1
#> 
#> , , 2
#> 
#>      [,1] [,2] [,3] [,4]
#> [1,]    0    2    1    0
#> [2,]    2    0    0    1
#> [3,]    2    0    0    1
#> [4,]    0    2    1    0
#> 
#> , , 3
#> 
#>      [,1] [,2] [,3] [,4]
#> [1,]    0    0    0    2
#> [2,]    0    0    2    0
#> [3,]    0    4   -2    0
#> [4,]    4    0    0   -2
#> 
#> 
#> $den
#> [1]  1  0 -5  0  4

# Example 3:
qkn_coeffr(2, 1/2) # For quaternion Wishart distribution with k = 2
#> $c
#> , , 1
#> 
#>      [,1] [,2]
#> [1,]    1    0
#> [2,]    0    1
#> 
#> , , 2
#> 
#>      [,1] [,2]
#> [1,]  0.0  1.0
#> [2,]  0.5  0.5
#> 
#> 
#> $den
#> [1]  1.0  0.5 -0.5

iwish_psr()

The function iwish_psr() computes the coefficient matrix \(\tilde{\mathcal{H}}_k\) for the general \(\beta\)-Wishart case. Elements of \(\tilde{\mathcal{H}}_k\) are rational polynomials of \(\tilde{n}\). The output contains two components: c and den. c is a 3-dimensional array where each slice along the third dimension represents a coefficient matrix of the numerator polynomial in descending powers of \(\tilde{n}\), and den is a vector that represents the coefficients of the denominator polynomial in descending power of \(\tilde{n}\).

Arguments

  • k: The order of the \(\tilde{\mathcal{C}}_k\) matrix
  • alpha: The type of Wishart distribution (\(\alpha=2/\beta\)):
    • 1/2: Quaternion Wishart
    • 1: Complex Wishart
    • 2: Real Wishart (default)

Output

The output has two components: c and den. c is a 3-dimensional array representing the numerator polynomial of \(\tilde{\mathcal{H}}_k\), and den is a vector representing the denominator polynomial of \(\tilde{\mathcal{H}}_k\), where \(\tilde{\mathcal{H}}_k\) is a matrix of constants that allow us to obtain \(\mathbb{E}[p_{\lambda}(W^{-1})]\), where \(|\lambda|=k\) and \(W \sim W_m^{\beta}(n,\Sigma)\).

Examples

# Example 1:
iwsih_psr(2) # For real Wishart distribution with k = 2
#> $c
#> , , 1
#> 
#>      [,1] [,2]
#> [1,]    1    0
#> [2,]    0    1
#> 
#> , , 2
#> 
#>      [,1] [,2]
#> [1,]    0    1
#> [2,]    2   -1
#> 
#> 
#> $den
#> [1]  1 -1 -2
 
# Example 2:
iwish_psr(4, 1) # For complex Wishart distribution with k = 4
#> $c
#> , , 1
#> 
#>      [,1] [,2] [,3] [,4] [,5]
#> [1,]    1    0    0    0    0
#> [2,]    0    1    0    0    0
#> [3,]    0    0    1    0    0
#> [4,]    0    0    0    1    0
#> [5,]    0    0    0    0    1
#> 
#> , , 2
#> 
#>      [,1] [,2] [,3] [,4] [,5]
#> [1,]    0    4    2    0    0
#> [2,]    3    0    0    3    0
#> [3,]    4    0    0    2    0
#> [4,]    0    4    1    0    1
#> [5,]    0    0    0    6    0
#> 
#> , , 3
#> 
#>      [,1] [,2] [,3] [,4] [,5]
#> [1,]    1    0    0   10    0
#> [2,]    0    3    6    0    2
#> [3,]    0   16   -6    0    1
#> [4,]   10    0    0    1    0
#> [5,]    0   16    3    0   -8
#> 
#> , , 4
#> 
#>      [,1] [,2] [,3] [,4] [,5]
#> [1,]    0    4   -3    0    5
#> [2,]    3    0    0    3    0
#> [3,]   -6    0    0   12    0
#> [4,]    0    4    6    0   -4
#> [5,]   30    0    0  -24    0
#> 
#> , , 5
#> 
#>      [,1] [,2] [,3] [,4] [,5]
#> [1,]    0    0    0    0    0
#> [2,]    0   12   -9    0   -3
#> [3,]    0  -24   18    0    6
#> [4,]    0    0    0    0    0
#> [5,]    0  -24   18    0    6
#> 
#> 
#> $den
#> [1]   1   0 -14   0  49   0 -36   0

# Example 3:
iwish_psr(2, 1/2) # For quaternion Wishart distribution with k = 2
#> $c
#> , , 1
#> 
#>      [,1] [,2]
#> [1,]    1    0
#> [2,]    0    1
#> 
#> , , 2
#> 
#>      [,1] [,2]
#> [1,]  0.0  1.0
#> [2,]  0.5  0.5
#> 
#> 
#> $den
#> [1]  1.0  0.5 -0.5


References

Díaz-García, José and Gutiérrez-Jáimez, Ramón (2011). On Wishart distribution: som extension. Linear Algebra and its Applications, 435, 1296-1310.

Drensky, Vesselin, Edelman, Alan, Genoar, Tierney, Kan, Raymond, and Koev, Plamen (2021). The Densities and Distributions of the Largest Eigenvalue and the Trace of a Beta-Wishart Matrix. Random Matrices: Theory and Applications, 10(1).

Letac, Gérard, and Massam, Héelène (2004). All invariant moments of the Wishart distribution. Scandinavian Journal of Statistics, 31, 295-318.

Hillier, Grant, and Kan, Raymond (2024). On the expectations of equivariant matrix-valued functions of Wishart and inverse Wishart Matrices. Scandinavian Journal of Statistics, 51, 697-723.


These binaries (installable software) and packages are in development.
They may not be fully stable and should be used with caution. We make no claims about them.