% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/tclustICsol.R
\name{tclustICsol}
\alias{tclustICsol}
\alias{print.tclustICsol}
\title{Extracts a set of best relevant solutions obtained by \code{\link{tclustIC}}}
\usage{
tclustICsol(
  obj,
  whichIC = c("ALL", "MIXMIX", "MIXCLA", "CLACLA"),
  nsol = 5,
  index = c("Rand", "FM"),
  thresholdRI = 0.7,
  trace = FALSE
)
}
\arguments{
\item{obj}{An S3 object of class \code{\link{tclustIC}}
(output of \code{\link{tclustIC}}) containing the values
of the information criteria BIC (MIXMIX), ICL (MIXCLA) or CLA (CLACLA),
for different values of \code{k} (number of groups) and different
values of \code{c} (restriction factor), for a prespecified level of trimming.}

\item{whichIC}{A character value which Specifies the information criterion to 
use to extract best solutions. Possible values for \code{whichIC} are:
\itemize{
 \item "MIXMIX": a mixture model is fitted and for computing the information criterion
    the mixture likelihood is used. This option corresponds to the use of the Bayesian
    Information criterion (BIC). In output just the matrix \code{MIXMIX} is given.
\item "MIXCLA": a mixture model is fitted but to compute the information criterion
    the classification likelihood is used. This option corresponds to the use of the
    Integrated Complete Likelihood (ICL). In the output just the matrix \code{MIXCLA} is given.
\item "CLACLA": everything is based on the classification likelihood. This information
    criterion will be called CLA. In the output just the matrix \code{CLACLA} is given.
\item "ALL": both classification and mixture likelihood are used. In this case all
    three information criteria CLA, ICL and BIC are computed. In the output all
    three matrices \code{MIXMIX}, \code{MIXCLA} and \code{CLACLA} are given.
}}

\item{nsol}{Number of best solutions to extract from BIC/ICL matrix.
The default value of NumberOfBestSolutions is 5}

\item{index}{Index to use to compare partitions. If \code{index=Rand} (default) 
the adjusted Rand index is used, else, \code{index="FM"}, the adjusted 
Fowlkes and Mallows index is used}

\item{thresholdRI}{Threshold to identify spurious solutions - the threshold
 of the adjusted Rand index to use to consider two solutions as equivalent.
The default value of ThreshRandIndex is 0.7}

\item{trace}{Whether to print intermediate results. Default is \code{trace=FALSE}.}
}
\value{
The function returns an S3 object of type \code{tclustICsol} containing the following components:
 \item{call}{the matched call}
 \item{kk}{a vector containing the values of \code{k} (number of components) which have been considered.
     This vector is identical to the optional argument \code{kk} (default is \code{kk=1:5}.}
 \item{cc}{a vector containing the values of \code{c} (values of the restriction factor) which
     have been considered. This vector is identical to the optional argument \code{cc}
  (defalt is \code{cc=c(1, 2, 4, 8, 16, 32, 64, 128)}.}
 \item{alpha}{trimming level}
 \item{whichIC}{Information criteria used}
 \item{MIXMIXbs}{a matrix of lists of size \code{NumberOfBestSolutions-times-5} which
 contains the details of the best solutions for MIXMIX (BIC). Each row refers to a
 solution. The information which is stored in the columns is as follows.
 \itemize{
 \item 1st col = value of k for which solution takes place
 \item 2nd col = value of c for which solution takes place;
 \item 3rd col = a vector of length \code{d} which contains the values of \code{c}
     for which the solution is uniformly better.
 \item 4th col = a vector of length \code{d + r} which contains the values of \code{c}
     for which the solution is considered stable (i.e. for which the value
     of the adjusted Rand index (or the adjusted Fowlkes and Mallows index)
     does not go below the threshold defined in input option \code{ThreshRandIndex}).
 \item 5th col = string which contains 'true' or 'spurious'. The solution is labelled
     spurious if the value of the adjusted Rand index with the previous solutions
     is greater than ThreshRandIndex.
 }

 Remark: the field MIXMIXbs is present only if \code{whichIC=ALL} or \code{whichIC="MIXMIX"}.
 }
 \item{MIXMIXbsari}{a matrix of adjusted Rand indexes (or Fowlkes and Mallows indexes)
     associated with the best solutions for MIXMIX. A matrix of size \code{NumberOfBestSolutions-times-NumberOfBestSolutions}
     whose \code{i,j}-th entry contains the adjusted Rand index between classification produced by solution
     \code{i} and solution \code{j}, \code{i,j=1,2, ...,NumberOfBestSolutions}.

 Remark: the field \code{MIXMIXbsari} is present only if \code{whichIC=ALL} or \code{whichIC="MIXMIX"}.
 }
 \item{ARIMIX}{a matrix of adjusted Rand indexes between two consecutive value of \code{c}.
     Matrix of size \code{k-by-length(cc)-1}. The first column contains the ARI indexes
     between \code{cc[2]} and \code{cc[1]} given \code{k}.
     The second column contains the the ARI indexes between \code{cc[3]} and \code{cc[2]} given \code{k}.

 Remark: the field \code{ARIMIX} is present only if \code{whichIC=ALL} or \code{whichIC="MIXMIX"} or \code{whichIC="MIXCLA"}.
 }
 \item{MIXCLAbs}{has the same structure as \code{MIXMIXbs} but referres to MIXCLA.

 Remark: the field MIXCLAbs is present only if \code{whichIC=ALL} or \code{whichIC="MIXCLA"}.
 }
 \item{MIXCLAbsari}{has the same structure as \code{MIXMIXbsari} but referres to MIXCLA.

 Remark: the field \code{MIXMIXbsari} is present only if \code{whichIC=ALL} or \code{whichIC="MIXCLA"}.
 }
 \item{CLACLAbs}{has the same structure as \code{MIXMIXbs} but referres to CLACLA.

 Remark: the field CLACLAbs is present only if \code{whichIC=ALL} or \code{whichIC="CLACLA"}.
 }
 \item{CLACLAbsari}{has the same structure as \code{MIXMIXbsari} but referres to CLACLA.

 Remark: the field \code{CLACLAbsari} is present only if \code{whichIC=ALL} or \code{whichIC="CLACLA"}.
 }
 \item{ARICLA}{a matrix of adjusted Rand indexes between two consecutive value of \code{c}.
     Matrix of size \code{k-by-length(cc)-1}. The first column contains the ARI indexes
     between \code{cc[2]} and \code{cc[1]} given \code{k}.
     The second column contains the the ARI indexes between \code{cc[3]} and \code{cc[2]} given \code{k}.

 Remark: the field \code{ARICLA} is present only if \code{whichIC=ALL} or \code{whichIC="CLACLA"}.
 }
 \item{x}{the input data matrix of size \code{n-times-p} with which
     the Information Criteria were computed.}
}
\description{
The function \code{tclustICsol()} takes as input an object of class
 \code{\link{tclustIC}}, the output
 of function \code{\link{tclustIC}} (that is a series of matrices which contain
 the values of the information criteria BIC/ICL/CLA for different values of \code{k}
 and \code{c}) and extracts the first best solutions. Two solutions are considered
 equivalent if the value of the adjusted Rand index (or the adjusted Fowlkes and
 Mallows index) is above a certain threshold. For each tentative solution the program
 checks the adjacent values of \code{c} for which the solution is stable.
 A matrix with adjusted Rand indexes is given for the extracted solutions.
}
\examples{

 #--- EXAMPLE 1 ------------------------------------------
 \donttest{
 data(geyser2)
 (out <- tclustIC(geyser2, whichIC="MIXMIX", alpha=0.1))

 ##  Show the first two best solutions using as Information criterion MIXMIX
 cat("\nBest solutions using MIXMIX\n")
 outsol <- tclust::tclustICsol(out, whichIC="MIXMIX", nsol=2)
 print(outsol$MIXMIXbs)
 }

 #--- EXAMPLE 2 ------------------------------------------
 \donttest{
 data(flea)
 Y <- as.matrix(flea[, 1:(ncol(flea)-1)])    # select only the numeric variables
 rownames(Y) <- 1:nrow(Y)
 head(Y)

 (out <- tclustIC(Y, whichIC="CLACLA", alpha=0.1))
 ## Find the smallest value inside the table and write the corresponding
 ## values of k (number of groups) and c (restriction factor)
 inds <- which(out$CLACLA == min(out$CLACLA), arr.ind=TRUE)
 vals <- out$CLACLA[inds]
 cat("\nThe Smallest value of the IC is ", vals, 
     " and takes place for k=", out$kk[inds[1]], " and c=",   
     out$cc[inds[2]], "\n")

 ##  Show the first two best solutions using as Information criterion CLACLA
 cat("\nBest solutions using CLACLA\n")
 outsol <- tclust::tclustICsol(out, whichIC="CLACLA", nsol=2)
 print(outsol$CLACLAbs)
 
 }

 #--- EXAMPLE 3 ------------------------------------------
 \donttest{
 data(swissbank)
 (out <- tclustIC(swissbank, whichIC="ALL"))
 
 outsol <- tclust::tclustICsol(out, whichIC="ALL", nsol=2)
 print(outsol$CLACLAbs)
 
 }

}
\references{
Cerioli, A., Garcia-Escudero, L.A., Mayo-Iscar, A. and Riani M. (2017).
     Finding the Number of Groups in Model-Based Clustering via Constrained Likelihoods,
     \emph{Journal of Computational and Graphical Statistics}, pp. 404--416,
     https://doi.org/10.1080/10618600.2017.1390469.

 Hubert L. and Arabie P. (1985), Comparing Partitions, \emph{Journal of Classification}, 
     Vol. 2, pp. 193--218.
}
\seealso{
\code{\link{tclust}}, \code{\link{tclustIC}}
}
