R: Summarizing the gips object

summary.gips {gips}

R Documentation

Summarizing the gips object

Description

summary method for gips class.

Usage

## S3 method for class 'gips'
summary(object, ...)

## S3 method for class 'summary.gips'
print(x, ...)

Arguments

`object`	An object of class `gips`. Usually, a result of a `find_MAP()`.
`...`	Further arguments passed to or from other methods.
`x`	An object of class `summary.gips` to be printed

Value

The function summary.gips() computes and returns a list of summary statistics of the given gips object. Those are:

For unoptimized gips object:
1. optimized - FALSE.
2. start_permutation - the permutation this gips represents.
3. start_permutation_log_posteriori - the log of the a posteriori value the start permutation has.
4. times_more_likely_than_id - how many more likely the start_permutation is over the identity permutation, ⁠()⁠. It can be less than 1, meaning the identity permutation is more likely. Remember that this number can big and overflow to Inf or small and underflow to 0.
5. n0 - the minimum number of observations needed for the covariance matrix's maximum likelihood estimator (corresponding to a MAP) to exist. See C\sigma and n0 section in vignette("Theory", package = "gips") or in its pkgdown page.
6. S_matrix - the underlying matrix. This matrix will be used in calculations of the posteriori value in log_posteriori_of_gips().
7. number_of_observations - the number of observations that were observed for the S_matrix to be calculated. This value will be used in calculations of the posteriori value in log_posteriori_of_gips().
8. was_mean_estimated - given by the user while creating the gips object:
  - TRUE means the S parameter was the output of stats::cov() function;
  - FALSE means the S parameter was calculated with S = t(X) %*% X / number_of_observations.
9. delta, D_matrix - the hyperparameters of the Bayesian method. See the Hyperparameters section of gips() documentation.
10. AIC, BIC - output of AIC.gips() and BIC.gips() functions.
11. n_parameters - number of free parameters in the covariance matrix.
For optimized gips object:
1. optimized - TRUE.
2. found_permutation - the permutation this gips represents. The visited permutation with the biggest a posteriori value.
3. found_permutation_log_posteriori - the log of the a posteriori value the found permutation has.
4. start_permutation - the original permutation this gips represented before optimization. It is the first visited permutation.
5. start_permutation_log_posteriori - the log of the a posteriori value the start permutation has.
6. times_more_likely_than_start - how many more likely the found_permutation is over the start_permutation. It cannot be a number less than 1. Remember that this number can big and overflow to Inf.
7. n0 - the minimal number of observations needed for the existence of the maximum likelihood estimator (corresponding to a MAP) of the covariance matrix (see C\sigma and n0 section in vignette("Theory", package = "gips") or in its pkgdown page).
8. S_matrix - the underlying matrix. This matrix will be used in calculations of the posteriori value in log_posteriori_of_gips().
9. number_of_observations - the number of observations that were observed for the S_matrix to be calculated. This value will be used in calculations of the posteriori value in log_posteriori_of_gips().
10. was_mean_estimated - given by the user while creating the gips object:
  - TRUE means the S parameter was output of the stats::cov() function;
  - FALSE means the S parameter was calculated with S = t(X) %*% X / number_of_observations.
11. delta, D_matrix - the hyperparameters of the Bayesian method. See the Hyperparameters section of gips() documentation.
12. AIC, BIC - output of AIC.gips() and BIC.gips() functions.
13. n_parameters - number of free parameters in the covariance matrix.
14. optimization_algorithm_used - all used optimization algorithms in order (one could start optimization with "MH", and then do an "HC").
15. did_converge - a boolean, did the last used algorithm converge.
16. number_of_log_posteriori_calls - how many times was the log_posteriori_of_gips() function called during the optimization.
17. whole_optimization_time - how long was the optimization process; the sum of all optimization times (when there were multiple).
18. log_posteriori_calls_after_best - how many times was the log_posteriori_of_gips() function called after the found_permutation; in other words, how long ago could the optimization be stopped and have the same result. If this value is small, consider running find_MAP() again with optimizer = "continue". For optimizer = "BF", it is NULL.
19. acceptance_rate - only interesting for optimizer = "MH". How often was the algorithm accepting the change of permutation in an iteration.

The function print.summary.gips() returns an invisible NULL.

Methods (by generic)

print(summary.gips): Printing method for class summary.gips. Prints every interesting information in a form pleasant for humans.

Examples

require("MASS") # for mvrnorm()

perm_size <- 6
mu <- runif(6, -10, 10) # Assume we don't know the mean
sigma_matrix <- matrix(
  data = c(
    1.0, 0.8, 0.6, 0.4, 0.6, 0.8,
    0.8, 1.0, 0.8, 0.6, 0.4, 0.6,
    0.6, 0.8, 1.0, 0.8, 0.6, 0.4,
    0.4, 0.6, 0.8, 1.0, 0.8, 0.6,
    0.6, 0.4, 0.6, 0.8, 1.0, 0.8,
    0.8, 0.6, 0.4, 0.6, 0.8, 1.0
  ),
  nrow = perm_size, byrow = TRUE
) # sigma_matrix is a matrix invariant under permutation (1,2,3,4,5,6)
number_of_observations <- 13
Z <- MASS::mvrnorm(number_of_observations, mu = mu, Sigma = sigma_matrix)
S <- cov(Z) # Assume we have to estimate the mean

g <- gips(S, number_of_observations)

g_map <- find_MAP(g, max_iter = 10, show_progress_bar = FALSE, optimizer = "Metropolis_Hastings")
unclass(summary(g_map))

g_map2 <- find_MAP(g, max_iter = 10, show_progress_bar = FALSE, optimizer = "hill_climbing")
summary(g_map2)
# ================================================================================
S <- matrix(c(1, 0.5, 0.5, 2), nrow = 2, byrow = TRUE)
g <- gips(S, 10)
print(summary(g))

[Package gips version 1.2.1 Index]