Core single-reference implementation for PhiSpace continuous phenotyping. Given an annotated reference
dataset and one or more query datasets, this function builds a PLS or PCA regression model from the
reference and projects the query onto the learned phenotype space. Both raw and normalised PhiSpace
scores are returned. For a higher-level wrapper that handles multiple references, see PhiSpace().
PhiSpaceR_1ref(
reference,
query,
phenotypes = NULL,
response = NULL,
refAssay = "log1p",
queryAssay = NULL,
regMethod = c("PLS", "PCA"),
ncomp = NULL,
nfeat = NULL,
selectedFeat = NULL,
center = TRUE,
scale = FALSE,
DRinfo = FALSE,
cellTypeThreshold = NULL,
fallback = c("none", "scoreCells"),
fallback_min_classes = 2,
fallback_score = c("signature", "correlation")
)A SingleCellExperiment (SCE) object. The annotated reference dataset. Must contain
an assay named by refAssay.
An SCE object or a list of SCE objects. The query dataset(s) to annotate.
Each must contain an assay named by queryAssay.
Character vector. Column name(s) in colData(reference) specifying which
phenotypes (e.g. cell type, disease condition) to predict. If NULL, response must be provided.
Currently only supports categorical phenotypes; for continuous phenotypes, specify response directly.
Named matrix. Rows correspond to cells (columns) in reference; columns correspond
to phenotypes. If not NULL, overrides phenotypes. Can contain continuous values such as age or BMI.
Character. Name of the assay in reference to use for model training (default: "log1p").
Character. Name of the assay in query to use for prediction. If NULL (default),
uses the same value as refAssay.
Character. Regression method: one of "PLS" (partial least squares, default) or
"PCA" (principal component regression).
Integer. Number of PLS/PCA components. If NULL (default), set to the total number
of phenotype levels.
Integer. Number of top-ranked features to select per phenotype for model fitting. If NULL
(default), all features are used. See Details.
Character vector. A set of pre-selected feature names to use for model fitting. If
provided, overrides nfeat.
Logical. Whether to center the feature matrix before regression (default: TRUE). See Details.
Logical. Whether to scale the feature matrix before regression (default: FALSE). See Details.
Logical. Whether to return dimension reduction information from PCA or PLS.
Disable to save memory (default: FALSE).
Integer or NULL. If a positive integer, cell types with fewer than this many
cells in the reference will be removed before model fitting. Only used when phenotypes is provided.
Default is NULL (no filtering).
Character. Optional fallback method for references with too few classes. "none"
preserves the standard PhiSpace behaviour. "scoreCells" uses scoreCells() when the number of
classes is less than fallback_min_classes.
Integer. Minimum number of classes required before fitting the standard
PhiSpace model when fallback = "scoreCells".
Character. Which scoreCells() output to use as the fallback PhiSpace score:
"signature" or "correlation".
A list with the following components:
Integer. Number of components used. NA when the scoreCells fallback is used.
Matrix. Feature importance scores (regression coefficients at the final component).
NULL when the scoreCells fallback is used.
Data frame mapping phenotype labels to their categories, or NULL if response
was provided directly.
Character vector. Features used in the final model. With the scoreCells
fallback, the union of the signature features, or all centroid features if there are no
signatures.
Matrix. Raw (unnormalised) predicted scores for the reference cells.
NULL when the scoreCells fallback is used.
Matrix. Normalised predicted scores for the reference cells (via normPhiScores()).
NULL when the scoreCells fallback is used.
Matrix or list of matrices. Raw (unnormalised) PhiSpace scores for the query dataset(s). A single matrix if one query was provided; a list of matrices if multiple queries.
Matrix or list of matrices. Normalised PhiSpace scores for the query dataset(s)
(via normPhiScores()). Same structure as PhiSpaceScore.
Logical. Whether centering was applied. NA when the scoreCells fallback is used.
Logical. Whether scaling was applied. NA when the scoreCells fallback is used.
List. Internal model object from SuperPC(), containing regression results and
preprocessing parameters needed for prediction. NULL when the scoreCells fallback is used.
A PhiSpaceModel (see trainPhiSpace()) trained on the genes shared with the
queries. It can be saved and used with predict.PhiSpaceModel(). Absent when the
scoreCells fallback is used.
List. Present only when the scoreCells fallback is used. It records the method,
the score type (fallback_score), the phenotype column and its number of classes,
fallback_min_classes, and the scoreCells() metadata.
Parameter tuning By default, PhiSpace takes ncomp equal to the total number of phenotypes.
For example, if there are 20 cell types and 5 sample sources (e.g. in vivo and in vitro) defined
in the reference, ncomp will be set to be 25. By default, PhiSpace doesn't do any feature selection.
However, feature selection is very straightforward in PhiSpace. The partial least squares model
automatically rank all features according to their contribution to predicting each phenotype. For
example, if there are 25 phenotypes then PLS will return 25 rankings of all features. Based on this,
customised feature selection can be done in two ways. The user either specify nfeat, i.e. the number
of features (or markers) used to predict each phenotype; or specify selectedFeat, i.e. a subset of
features used to predict all phenotypes (e.g. highly variable genes). If nfeat is provided, then
selectedFeat will be automatically defined as the union of the nfeat markers of all phenotypes.
Center and scale By default, PhiSpace only center the data but do not scale. This is because we often use more features than standard single-cell pipelines (e.g. Seurat selects 2,000 highly variable genes) for a better prediction. This means that we might have included genes with small variance and scaling would greatly inflate the expression levels of these genes.
Mao J., Deng Y. and Lê Cao K.-A. (2025). Φ-Space: continuous phenotyping of single-cell multi-omics data. Genome Biology 26, 323. doi:10.1186/s13059-025-03755-8
PhiSpace() for the main user-facing wrapper that handles multiple references,
normPhiScores() for score normalisation, tunePhiSpace() for parameter tuning.
set.seed(1)
ref <- logNormTransf(scuttle::mockSCE(ncells = 200, ngenes = 300))
query <- logNormTransf(scuttle::mockSCE(ncells = 100, ngenes = 300))
res <- PhiSpaceR_1ref(ref, query, phenotypes = "Cell_Cycle",
refAssay = "logcounts", ncomp = 3)
names(res)
head(res$PhiSpaceNorm)