% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/svaEnmix.R
\name{svaEnmix}
\alias{svaEnmix}
\title{Estimate surrogate variables from ENmix control probes}
\usage{
svaEnmix(
  phenoFile = "data/preprocessingMinfiEwasWater/phenoLC.csv",
  rgsetData = "rData/preprocessingMinfiEwasWater/objects/RGSet.RData",
  sepType = NULL,
  outputLogs = "logs",
  nSamples = NA,
  SampleID = "Sample_Name",
  arrayType = "IlluminaHumanMethylationEPICv2",
  annotationVersion = "20a1.hg38",
  SentrixIDColumn = "Sentrix_ID",
  SentrixPositionColumn = "Sentrix_Position",
  ctrlSvaPercVar = 0.9,
  ctrlSvaFlag = 1,
  scriptLabel = "svaEnmix",
  tiffWidth = 2000,
  tiffHeight = 1000,
  tiffRes = 150,
  figureBaseDir = "figures",
  dataBaseDir = "data",
  rBaseDir = "rData",
  display = FALSE,
  verbose = FALSE,
  logs = FALSE,
  saveOutputs = FALSE
)
}
\arguments{
\item{phenoFile}{Character. Path to the phenotype file with cell-composition
data. When \code{saveOutputs = TRUE}, the validated PC columns are appended to
this file using a rollback-safe replacement.}

\item{rgsetData}{Character. Path to a saved \code{RGChannelSet} object. Both
\code{.RData} and \code{.rds} files are supported.}

\item{sepType}{Character or \code{NULL}. Field separator used in \code{phenoFile}. Use
\code{NULL} for a comma-separated file, \code{'\\\\t'} for a tab-delimited file, or
another separator accepted by \code{utils::read.csv()}.}

\item{outputLogs}{Character. Directory used for log files when \code{logs = TRUE}.}

\item{nSamples}{Integer or \code{NA}. Number of rows to keep from the phenotype
table. Use \code{NA} to keep all samples.}

\item{SampleID}{Character. Name of the phenotype column containing sample
identifiers.}

\item{arrayType}{Character. Illumina array identifier assigned to
\code{Biobase::annotation(RGSet)}.}

\item{annotationVersion}{Character. Annotation build assigned to
\code{Biobase::annotation(RGSet)}.}

\item{SentrixIDColumn}{Character. Name of the chip identifier column in the
phenotype data.}

\item{SentrixPositionColumn}{Character. Name of the chip position column in
the phenotype data.}

\item{ctrlSvaPercVar}{Numeric. Proportion of control-probe variance explained
when running \code{ENmix::ctrlsva()}.}

\item{ctrlSvaFlag}{Integer. Control-probe flag passed to \code{ENmix::ctrlsva()}.}

\item{scriptLabel}{Character. Label used to name output folders when
\code{saveOutputs = TRUE}.}

\item{tiffWidth}{Integer. Width of saved TIFF plots in pixels.}

\item{tiffHeight}{Integer. Height of saved TIFF plots in pixels.}

\item{tiffRes}{Integer. Resolution in DPI for saved TIFF plots.}

\item{figureBaseDir}{Character. Base directory used for saved figure outputs
when \code{saveOutputs = TRUE}.}

\item{dataBaseDir}{Character. Base directory used for saved CSV and text
outputs when \code{saveOutputs = TRUE}.}

\item{rBaseDir}{Character. Base directory used for saved \code{.RData} outputs
when \code{saveOutputs = TRUE}.}

\item{display}{Logical. If \code{TRUE}, draw plots on the active graphics device.}

\item{verbose}{Logical. If \code{TRUE}, emit progress messages with \code{message()}.
The default is \code{FALSE}.}

\item{logs}{Logical. If \code{TRUE}, write the same progress messages to
\code{outputLogs}. The default is \code{FALSE}.}

\item{saveOutputs}{Logical. If \code{TRUE}, write the CSV, \code{.RData}, text,
and TIFF outputs to disk. The default is \code{FALSE}.}
}
\value{
A list with class \code{'dnaEPICO_svaEnmix'}.
\describe{
\item{targets}{Phenotype table read from \code{phenoFile} after any optional row
subsetting.}
\item{RGSet}{Loaded \code{RGChannelSet} with sample names realigned to
\code{targets[[SampleID]]}.}
\item{svaData}{Object returned by \code{\link[=estimateSvaEnmixControls]{estimateSvaEnmixControls()}} containing
the surrogate-variable matrix and the control-probe settings used to
estimate it.}
\item{mergedPheno}{Phenotype table returned by \code{\link[=mergeSvaTargetsEnmix]{mergeSvaTargetsEnmix()}}
after the surrogate variables were appended as additional columns.}
\item{analysisData}{Object returned by \code{\link[=analyzeSvaEnmix]{analyzeSvaEnmix()}} containing the
surrogate-variable association models, ANOVA tables, and Sentrix metadata.}
\item{plotFiles}{Named list describing the plot file paths requested for the
SVA figures. When \code{saveOutputs = FALSE}, the entries are typically \code{NULL}.}
\item{savedFiles}{Object returned by \code{\link[=writeSvaEnmixOutputs]{writeSvaEnmixOutputs()}} when
\code{saveOutputs = TRUE}, otherwise \code{NULL}.}
\item{logFile}{Resolved path to the optional log file, or \code{NULL} when
logging was disabled.}
}
See \linkS4class{dnaEPICO_svaEnmix} for a class-level overview.
}
\description{
Read the phenotype table and a saved \code{RGChannelSet}, estimate surrogate
variables from ENmix control probes, analyze their association with Sentrix
chip and position factors, and return a structured in-memory result. CSV,
\code{.RData}, text-summary, and figure outputs are written only when
\code{saveOutputs = TRUE}.
}
\examples{
tmp <- tempdir()
stopifnot(dir.exists(tmp))

if (requireNamespace("minfiData", quietly = TRUE)) {
    ex <- dnaEPICO:::exampleMinfiBaseDataDnaEpico()
    pheno_file <- file.path(tmp, "pheno.csv")
    rgset_path <- file.path(tmp, "RGSet.RData")
    RGSet <- ex$RGSet
    utils::write.csv(ex$targets, pheno_file, row.names = FALSE)
    save(RGSet, file = rgset_path)
    sva_result <- svaEnmix(
        phenoFile = pheno_file,
        rgsetData = rgset_path,
        SampleID = "Sample_Name",
        arrayType = "IlluminaHumanMethylation450k",
        annotationVersion = "ilmn12.hg19",
        SentrixIDColumn = "Sentrix_ID",
        SentrixPositionColumn = "Sentrix_Position",
        outputLogs = file.path(tmp, "logs"),
        figureBaseDir = file.path(tmp, "figures"),
        dataBaseDir = file.path(tmp, "data"),
        rBaseDir = file.path(tmp, "rData"),
        saveOutputs = FALSE
    )
    stopifnot(inherits(sva_result, "dnaEPICO_svaEnmix"))
}

}
\seealso{
\linkS4class{dnaEPICO_svaEnmix}
}
