% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/07_IRM.R, R/17_Biclustering_nominal_IRM.R,
%   R/18_Biclustering_ordinal_IRM.R, R/20_Biclustering_rated_IRM.R
\name{Biclustering_IRM}
\alias{Biclustering_IRM}
\alias{Biclustering_IRM.default}
\alias{Biclustering_IRM.binary}
\alias{Biclustering_IRM.nominal}
\alias{Biclustering_IRM.ordinal}
\alias{Biclustering_IRM.rated}
\title{Biclustering with Infinite Relational Model}
\usage{
Biclustering_IRM(U, ...)

\method{Biclustering_IRM}{default}(U, na = NULL, Z = NULL, w = NULL, ...)

\method{Biclustering_IRM}{binary}(
  U,
  Z = NULL,
  w = NULL,
  na = NULL,
  gamma_c = 1,
  gamma_f = 1,
  max_iter = 100,
  stable_limit = 5,
  minSize = 20,
  EM_limit = 20,
  seed = 123,
  verbose = TRUE,
  ...
)

\method{Biclustering_IRM}{nominal}(
  U,
  gamma_c = 1,
  gamma_f = 1,
  alpha = 1,
  max_iter = 100,
  stable_limit = 5,
  minSize = 20,
  EM_limit = 20,
  seed = 123,
  verbose = TRUE,
  ...
)

\method{Biclustering_IRM}{ordinal}(
  U,
  gamma_c = 1,
  gamma_f = 1,
  alpha = 1,
  mic = TRUE,
  max_iter = 100,
  stable_limit = 5,
  minSize = 20,
  EM_limit = 100,
  seed = 123,
  verbose = TRUE,
  ...
)

\method{Biclustering_IRM}{rated}(
  U,
  gamma_c = 1,
  gamma_f = 1,
  alpha = 1,
  max_iter = 100,
  stable_limit = 5,
  minSize = 20,
  EM_limit = 20,
  seed = 123,
  verbose = TRUE,
  ...
)
}
\arguments{
\item{U}{U is either a data class of exametrika, or raw data. When raw data is given,
it is converted to the exametrika class with the \link{dataFormat} function.}

\item{...}{Additional arguments passed to specific methods.}

\item{na}{na argument specifies the numbers or characters to be treated as missing values.}

\item{Z}{Z is a missing indicator matrix of the type matrix or data.frame}

\item{w}{w is item weight vector}

\item{gamma_c}{\eqn{\gamma_C} is the hyperparameter of the CRP and represents the
attractiveness of a new Class. As \eqn{\gamma_C} increases, the student is more likely
to be seated at a vacant class. The default is 1.}

\item{gamma_f}{\eqn{\gamma_F} is the hyperparameter of the CRP and represents the
attractiveness of a new Field. The greater this value it more likely to be classified
in the new field. The default is 1.}

\item{max_iter}{A maximum iteration number of IRM process. The default is 100.}

\item{stable_limit}{The IRM process exits the loop when the FRM stabilizes and no longer
changes significantly. This option sets the maximum number of stable iterations,
with a default of 5.}

\item{minSize}{A value used for readjusting the number of classes.If the size of each
class is less than \code{minSize}, the number of classes will be reduced. Note that this
under limit of size is not used for either all correct or all incorrect class.}

\item{EM_limit}{After IRM process, resizing the number of classes process will starts.
This process using EM algorithm,\code{EM_limit} is the maximum number of iteration with
default of 20.}

\item{seed}{Random seed for reproducibility. When a numeric value is provided,
\code{set.seed(seed)} is called before the Gibbs sampling begins, ensuring
reproducible results. The default is \code{123}, which guarantees deterministic
output. Set to \code{NULL} to disable seed setting and let the results depend
on the current state of the random number generator.}

\item{verbose}{verbose output Flag. default is TRUE}

\item{alpha}{Dirichlet distribution concentration parameter for the prior density of
field reference probabilities (rated/nominal IRM). Must be positive. The default is 1.}

\item{mic}{Logical; if TRUE, forces Field Reference Profiles to be monotonically
increasing across classes (ordinal IRM only). Default is TRUE.}
}
\value{
An object of class "exametrika" containing the IRM results.
See \code{Biclustering_IRM.binary} or \code{Biclustering_IRM.nominal} for details.

\describe{
\item{nobs}{Sample size. The number of rows in the dataset.}
\item{msg}{A character string indicating the model type. }
\item{testlength}{Length of the test. The number of items included in the test.}
\item{n_class}{Optimal number of classes (new naming convention).}
\item{n_field}{Optimal number of fields (new naming convention).}
\item{em_cycle}{Number of EM algorithm iterations (new naming convention).}
\item{Nclass}{Optimal number of classes (deprecated, use n_class).}
\item{Nfield}{Optimal number of fields (deprecated, use n_field).}
\item{EM_Cycle}{Number of EM algorithm iterations (deprecated, use em_cycle).}
\item{BRM}{Bicluster Reference Matrix}
\item{FRP}{Field Reference Profile}
\item{FRPIndex}{Index of FFP includes the item location parameters B and Beta,
the slope parameters A and Alpha, and the monotonicity indices C and Gamma.}
\item{TRP}{Test Reference Profile}
\item{FMP}{Field Membership Profile}
\item{Students}{Rank Membership Profile matrix.The s-th row vector of \eqn{\hat{M}_R}, \eqn{\hat{m}_R}, is the
rank membership profile of Student s, namely the posterior probability distribution representing the student's
belonging to the respective latent classes. It also includes the rank with the maximum estimated membership probability,
as well as the rank-up odds and rank-down odds.}
\item{LRD}{Latent Rank Distribution. see also \link{plot.exametrika}}
\item{LFD}{Latent Field Distribution. see also \link{plot.exametrika}}
\item{RMD}{Rank Membership Distribution.}
\item{TestFitIndices}{Overall fit index for the test.See also \link{TestFit}}
}

For nominal data, the returned list includes:
\describe{
\item{Q}{Response matrix.}
\item{Z}{Missing indicator matrix.}
\item{testlength}{Number of items.}
\item{nobs}{Sample size.}
\item{n_class}{Optimal number of classes.}
\item{n_field}{Optimal number of fields.}
\item{n_cycle}{Number of EM algorithm iterations.}
\item{FRP}{Field Reference Profile, a 3D array (nfld x ncls x maxQ).}
\item{LFD}{Latent Field Distribution.}
\item{LCD}{Latent Class Distribution.}
\item{FieldMembership}{Field membership probability matrix.}
\item{ClassMembership}{Class membership probability matrix.}
\item{FieldEstimated}{Estimated field assignment for each item.}
\item{ClassEstimated}{Estimated class assignment for each student.}
\item{Students}{Rank Membership Profile matrix with estimated class.}
\item{TestFitIndices}{Overall fit index for the test.}
\item{log_lik}{Log-likelihood of the model.}
}

For ordinal data, the returned list includes:
\describe{
\item{Q}{Response matrix.}
\item{Z}{Missing indicator matrix.}
\item{testlength}{Number of items.}
\item{nobs}{Sample size.}
\item{n_class}{Optimal number of classes.}
\item{n_field}{Optimal number of fields.}
\item{n_cycle}{Number of EM algorithm iterations.}
\item{FRP}{Field Reference Profile (BCRM), a 3D array (nfld x ncls x maxQ).}
\item{FRPIndex}{Index of FRP includes the item location parameters B and Beta,
the slope parameters A and Alpha, and the monotonicity indices C and Gamma.}
\item{TRP}{Test Reference Profile.}
\item{BFRP}{Bicluster Field Reference Profile (expected scores), a list with
Weighted and Observed components.}
\item{LFD}{Latent Field Distribution.}
\item{LCD}{Latent Class Distribution.}
\item{FieldMembership}{Field membership probability matrix.}
\item{ClassMembership}{Class membership probability matrix.}
\item{FieldEstimated}{Estimated field assignment for each item.}
\item{ClassEstimated}{Estimated class assignment for each student.}
\item{Students}{Rank Membership Profile matrix with estimated class.}
\item{TestFitIndices}{Overall fit index for the test.}
\item{log_lik}{Log-likelihood of the model.}
\item{SOACflg}{Logical; TRUE if Strongly Ordinal Alignment Condition is satisfied.}
\item{WOACflg}{Logical; TRUE if Weakly Ordinal Alignment Condition is satisfied.}
}

For rated data, the returned list includes:
\describe{
\item{Q}{Response matrix.}
\item{U}{Binary correct/incorrect matrix.}
\item{Z}{Missing indicator matrix.}
\item{testlength}{Number of items.}
\item{nobs}{Sample size.}
\item{n_class}{Optimal number of classes.}
\item{n_field}{Optimal number of fields.}
\item{n_cycle}{Number of EM algorithm iterations.}
\item{FRP}{Field Reference Profile (BCRM), a 3D array (nfld x ncls x maxQ).}
\item{FieldFRP}{Field Reference Profile based on binary correct rates (nfld x ncls).}
\item{quasiFRP}{Item-level correct response rate per class (nitems x ncls).}
\item{FRPIndex}{Index of FRP includes the item location parameters B and Beta,
the slope parameters A and Alpha, and the monotonicity indices C and Gamma.}
\item{TRP}{Test Reference Profile.}
\item{LFD}{Latent Field Distribution.}
\item{LCD}{Latent Class Distribution.}
\item{FieldMembership}{Field membership probability matrix.}
\item{ClassMembership}{Class membership probability matrix.}
\item{FieldEstimated}{Estimated field assignment for each item.}
\item{ClassEstimated}{Estimated class assignment for each student.}
\item{Students}{Rank Membership Profile matrix with estimated class.}
\item{FieldAnalysis}{Field analysis with CRR and field memberships.}
\item{TestFitIndices}{Overall fit index for the test (binary layer, default).}
\item{TestFitIndices_nominal}{Fit indices for the nominal layer (AIC/BIC/CAIC only).}
\item{log_lik}{Log-likelihood of the binary layer model.}
\item{log_lik_nominal}{Log-likelihood of the nominal layer model.}
\item{SOACflg}{Logical; TRUE if Strongly Ordinal Alignment Condition is satisfied.}
\item{WOACflg}{Logical; TRUE if Weakly Ordinal Alignment Condition is satisfied.}
}
}
\description{
This function performs Biclustering structure learning using the Infinite Relational Model (IRM)
to automatically determine the optimal number of classes C and optimal number of
fields F. It dispatches to the appropriate method based on the data type:
binary, ordinal, or nominal. For binary data, see Section 7.8 in Shojima(2022).
For nominal data, a Dirichlet-Multinomial collapsed Gibbs sampler is used.
}
\examples{
\donttest{
# Fit a Biclustering model with automatic structure learning using IRM
# gamma_c and gamma_f are concentration parameters for the Chinese Restaurant Process
result <- Biclustering_IRM(J35S515, gamma_c = 1, gamma_f = 1, verbose = TRUE)

# Display the Bicluster Reference Matrix (BRM) as a heatmap
plot(result, type = "Array")

# Plot Field Reference Profiles (FRP) in a 3-column grid
plot(result, type = "FRP", nc = 3)
}

\donttest{
result <- Biclustering_IRM(J35S515, gamma_c = 1, gamma_f = 1, verbose = TRUE)
plot(result, type = "Array")
}
\donttest{
# Fit a nominal Biclustering IRM model
result <- Biclustering_IRM(J20S600, gamma_c = 1, gamma_f = 1, verbose = TRUE)
plot(result, type = "Array")
}
\donttest{
# Fit an ordinal Biclustering IRM model
result <- Biclustering_IRM(J35S500, gamma_c = 1, gamma_f = 1, verbose = TRUE)
plot(result, type = "Array")
}
\donttest{
# Fit a rated Biclustering IRM model
result <- Biclustering_IRM(J21S300, gamma_c = 1, gamma_f = 1, verbose = TRUE)
plot(result, type = "Array")
}
}
