summary.gips: Summarizing the gips object
In PrzeChoj/gips: Gaussian Model Invariant by Permutation Symmetry

summary.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. log_times_more_likely_than_id - log of times_more_likely_than_id.
6. likelihood_ratio_test_statistics, likelihood_ratio_test_p_value - statistics and p-value of Likelihood Ratio test, where the H_0 is that the data was drawn from the normal distribution with Covariance matrix invariant under the given permutation. The p-value is calculated from the asymptotic distribution. Note that this is sensibly defined only for n \ge p.
7. 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.
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 the output of 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. n_parameters - number of free parameters in the covariance matrix.
13. AIC, BIC - output of AIC.gips() and BIC.gips() functions.
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. log_times_more_likely_than_start - log of times_more_likely_than_start.
8. likelihood_ratio_test_statistics, likelihood_ratio_test_p_value - statistics and p-value of Likelihood Ratio test, where the H_0 is that the data was drawn from the normal distribution with Covariance matrix invariant under found_permutation. The p-value is calculated from the asymptotic distribution. Note that this is sensibly defined only for n \ge p.
9. 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).
10. S_matrix - the underlying matrix. This matrix will be used in calculations of the posteriori value in log_posteriori_of_gips().
11. 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().
12. 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.
13. delta, D_matrix - the hyperparameters of the Bayesian method. See the Hyperparameters section of gips() documentation.
14. n_parameters - number of free parameters in the covariance matrix.
15. AIC, BIC - output of AIC.gips() and BIC.gips() functions.
16. optimization_algorithm_used - all used optimization algorithms in order (one could start optimization with "MH", and then do an "HC").
17. did_converge - a boolean, did the last used algorithm converge.
18. number_of_log_posteriori_calls - how many times was the log_posteriori_of_gips() function called during the optimization.
19. whole_optimization_time - how long was the optimization process; the sum of all optimization times (when there were multiple).
20. 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.
21. 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.1, 0.8, 0.6, 0.4, 0.6, 0.8,
    0.8, 1.1, 0.8, 0.6, 0.4, 0.6,
    0.6, 0.8, 1.1, 0.8, 0.6, 0.4,
    0.4, 0.6, 0.8, 1.1, 0.8, 0.6,
    0.6, 0.4, 0.6, 0.8, 1.1, 0.8,
    0.8, 0.6, 0.4, 0.6, 0.8, 1.1
  ),
  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)
unclass(summary(g))

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))

PrzeChoj/gips documentation built on June 12, 2025, 12:23 a.m.