% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/multiModTest.R
\name{mglm.test}
\alias{mglm.test}
\title{Modality Assessment in Multimodal Generalized Linear Models}
\usage{
mglm.test(
  X,
  y,
  mod.idx,
  family = c("gaussian", "binomial", "cox", "negative.binomial"),
  robust = c("none", "mom"),
  iter = TRUE,
  penalty = c("SCAD", "MCP", "lasso"),
  tune = c("bic", "ebic", "aic"),
  lambda = NULL,
  nlambda = 100,
  conf.level = 0.95,
  CI.type = c("two.sided", "one.sided"),
  CI = NULL,
  nboot = 200,
  nblock = 5,
  theta = NULL,
  trace = FALSE
)
}
\arguments{
\item{X}{The finite numeric \eqn{n \times p} data matrix consisting of features from all modalities.}

\item{y}{The response. For \code{family = "gaussian"} or \code{"binomial"} this is the
length-\eqn{n} vector (or one-column matrix/data frame) of finite responses; binomial responses
must contain both 0 and 1.
Negative-binomial responses must be non-negative integer counts. For \code{family = "cox"} this is a
\code{\link[survival]{Surv}} object, or equivalently an \eqn{n \times 2} matrix / data frame
whose first column is the observed time and whose second column is the event indicator.}

\item{mod.idx}{A non-empty list of disjoint column-index vectors for all modalities in the
concatenated data matrix \code{X}. Every column of \code{X} must be assigned to exactly one modality.}

\item{family}{A description of the error distribution and link function to be used in the model.
With \code{robust = "none"} the Gaussian (\code{"gaussian"}) and Binomial (\code{"binomial"})
families with canonical links and the Cox proportional hazards model (\code{"cox"}) are available.
With \code{robust = "mom"} the Gaussian (\code{"gaussian"}) and Negative-Binomial
(\code{"negative.binomial"}) families are available.}

\item{robust}{Estimator for the modality information gain. \code{"none"} (default) uses the
standard maximum-likelihood / partial-likelihood estimator with closed-form non-central
chi-square confidence intervals. \code{"mom"} uses the Median-of-Means gradient-descent
(MoM-GD) estimator, which is robust to heavy-tailed responses, with basic bootstrap
confidence intervals.}

\item{iter}{Specifies whether to perform iterative SIS. For the Cox family this toggles between
a single BIC-driven screening pass (\code{iter=FALSE}) and the full iterative (ISIS) procedure
(\code{iter=TRUE}). The default is \code{iter=TRUE}.}

\item{penalty}{Specifies the type of penalty to be used in the variable selection and
inference procedure.
Options include \code{'MCP'}, \code{'SCAD'}, and \code{'lasso'}. The default is \code{penalty='SCAD'}.}

\item{tune}{Specifies the method for selecting the optimal tuning parameters in (I)SIS and
penalized likelihood procedure. Options include \code{'bic'}, \code{'ebic'} and \code{'aic'}.
The default is \code{tune='bic'}.}

\item{lambda}{A user-specified finite, positive, strictly decreasing sequence of at least two
lambda values for penalized likelihood
procedure. By default, a sequence of values of length \code{nlambda} is automatically computed and
equally spaced on the log scale.}

\item{nlambda}{The number of lambda values, an integer of at least 2. The default is 100.}

\item{conf.level}{Confidence level, a finite number strictly between 0 and 1. The default is
\code{conf.level=0.95}.}

\item{CI.type}{A string specifying the type of the confidence interval. Options include
\code{'two.sided'} and \code{'one.sided'}. The default is \code{CI.type='two.sided'}.}

\item{CI}{Logical; whether to compute confidence intervals. When \code{robust = "none"} the
default is \code{TRUE} (closed-form non-central chi-square intervals). When
\code{robust = "mom"} the default is \code{FALSE}; set \code{CI = TRUE} to run the basic
bootstrap. If \code{CI = FALSE}, only point estimates are returned (CI bounds are \code{NA}).}

\item{nboot}{Number of bootstrap resamples (at least 2) used for the MoM basic bootstrap confidence interval
(used only when \code{robust = "mom"} and \code{CI = TRUE}). The default is 200.}

\item{nblock}{Number of Median-of-Means blocks used by the MoM-GD estimator (used only when
\code{robust = "mom"}). Must be an integer between 1 and \code{nrow(X)}. The rows of \code{X}
are partitioned into \code{nblock} contiguous,
near-equal blocks. The default is 5.}

\item{theta}{Negative-Binomial dispersion parameter (used only when
\code{family = "negative.binomial"}), a finite positive number treated as fixed in the MoM fit. If \code{NULL}
(default), it is estimated once from the screened design.}

\item{trace}{Specifies whether to print out logs of iterations in SIS procedure. The default is
\code{trace=FALSE}.}
}
\value{
An object with S3 class "mglm.test" containing:
\item{sel.idx}{ List of indices of selected features by (I)SIS in each modality.}
\item{num.nonzeros}{Number of selected features by (I)SIS in each modality.}
\item{ERE}{Point estimation of ERE for each modality.}
\item{ERE.CI.L}{Lower bound of the confidence interval of ERE for each modality}
\item{ERE.CI.U}{Upper bound of the confidence interval of ERE for each modality}
\item{R2}{Point estimate of pseudo-\eqn{R^2} for each modality.}
\item{R2.CI.L}{Lower bound of the confidence interval of pseudo-\eqn{R^2} for each modality}
\item{R2.CI.U}{Upper bound of the confidence interval of pseudo-\eqn{R^2} for each modality}
\item{conf.level}{ Level of confidence intervals.}
}
\description{
Provides statistical inference for modality-specific information gain in
multimodal GLMs. Estimates ERE and pseudo-\eqn{R^2} with confidence intervals using
Sure Independence Screening for variable selection and penalized likelihood for inference.
}
\examples{
## Example 1: Linear model
data(data_linear_model)
X <- data_linear_model$X
y <- data_linear_model$y
mod.idx <- data_linear_model$mod.idx
test <- mglm.test(X = X, y = y, mod.idx = mod.idx, family = "gaussian",
               iter = TRUE, penalty = "SCAD", tune = "bic",
               conf.level = 0.95, CI.type = "one.sided")
summary(test)


## Example 2: Logistic regression
data(data_logistic_model)
X <- data_logistic_model$X
y <- data_logistic_model$y
mod.idx <- data_logistic_model$mod.idx
test <- mglm.test(X = X, y = y, mod.idx = mod.idx, family = "binomial",
               iter = TRUE, penalty = "SCAD", tune = "bic",
               conf.level = 0.95, CI.type = "two.sided")
sum.test <- summary(test)


## Example 3: Cox proportional hazards model
\donttest{
data(data_cox_model)
X <- data_cox_model$X
y <- data_cox_model$y          # two-column matrix: (time, status)
mod.idx <- data_cox_model$mod.idx
test <- mglm.test(X = X, y = y, mod.idx = mod.idx, family = "cox",
               iter = TRUE, penalty = "SCAD", tune = "ebic",
               conf.level = 0.95, CI.type = "two.sided")
summary(test)
}


## Example 4: Robust (MoM) estimation under heavy-tailed responses
data(data_nb_model)
X <- data_nb_model$X
y <- data_nb_model$y
mod.idx <- data_nb_model$mod.idx
## Point estimates only (CI = FALSE is the default when robust = "mom"):
test <- mglm.test(X = X, y = y, mod.idx = mod.idx,
               family = "negative.binomial", robust = "mom",
               iter = FALSE, penalty = "SCAD", tune = "bic",
               nblock = 5, theta = data_nb_model$theta)
summary(test)


}
