PhiSpace annotates a query dataset or a list of query datasets, given an annotated bulk or single-cell RNA-seq references. PhiSpace can simultaneously model multiple layers of cell phenotypes, e.g. cell type and disease condtion.
PhiSpace(
reference,
query,
phenotypes = NULL,
response = NULL,
refAssay = "rank",
queryAssay = NULL,
regMethod = c("PLS", "PCA"),
reducedDimName = "PhiSpace",
ncomp = NULL,
nfeat = NULL,
selectedFeat = NULL,
center = TRUE,
scale = FALSE,
DRinfo = FALSE,
storeUnNorm = FALSE,
updateRef = FALSE,
cellTypeThreshold = NULL,
fallback = c("none", "scoreCells"),
fallback_min_classes = 2,
fallback_score = c("signature", "correlation")
)The references. A SingleCellExperiment (SCE) object, a PhiSpaceModel from
trainPhiSpace(), or a list of either (models and SCE objects can be mixed). Each SCE must contain an
assay named by refAssay. A model is applied as it is: the training arguments (phenotypes,
response, refAssay, regMethod, ncomp, nfeat, selectedFeat, center, scale, DRinfo,
cellTypeThreshold and the fallback arguments) are used only for SCE references. If the queries lack
some model genes, the model is restricted to the genes shared by all queries, as described in
predict.PhiSpaceModel().
The queries. An SCE object or a list of SCE object. Each must contain an assay named by queryAssay.
Which phenotypes (e.g. "cell type") to predict. If NULL, then have to specify response.
Named matrix. Rows correpond to cells (columns) in reference; columns correspond to phenotypes. If not NULL, then will override phenotypes.
Character. Which assay in reference to use to train PhiSpace.
Character. Which assay in query to use to predict. If NULL, refAssay for an SCE
reference and the model's training assay for a PhiSpaceModel.
Character. Regression method: one of "PLS" and "PCA".
Name of reducedDim layer to store PhiSpace scores, i.e. PhiSpace scores will be stored in reducedDim(query, reducedDimName); default is "PhiSpace".
Integer. Number of components. If NULL, will use the default, i.e. same as the total number of phenotypes.
Integer. Number of features to choose to predict each phenotype. See details.
Character. Alternatively, can provide a vector of pre-selected features.
Logic. Whether to perform centering. See details.
Logic. Whether to perform scaling. See details.
Logic. Whether to return dimension reduction information from PCA or PLS. By default disabled to save memory.
Store unnormalised raw PhiSpace scores or not. Default is FALSE.
Update reference (store reference PhiSpace scores in reference sce object) or not.
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 for references with too few classes. "none" preserves
standard PhiSpace behaviour. "scoreCells" calls scoreCells() through PhiSpaceR_1ref() 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".
If updateRef = FALSE (default): An updated query SCE object with PhiSpace annotation results stored in reducedDim slot "PhiSpace";
If updateRef = TRUE: A list of updated reference and query SCE objects with PhiSpace annotation results stored in reducedDim slot "PhiSpace".
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
Mao J., Choi J. and Lê Cao K.-A. (2026). Φ-Space ST: a platform-agnostic method to identify cell states in spatial transcriptomics studies. Cell Reports Methods 6(8), 101483. doi:10.1016/j.crmeth.2026.101483
# Simulated reference and query; Cell_Cycle is the reference phenotype.
set.seed(1)
ref <- logNormTransf(scuttle::mockSCE(ncells = 200, ngenes = 300))
query <- logNormTransf(scuttle::mockSCE(ncells = 100, ngenes = 300))
query <- PhiSpace(ref, query, phenotypes = "Cell_Cycle",
refAssay = "logcounts", ncomp = 3)
head(reducedDim(query, "PhiSpace"))