% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/QC.R
\name{computeQScore}
\alias{computeQScore}
\title{computeQScore}
\usage{
computeQScore(spe, bestLambda = NULL, modelFormula = NULL, verbose = FALSE)
}
\arguments{
\item{spe}{A `SpatialExperiment` object with spatial omics data.}

\item{bestLambda}{the best lambda typically computed using `computeLambda`.}

\item{modelFormula}{A one-sided formula or character string. If `NULL`, the
default formula is generated from available supported metrics and their
outliers. If supplied, its supported terms and interactions are fitted
without rewriting. See Details.}

\item{verbose}{logical for having a verbose output. Default is FALSE.}
}
\value{
The `SpatialExperiment` object with added Quality Score in `colData`.
}
\description{
Computes Quality Score (QS) and automatically define weights of the QS model
terms through glm training. This function computes QS with a formula
defined on the metrics "log2SignalDensity", "Area_um",
"log2AspectRatio", "log2Ctrl_total_ratio", as computed from
the `spatialPerCellQC` function.
It automatically computes the number of outliers for each available
metric, which are needed for the glm training.
See Details for further information.
}
\details{
For all the technologies, the QS formula can contain
only the following terms at most:

Quality Score ~ signal density - size - border effect - background signal 

Where signal density is the total counts/protein intensities-to-size ratio, 
border effect is represented by the aspect ratio (i.e. width/height of the cell) 
and is considered only for cells with a distance from the FOV border less than 
50 px and only for CosMx datasets. Background signal is represented by the ratio 
of control probe counts to total counts (protein intensities) and cell size is 
the area for CosMx and Xenium, while it is the volume for Merfish.
For each couple of variables interaction terms are computed.

Note that the function is responsible for automatically including/excluding
metrics in the formula based on their availability in the `colData` of the
`SpatialExperiment` object.

For the default formula, inclusion of metrics also depends on the number of
available outliers. If the number of outliers for a metric is less than
0.1\% of the dataset, that metric is excluded from the default QS formula.

- Model fitting: ridge (L2) logistic regression is fitted (via `glmnet`) on
the balanced training set. The function uses `trainModel()` for fitting
and `computeLambda()` to select lambda unless `bestLambda` is supplied.

- Lambda details: because of the randomness in the training set selection,
results may vary. The easiest way to ensure reproducibility is to let lambda 
be computed internally, just set a seed with `set.seed()` before running 
`computeQScore`. Otherwise, a fixed value of lambda previously computed with 
`computeLambda` preceeded by `computeTrainDF` and `getModelFormula` can be set.

- Model formula details: the most complete default formula is:
`~(log2SignalDensity + Area_um + I(abs(log2AspectRatio) * as.numeric(dist_border < 50)) + log2Ctrl_total_ratio)^2`.
A user-supplied formula is fitted as supplied: additive structures, selected
interactions, `:` and `*` are preserved. The formula must include
`log2SignalDensity` and may use any subset of the other supported predictors:
`Area_um`,
`log2AspectRatio`, and `log2Ctrl_total_ratio`. Arbitrary predictors and
transformations are rejected. The supported CosMx-only border expression is
`I(abs(log2AspectRatio) * as.numeric(dist_border < 50))`.

When a custom `modelFormula` is supplied, the supported base QC metrics in
that formula are also used to compute outliers, define good and bad training
cells, and construct `QScore_train`. Interactions do not create additional
training metrics. In the supported border expression, `dist_border` is an
auxiliary variable and `log2AspectRatio` is the corresponding training QC
metric. Supported metrics omitted from the custom formula do not contribute
to training-label construction. When `modelFormula=NULL`, the established
default metric-selection and training-label workflow is unchanged.

The computed model output is stored in `metadata(spe)$QScore_model`.
For inspection and model coefficient transfer between datasets
see also \code{\link{applyQScoreModel}}. However, transferring models between
datasets is not recommended. As described in the paper, QS model training is
dataset-specific and does not generalize well across datasets. Moreover,
this step is computationally efficient. Please, refer to the paper for  
details on scalability and coefficient transfer.
}
\examples{
example(spatialPerCellQC)
set.seed(1998)
spe <- computeQScore(spe)
summary(spe$QScore)
}
