Summarizing the gips object

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 times 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 become very large 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. For interpretation, see the Likelihood-ratio test section in vignette("Theory", package = "gips"). Comparison with the unrestricted model requires \(n \ge p\), or \(n \ge p + 1\) when the mean was estimated.

  7. n0 - the sample-size threshold: the number of permutation cycles, increased by one when was_mean_estimated = TRUE. The projection must also be numerically positive definite; see MLE_available below and \(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 posterior 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 posterior 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 = crossprod(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 times more likely the found_permutation is over the start_permutation. It cannot be a number less than 1. Remember that this number can become large 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. For interpretation, see the Likelihood-ratio test section in vignette("Theory", package = "gips"). Comparison with the unrestricted model requires \(n \ge p\), or \(n \ge p + 1\) when the mean was estimated.

  9. n0 - the sample-size threshold: the number of permutation cycles, increased by one when was_mean_estimated = TRUE. The projection must also be numerically positive definite; see MLE_available below and \(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 posterior 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 posterior 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 = crossprod(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 - the number of actual posterior evaluations during the recorded optimization. For multiple samples, one evaluation computes the joint objective.

  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 - the number of posterior evaluations after the best log-posterior value was first obtained. If this value is small, consider running find_MAP() again with optimizer = "continue". For optimizer = "BF", it is NULL.

  21. acceptance_rate - the fraction of eligible MH proposals accepted. Counts are pooled across MH stages, including in mixed histories; HC contributes to neither count. The value is NULL for histories without MH stages.

Both summaries also contain MLE_available: whether the sample-size requirement is met and all projected covariance matrices pass the numerical positive-definiteness check used by logLik().

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.

Multi-sample

For multi-sample gips objects the summary includes the number of groups G, the full vector of per-group sample sizes, and the total n_parameters (which equals G * dim_omega(sigma)). The sample-size check is min(n_g) >= n0, and every projected covariance matrix must be numerically positive definite for MLE_available to be TRUE. The Likelihood-Ratio test is not available for multi-sample objects and is reported as NULL.

See also

• find_MAP() - Usually, the summary.gips() is called on the output of find_MAP().

• log_posteriori_of_gips() - Calculate the likelihood of a permutation.

• AIC.gips(), BIC.gips() - Calculate Akaike's or Bayesian Information Criterion

• project_matrix() - Project the known matrix on the found permutations space.

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))
#> $optimized
#> [1] FALSE
#> 
#> $start_permutation
#> [1] ()
#> 
#> $start_permutation_log_posteriori
#> [1] -31.54222
#> 
#> $times_more_likely_than_id
#> [1] 1
#> 
#> $log_times_more_likely_than_id
#> [1] 0
#> 
#> $likelihood_ratio_test_statistics
#> [1] 0
#> 
#> $likelihood_ratio_test_p_value
#> NULL
#> 
#> $n0
#> [1] 7
#> 
#> $S_matrix
#>           [,1]      [,2]      [,3]      [,4]      [,5]      [,6]
#> [1,] 1.0494842 0.7252864 0.6235954 0.6491538 1.0485598 1.2153406
#> [2,] 0.7252864 1.0606126 0.8077534 0.6139671 0.5084607 0.6452723
#> [3,] 0.6235954 0.8077534 1.3994864 0.9755517 0.9012682 0.2643403
#> [4,] 0.6491538 0.6139671 0.9755517 1.0954129 0.8863493 0.6461863
#> [5,] 1.0485598 0.5084607 0.9012682 0.8863493 1.4804070 1.1258938
#> [6,] 1.2153406 0.6452723 0.2643403 0.6461863 1.1258938 1.7360910
#> 
#> $number_of_observations
#> [1] 13
#> 
#> $was_mean_estimated
#> [1] TRUE
#> 
#> $delta
#> [1] 3
#> 
#> $D_matrix
#>          [,1]     [,2]     [,3]     [,4]     [,5]     [,6]
#> [1,] 1.303582 0.000000 0.000000 0.000000 0.000000 0.000000
#> [2,] 0.000000 1.303582 0.000000 0.000000 0.000000 0.000000
#> [3,] 0.000000 0.000000 1.303582 0.000000 0.000000 0.000000
#> [4,] 0.000000 0.000000 0.000000 1.303582 0.000000 0.000000
#> [5,] 0.000000 0.000000 0.000000 0.000000 1.303582 0.000000
#> [6,] 0.000000 0.000000 0.000000 0.000000 0.000000 1.303582
#> 
#> $n_parameters
#> [1] 21
#> 
#> $AIC
#> [1] 163.442
#> 
#> $BIC
#> [1] 175.3059
#> 
#> $MLE_available
#> [1] TRUE
#> 

g_map <- find_MAP(g, max_iter = 10, show_progress_bar = FALSE, optimizer = "Metropolis_Hastings")
unclass(summary(g_map))
#> $optimized
#> [1] TRUE
#> 
#> $found_permutation
#> [1] (1452)
#> 
#> $found_permutation_log_posteriori
#> [1] -28.37266
#> 
#> $start_permutation
#> [1] ()
#> 
#> $start_permutation_log_posteriori
#> [1] -31.54222
#> 
#> $times_more_likely_than_start
#> [1] 23.79708
#> 
#> $log_times_more_likely_than_start
#> [1] 3.169563
#> 
#> $likelihood_ratio_test_statistics
#> [1] 32.77581
#> 
#> $likelihood_ratio_test_p_value
#> [1] 0.001841075
#> 
#> $n0
#> [1] 4
#> 
#> $S_matrix
#>           [,1]      [,2]      [,3]      [,4]      [,5]      [,6]
#> [1,] 1.0494842 0.7252864 0.6235954 0.6491538 1.0485598 1.2153406
#> [2,] 0.7252864 1.0606126 0.8077534 0.6139671 0.5084607 0.6452723
#> [3,] 0.6235954 0.8077534 1.3994864 0.9755517 0.9012682 0.2643403
#> [4,] 0.6491538 0.6139671 0.9755517 1.0954129 0.8863493 0.6461863
#> [5,] 1.0485598 0.5084607 0.9012682 0.8863493 1.4804070 1.1258938
#> [6,] 1.2153406 0.6452723 0.2643403 0.6461863 1.1258938 1.7360910
#> 
#> $number_of_observations
#> [1] 13
#> 
#> $was_mean_estimated
#> [1] TRUE
#> 
#> $delta
#> [1] 3
#> 
#> $D_matrix
#>          [,1]     [,2]     [,3]     [,4]     [,5]     [,6]
#> [1,] 1.303582 0.000000 0.000000 0.000000 0.000000 0.000000
#> [2,] 0.000000 1.303582 0.000000 0.000000 0.000000 0.000000
#> [3,] 0.000000 0.000000 1.303582 0.000000 0.000000 0.000000
#> [4,] 0.000000 0.000000 0.000000 1.303582 0.000000 0.000000
#> [5,] 0.000000 0.000000 0.000000 0.000000 1.303582 0.000000
#> [6,] 0.000000 0.000000 0.000000 0.000000 0.000000 1.303582
#> 
#> $n_parameters
#> [1] 8
#> 
#> $AIC
#> [1] 170.2178
#> 
#> $BIC
#> [1] 174.7374
#> 
#> $optimization_algorithm_used
#> [1] "Metropolis_Hastings"
#> 
#> $did_converge
#> NULL
#> 
#> $number_of_log_posteriori_calls
#> [1] 8
#> 
#> $whole_optimization_time
#> Time difference of 0.002931595 secs
#> 
#> $log_posteriori_calls_after_best
#> [1] 0
#> 
#> $acceptance_rate
#> [1] 0.3333333
#> 
#> $MLE_available
#> [1] TRUE
#> 

g_map2 <- find_MAP(g, max_iter = 10, show_progress_bar = FALSE, optimizer = "hill_climbing")
summary(g_map2)
#> The optimized `gips` object.
#> 
#> Permutation:
#>  (1,5,4,2)(3,6)
#> 
#> Log_posteriori:
#>  -23.55936
#> 
#> Times more likely than starting permutation:
#>  2930.312
#> 
#> The p-value of Likelihood-Ratio test:
#>  0.02138
#> 
#> The number of observations:
#>  13
#> 
#> The mean in the `S` matrix was estimated.
#> Therefore, one degree of freedom was lost.
#> There are 12 degrees of freedom left.
#> 
#> n0 = number of cycles in a permutation + 1 (as the mean was estimated):
#>  3
#> 
#> The MLE estimator based on the found permutation does exist,
#> since the number of observations (13) is bigger than n0 (3),
#> and the projected covariance matrix is numerically positive definite.
#> 
#> The number of free parameters in the covariance matrix:
#>  7
#> 
#> BIC:
#>  166.0458
#> 
#> AIC:
#>  162.0912
#> 
#> --------------------------------------------------------------------------------
#> Optimization algorithm:
#>  hill_climbing did converge
#> 
#> Posterior calculations during optimization:
#>  76
#> 
#> Optimization time:
#>  0.02270412 secs
#> 
#> Posterior calculations after first reaching the best value:
#>  18
# ================================================================================
S <- matrix(c(1, 0.5, 0.5, 2), nrow = 2, byrow = TRUE)
g <- gips(S, 10)
print(summary(g))
#> The unoptimized `gips` object.
#> 
#> Permutation:
#>  ()
#> 
#> Log_posteriori:
#>  -15.4837
#> 
#> The current permutation is id, so Likelihood-Ratio test cannot be performed (there is nothing to compare)
#> 
#> The number of observations:
#>  10
#> 
#> The mean in the `S` matrix was estimated.
#> Therefore, one degree of freedom was lost.
#> There are 9 degrees of freedom left.
#> 
#> n0 = number of cycles in a permutation + 1 (as the mean was estimated):
#>  3
#> 
#> The MLE estimator based on the found permutation does exist,
#> since the number of observations (10) is bigger than n0 (3),
#> and the projected covariance matrix is numerically positive definite.
#> 
#> The number of free parameters in the covariance matrix:
#>  3
#> 
#> BIC:
#>  63.02608
#> 
#> AIC:
#>  62.11833