% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/jointDimReduction.R
\name{jointDimReduction}
\alias{jointDimReduction}
\title{Joint Dimensionality Reduction via Sparse Multi-Block PLS-DA}
\usage{
jointDimReduction(
  mae,
  outcome,
  n_components = 2L,
  n_features_host = 50L,
  n_features_mb = 20L,
  design_off_diag = 0.1,
  host_assay = "voom",
  mb_assay = "CLR",
  min_variance = 0
)
}
\arguments{
\item{mae}{A \code{MultiAssayExperiment} from \code{\link{matchSamples}}
containing \code{"host"} and \code{"microbiome"} experiments.}

\item{outcome}{A \code{character} or \code{factor} vector of outcome
labels, one per sample (in the same order as \code{colnames(mae)}).
Must have exactly 2 or more levels.}

\item{n_components}{An \code{integer(1)} number of latent components
to extract. Default: \code{2}.}

\item{n_features_host}{An \code{integer(1)} number of host genes to
retain per component (sparse selection). Default: \code{50}.}

\item{n_features_mb}{An \code{integer(1)} number of microbial taxa to
retain per component. Default: \code{20}.}

\item{design_off_diag}{A \code{numeric(1)} in \code{[0, 1]} controlling
the off-diagonal entries of the DIABLO design matrix. Higher values
emphasize cross-block correlation; lower values prioritize outcome
discrimination. Default: \code{0.1}.}

\item{host_assay}{A \code{character(1)} name of the assay in the host
\code{SummarizedExperiment} to use as input. Default: \code{"voom"}.}

\item{mb_assay}{A \code{character(1)} name of the assay in the
microbiome \code{SummarizedExperiment} to use as input. Default:
\code{"CLR"}.}

\item{min_variance}{A \code{numeric(1)} minimum variance (as a fraction
of total row variance) for genes/taxa to be retained before DIABLO.
Default: \code{0} (no filtering).}
}
\value{
A named \code{list} with elements:
  \describe{
    \item{\code{scores}}{A \code{matrix} (samples x components) of
      integrated sample scores (from the host block variate).}
    \item{\code{host_loadings}}{A \code{matrix} (genes x components)
      of sparse host feature loadings.}
    \item{\code{mb_loadings}}{A \code{matrix} (taxa x components)
      of sparse microbiome feature loadings.}
    \item{\code{explained_variance}}{A named \code{numeric} vector of
      explained variance per component.}
    \item{\code{diablo_object}}{The full DIABLO result object from
      \code{mixOmics::block.splsda}.}
    \item{\code{outcome}}{The outcome factor used.}
  }
}
\description{
Performs joint dimensionality reduction across host transcriptomics
and gut microbiome data using DIABLO (Data Integration Analysis for
Biomarker discovery using Latent cOmponents), a sparse multi-block
PLS-DA implemented in \code{mixOmics}. DIABLO simultaneously identifies
correlated features across data blocks while discriminating between
outcome groups, enforcing sparsity so only the most informative
features contribute to each latent component.
}
\details{
The DIABLO model is fitted as:
\deqn{\max \, \text{Cov}(t_\text{host}, t_\text{mb})}
subject to \eqn{||w_\text{host}||_1 \leq \lambda_\text{host}} and
\eqn{||w_\text{mb}||_1 \leq \lambda_\text{mb}}, where
\eqn{t} are the sample scores (variates) and \eqn{w} are the
sparse feature weights (loadings).

The number of features retained per component is controlled by
\code{n_features_host} and \code{n_features_mb}. By default, a
design matrix connecting all blocks with moderate correlation
(\code{design_off_diag = 0.1}) is used, which prioritizes outcome
discrimination over cross-block correlation.
}
\examples{
set.seed(42)
host_counts <- matrix(rpois(500 * 20, 100), nrow = 500, ncol = 20,
    dimnames = list(paste0("Gene", 1:500), paste0("S", 1:20)))
host_counts[1:20, 11:20] <- host_counts[1:20, 11:20] * 5L
mb_counts <- matrix(rpois(60 * 20, 40), nrow = 60, ncol = 20,
    dimnames = list(paste0("Taxon", 1:60), paste0("S", 1:20)))

host_se <- loadHostData(host_counts)
mb_se   <- loadMicrobiomeData(mb_counts)
mae     <- matchSamples(host_se, mb_se)

outcome <- rep(c("ctrl", "treat"), each = 10)
dr_res  <- jointDimReduction(mae, outcome = outcome,
                              n_components = 2,
                              n_features_host = 30,
                              n_features_mb   = 15)
dim(dr_res$scores)
head(dr_res$explained_variance)

}
\seealso{
\code{\link{biomarkerDiscovery}}, \code{\link{plotIntegration}},
  \code{\link{MultiOmicsBridgeAnalysis}}
}
