Package 'PhiSpace'

Description

Convert a matrix to sparse metrix.

Usage

as.sparse.matrix(X)

Arguments

Value

Sparse matrix version of X

Description

Plot formatting for presentation and publication

Usage

basicPlotFormat(
  p,
  theme_overall = "bw",
  base_size = 8,
  legend.position = "top",
  x.text.blank = FALSE,
  y.text.blank = FALSE,
  axis.title.bold = TRUE,
  legend.title.bold = TRUE,
  axis.title.x.blank = FALSE,
  axis.title.y.blank = FALSE,
  legend.title.blank = FALSE,
  legend.spacing.x = 0,
  legend.key.spacing = 0,
  legend.key.spacing.y = 0,
  legend.box.margin = 0,
  legend.box.spacing = 0,
  legend.key.size = 8
)

Arguments

Value

A ggplot2 object.

Description

A generic function to compute a correlation matrix for different input types, including matrix, data.frame and SingleCellExperiment objects.

Usage

cellTypeCorMat(input, mask = NULL, reducedDimName = "PhiSpace", groupBy = NULL)

## S4 method for signature 'matrix'
cellTypeCorMat(input, mask = NULL, reducedDimName = "PhiSpace", groupBy = NULL)

## S4 method for signature 'data.frame'
cellTypeCorMat(input, mask = NULL, reducedDimName = "PhiSpace", groupBy = NULL)

## S4 method for signature 'SingleCellExperiment'
cellTypeCorMat(input, mask = NULL, reducedDimName = "PhiSpace", groupBy = NULL)

Arguments

Details

This method calculates the correlation matrix directly for the input matrix.

This method first converts the data.frame to a matrix and then calculates the correlation matrix.

This method uses the reduced dimension "PhiSpace" of the SingleCellExperiment object to compute the correlation matrix. If "PhiSpace" is not available, an error is raised.

Value

If mask is provided, returns a list of correlation matrices (one per column of mask). Otherwise, returns a single correlation matrix.

Examples

set.seed(1)
scores <- matrix(rnorm(200), 50, 4, dimnames = list(NULL, LETTERS[1:4]))
cellTypeCorMat(scores)
# One correlation matrix per group of rows.
mask <- cbind(first = rep(c(1, 0), each = 25), second = rep(c(0, 1), each = 25))
names(cellTypeCorMat(scores, mask = mask))

Description

Calculate classification errors.

Usage

classErr(classQuery, classOriginal, labPerSample = NULL)

Arguments

Value

A list containing:

Description

Center log ratio normalisation

Usage

CLRnorm(sce, assayName = "counts", targetAssay = "data", offset = 1)

Arguments

Value

SCE object

Examples

sce <- scuttle::mockSCE(ncells = 20, ngenes = 10)
sce <- CLRnorm(sce)
assay(sce, "data")[1:3, 1:3]

Description

Performs k-means clustering on principal components derived from PhiSpace scores or any other matrix-like data. This is useful for identifying spatial niches or clusters based on cell state compositions or gene expression patterns.

Usage

clusterPhiSpace(
  x,
  k = NULL,
  k_range = NULL,
  select_k_method = c("silhouette", "elbow"),
  ncomp = NULL,
  reducedDimName = "PhiSpace",
  use_assay = NULL,
  nstart = 20,
  iter.max = 500,
  algorithm = c("Lloyd", "Hartigan-Wong", "MacQueen", "Forgy"),
  center = TRUE,
  scale = FALSE,
  seed = NULL,
  silhouette_max_cells = Inf,
  return_pca = TRUE,
  store_in_colData = FALSE,
  cluster_name = "PhiClust"
)

Arguments

Details

This function implements a common workflow for spatial clustering:

1. Extract data (from reducedDim, assay, or use directly if matrix)

2. Perform PCA to reduce dimensionality

3. Select top principal components

4. Apply k-means clustering

The function can either:

• Use a fixed k value (specify k parameter)

• Automatically select k from a range (specify k_range parameter)

When k_range is provided, the function tests all k values in the range and selects the optimal k using either:

• Silhouette method (default): Maximizes average silhouette width

• Elbow method: Identifies elbow point in total within-cluster sum of squares

Value

A list with class "PhiSpaceClustering" containing:

Input Types

The function accepts multiple input types:

• SingleCellExperiment/SpatialExperiment: Uses reducedDim (default) or assay

• Matrix: Standard R matrix with observations in rows

• Sparse matrix: dgCMatrix or similar sparse formats

• Data frame: Coerced to matrix

PCA Parameters

The number of PCs to use affects clustering resolution:

• Fewer PCs (e.g., 10-15): Broader, more general clusters

• More PCs (e.g., 30-50): Finer, more specific clusters

• Default (30): Good balance for most applications

K-means Algorithm

• Lloyd (default): Standard algorithm, good balance of speed and quality

• Hartigan-Wong: Often better results but slower

• MacQueen: Faster but may converge to local optima

• Forgy: Similar to Lloyd

Examples

set.seed(1)
scores <- matrix(rnorm(150 * 5), 150, 5, dimnames = list(NULL, LETTERS[1:5]))
scores[1:50, 1] <- scores[1:50, 1] + 3
scores[51:100, 2] <- scores[51:100, 2] + 3
res <- clusterPhiSpace(scores, k = 3, seed = 1)
res
table(res$clusters)
# Choose k from a range with the silhouette method.
res <- clusterPhiSpace(scores, k_range = 2:5, seed = 1)
summary(res)
plot(res, type = "silhouette")

Description

Convert discrete annotations to dummy variable matrices.

Usage

codeY(sce, phenotypes, method = c("-1,1", "0,1"))

Arguments

Value

Examples

sce <- scuttle::mockSCE(ncells = 20, ngenes = 10)
YY <- codeY(sce, phenotypes = c("Cell_Cycle", "Treatment"))
head(YY)

Description

Convert discrete annotations to dummy variable matrices.

Usage

codeY_vec(vec, rowNames = NULL, method = c("-1,1", "0,1"))

Arguments

Value

Examples

codeY_vec(c("B", "T", "T", "NK"), rowNames = paste0("cell", 1:4))
codeY_vec(c("B", "T", "T", "NK"), method = "0,1")

Description

Compute kernel weights based on distances

Usage

compute_kernel_weights(distances, kernel, sigma = NULL)

Arguments

Value

Matrix of weights

Description

Compute UMAP.

Usage

computeUMAP(
  dat,
  computPC = TRUE,
  ncomp = 30,
  center = TRUE,
  scale = FALSE,
  config = NULL
)

Arguments

Value

UMAP coordinates.

Examples

set.seed(1)
X <- matrix(rnorm(100 * 10), 100, 10, dimnames = list(paste0("cell", 1:100), NULL))
emb <- computeUMAP(X, ncomp = 5)
dim(emb)

Description

Tune ncomp using cross-validation.

Usage

CVTune_ncomp(
  reference,
  assayName = "logcounts",
  phenotypes = NULL,
  YY = NULL,
  center = TRUE,
  scale = FALSE,
  ncompLimits = c(1, 100),
  gridSize = 20,
  ncompGrid = NULL,
  selectedFeat = NULL,
  Kfolds = 5,
  regMethod = "PCA",
  labelCode = "-1,1",
  Ncores = 1,
  seed = 5202056,
  ncomp = NULL
)

Arguments

Value

A list.

Description

Tune nfeat using cross-validation.

Usage

CVTune_nfeat(
  reference,
  assayName = "logcounts",
  phenotypes = NULL,
  YY = NULL,
  ncomp = NULL,
  impScores = NULL,
  center = TRUE,
  scale = FALSE,
  nfeatLimits = c(10, 15000),
  gridSize = 30,
  nfeatV = NULL,
  Kfolds = 5,
  regMethod = "PCA",
  labelCode = "-1,1",
  seed = 5202056,
  Ncores = 1,
  nfeat = NULL
)

Arguments

Value

A list.

Description

Double center a matrix by column and row means, resulting in a new matrix with zero row and column means.

Usage

doubleCent(X)

Arguments

Value

A double-centred matrix.

Examples

X <- matrix(1:12, 3, 4)
dc <- doubleCent(X)
round(rowMeans(dc), 10)
round(colMeans(dc), 10)

Description

Identifies spatial niches by performing k-means clustering on PhiSpace cell type scores. Optionally performs PCA before clustering to reduce dimensionality and improve clustering performance. Can test multiple numbers of niches and return all results for comparison.

Usage

findNiches(
  spe,
  reducedDimName = "PhiSpace",
  n_niches,
  use_pca = TRUE,
  ncomp = NULL,
  center = TRUE,
  scale = FALSE,
  kmeans_iter = 500L,
  kmeans_nstart = 20L,
  kmeans_algorithm = "Lloyd",
  seed = 94863,
  store_pca = FALSE,
  pca_name = "PhiSpace_PCA",
  verbose = TRUE
)

Arguments

Details

This function identifies spatial niches by clustering cells/spots based on their PhiSpace cell type composition scores. The workflow consists of:

1. Extract PhiSpace scores from the specified reducedDim

2. Optionally perform PCA to reduce dimensionality and focus on major patterns

3. Apply k-means clustering to identify niches (for each k in n_niches)

4. Store niche assignments in colData

PCA is recommended when you have many cell types (>20) as it can improve clustering by focusing on the main axes of variation in cell type composition.

When multiple values of n_niches are provided, the function will test each one and store all results, allowing you to compare different numbers of niches and choose the most appropriate one for your analysis.

Value

The input object with niche assignments added to colData. If a single n_niches is provided, results are stored as "spatial_niches". If multiple n_niches are provided, results are stored as "spatial_niches_k7", "spatial_niches_k8", etc. If store_pca = TRUE, PCA results are also stored in reducedDims.

Examples

set.seed(1)
ref <- logNormTransf(scuttle::mockSCE(ncells = 200, ngenes = 300))
query <- logNormTransf(scuttle::mockSCE(ncells = 100, ngenes = 300))
spe <- SpatialExperiment::SpatialExperiment(
  assays = list(logcounts = logcounts(query)),
  spatialCoords = cbind(x = runif(100), y = runif(100))
)
spe <- PhiSpace(ref, spe, phenotypes = "Cell_Cycle", refAssay = "logcounts",
                ncomp = 3)
spe <- findNiches(spe, n_niches = 3, ncomp = 3, verbose = FALSE)
table(spe$spatial_niches)

Description

Compute different errors for cross-validation.

Usage

getErr(
  ncompGrid,
  XXtrain,
  YYtrain,
  XXtest,
  YYtest,
  center = TRUE,
  scale = FALSE,
  selectedFeat = NULL,
  regMethod = "PLS",
  assayName = "rank",
  loss = c("Frobenius", "exponential")
)

Arguments

Value

A list

Description

Calculate errors for the cross-validation for selecting nfeat.

Usage

getErr_nfeat(
  nfeatV,
  impScores,
  ncomp,
  XXtrain,
  YYtrain,
  XXtest,
  YYtest,
  center = TRUE,
  scale = FALSE,
  regMethod = "PLS",
  assayName = "logcounts",
  loss = c("Frobenius", "exponential")
)

Arguments

Value

A list.

Description

Gives each row of a score matrix the name of the column with the highest score, or the names of the labPerSample highest-scoring columns. This function was called getClass() before PhiSpace 0.99.0; it was renamed because that name masked methods::getClass().

Usage

getLabels(X, labPerSample = NULL)

Arguments

Value

With one label per row, a character vector of column names, one per row of X. With more, a character matrix with one row per row of X, labels in decreasing order of score.

Examples

set.seed(1)
scores <- matrix(rnorm(20), 5, 4, dimnames = list(NULL, LETTERS[1:4]))
getLabels(scores)
getLabels(scores, labPerSample = 2)

Description

getPC() uses irlba's partial SVD. When ncomp is at least half of the smaller dimension of X, where irlba can be inaccurate, or when the smaller dimension is at most 100, it uses a full SVD of a dense copy of X instead. On such small matrices irlba may not converge, and its result then depends on its random start; the full SVD does not.

Usage

getPC(X, ncomp, center = TRUE, scale = FALSE, sparse = FALSE)

Arguments

Value

A list containing

Examples

set.seed(1)
X <- matrix(rnorm(100 * 10), 100, 10)
pc <- getPC(X, ncomp = 3)
dim(pc$scores)
pc$props

Description

Keep common genes of two SingleCellExperiment objects.

Usage

KeepCommonGenes(reference, query, dots2hyphen = FALSE)

Arguments

Value

A list containing updated SingleCellExperiment obejcts with matching features.

Examples

ref <- scuttle::mockSCE(ncells = 20, ngenes = 10)
query <- scuttle::mockSCE(ncells = 20, ngenes = 10)
query <- query[3:10, ]
res <- KeepCommonGenes(ref, query)
nrow(res$reference)
nrow(res$query)

Description

Divides the counts of each cell by its size factor and takes $\log_2(x + 1)$. By default the size factors are the library sizes, centred to mean 1. This gives the same values as the defaults of scuttle::logNormCounts(), which Bioconductor 3.24 deprecates.

Usage

logNormTransf(
  sce,
  assayName = "counts",
  targetAssay = "logcounts",
  sizeFactors = NULL
)

Arguments

Value

sce with the log-normalised assay targetAssay and the size factors, centred to mean 1, in colData(sce)$sizeFactor. A sparse or DelayedArray count matrix gives a dgCMatrix, a dense one a dense matrix.

See Also

scranTransf() for pooled size factors, logTransf() for log1p() of counts or relative counts.

Examples

sce <- scuttle::mockSCE(ncells = 20, ngenes = 10)
sce <- logNormTransf(sce)
assay(sce, "logcounts")[1:3, 1:3]

Description

Do log1p normalisation by default.

Usage

logTransf(
  sce,
  scalFactor = 10000,
  assayName = "counts",
  targetAssay = "log1p",
  use_log1p = TRUE,
  sparse = TRUE
)

Arguments

Value

A SingleCellExperiment object containing a new assay after relative counts normalisation.

Examples

sce <- scuttle::mockSCE(ncells = 20, ngenes = 10)
sce <- logTransf(sce, targetAssay = "log1p")
assay(sce, "log1p")[1:3, 1:3]

Description

Simplified version of pls::mvr, using computationally faster versions of PCA and PLS.

Usage

mvr(
  X,
  Y,
  ncomp,
  method = c("PCA", "PLS"),
  center = TRUE,
  sparse = FALSE,
  scale = FALSE,
  DRinfo = FALSE,
  keepComps = seq_len(ncomp)
)

Arguments

Details

A sparse X (for example a dgCMatrix) stays sparse: centring and scaling are applied implicitly, without a dense copy of X. PLS uses the kernel algorithm of pls::kernelpls.fit.

Value

A list containing

Examples

set.seed(1)
X <- matrix(rnorm(100 * 20), 100, 20)
Y <- X[, 1:3] %*% matrix(rnorm(9), 3, 3) + matrix(rnorm(300, sd = 0.1), 100, 3)
fit <- mvr(X, Y, ncomp = 3, method = "PLS")
dim(fit$coefficients)

Description

The by-row normalisation is the same as SingleR:::.trim_byLabel_and_normalize_scores.

Usage

normPhiScores(X, method = c("col", "row"))

Arguments

Value

A matrix normalised by row or by column.

Examples

set.seed(1)
scores <- matrix(rnorm(20), 5, 4, dimnames = list(NULL, LETTERS[1:4]))
normPhiScores(scores)
normPhiScores(scores, method = "row")

Description

Soft phenotyping of query assay.

Usage

phenotype(
  phenoAssay,
  atlas_re,
  assayName = "rank",
  scaleMethod = c("byQuery", "byRef")
)

Arguments

Value

A list containing

Description

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.

Usage

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")
)

Arguments

Details

• 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.

Value

• 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".

References

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

Examples

# 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"))

Description

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().

Usage

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")
)

Arguments

Details

• 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.

Value

A list with the following components:

ncomp

Integer. Number of components used. NA when the scoreCells fallback is used.

impScores

Matrix. Feature importance scores (regression coefficients at the final component). NULL when the scoreCells fallback is used.

phenoDict

Data frame mapping phenotype labels to their categories, or NULL if response was provided directly.

selectedFeat

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.

YrefHat

Matrix. Raw (unnormalised) predicted scores for the reference cells. NULL when the scoreCells fallback is used.

YrefHatNorm

Matrix. Normalised predicted scores for the reference cells (via normPhiScores()). NULL when the scoreCells fallback is used.

PhiSpaceScore

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.

PhiSpaceNorm

Matrix or list of matrices. Normalised PhiSpace scores for the query dataset(s) (via normPhiScores()). Same structure as PhiSpaceScore.

center

Logical. Whether centering was applied. NA when the scoreCells fallback is used.

scale

Logical. Whether scaling was applied. NA when the scoreCells fallback is used.

atlas_re

List. Internal model object from SuperPC(), containing regression results and preprocessing parameters needed for prediction. NULL when the scoreCells fallback is used.

model

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.

fallback

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.

References

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

See Also

PhiSpace() for the main user-facing wrapper that handles multiple references, normPhiScores() for score normalisation, tunePhiSpace() for parameter tuning.

Examples

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)

Description

Combines log fold change and p-value into a single significance score (Xiao et al. 2014). By default returns the signed variant log2FC * -log10(p) for directional ranking; set signed = FALSE for the paper's original |log2FC| * -log10(p).

Usage

piScore(
  de_results,
  logfc_col = "avg_log2FC",
  pval_col = "p_val_adj",
  signed = TRUE,
  pval_floor = .Machine$double.xmin,
  add_column = TRUE,
  rank = FALSE
)

Arguments

Value

If add_column = TRUE, a data.frame with pi_score and optionally pi_rank appended. Otherwise, a numeric vector aligned to the input rows.

References

Xiao Y, Hsiao T-H, Suresh U, et al. (2014) A novel significance score for gene selection and ranking. Bioinformatics 30(6):801-807. doi:10.1093/bioinformatics/btr671

Examples

de <- data.frame(gene = c("g1", "g2", "g3"), avg_log2FC = c(2, -1, 0.5),
                 p_val_adj = c(1e-10, 0.01, 0.5))
piScore(de, rank = TRUE)

Description

Plot method for PhiSpaceClustering objects

Usage

## S3 method for class 'PhiSpaceClustering'
plot(x, type = c("pca", "elbow", "silhouette", "variance"), ...)

Arguments

Value

A ggplot object.

Description

Plot PhiSpace scores as a heatmap

Usage

plotPhiSpaceHeatMap(
  PhiSpaceScore,
  phenoDict = NULL,
  phenotypes = NULL,
  queryLabs = NULL,
  refLvls = NULL,
  queryLvls = NULL,
  cluster_columns = FALSE,
  cluster_rows = FALSE,
  show_row_names = FALSE,
  show_column_names = TRUE,
  row_title_rot = 0,
  ...
)

Arguments

Value

A heatmap of PhiSpace scores.

Examples

set.seed(1)
scores <- matrix(rnorm(60 * 5), 60, 5,
                 dimnames = list(NULL, c("T", "B", "NK", "ctrl", "stim")))
plotPhiSpaceHeatMap(
  scores,
  phenoDict = list(cellType = c("T", "B", "NK"), treatment = c("ctrl", "stim")),
  queryLabs = rep(c("cluster1", "cluster2"), each = 30)
)

Description

Score a query with a stored PhiSpace model

Usage

## S3 method for class 'PhiSpaceModel'
predict(object, newdata, assay = NULL, nfeat = NULL, ...)

Arguments

Details

If the query lacks some of the model genes, the model is first restricted to the genes that the query has:

• A model trained with nfeat and statistics over candidate genes (nfeatPool in trainPhiSpace()) selects nfeat genes per phenotype again, among its candidate genes that the query has, with a message. It refits the model on these candidate genes, selects the top genes of that fit and refits the model on them (see trainPhiSpace()).

• Another model with stored statistics (see trainPhiSpace()) is refitted exactly on these genes, with a message. The scores equal those of a model trained on the reference with selectedFeat set to these genes.

• A model without statistics (a "rank" model, a model trained with keepStats = FALSE, or PhiSpaceR_1ref()$model) keeps the coefficients of these genes and drops the others, with a warning. These scores are approximate: the error grows with the share of the coefficients that the missing genes hold, which the warning reports.

The query must be preprocessed as the reference was. Before scoring, the query values over the model genes are compared with the reference values recorded in the model (in up to 2,000 evenly spaced cells), and a warning is given if

• the non-zero values are integers in one and not in the other (for example raw counts against log-transformed values);

• one has negative values and the other has none (for example centred or scaled values);

• the 99th percentiles of the absolute non-zero values differ by more than a factor of 10;

• the model was trained on the "rank" assay and the query assay is not "rank", or the reverse. Only an assay named "rank" is ranked again within each cell.

The check cannot detect every difference: for example, values normalised to different library sizes can pass it. Changes that act on all genes alike, such as the base of the logarithm, do not change the normalised scores, because the query is centred and each score is scaled by normPhiScores().

Value

A cell by phenotype matrix of raw PhiSpace scores. Use normPhiScores() to normalise them.

Examples

set.seed(1)
ref <- logNormTransf(scuttle::mockSCE(ncells = 200, ngenes = 300))
query <- logNormTransf(scuttle::mockSCE(ncells = 100, ngenes = 300))
model <- trainPhiSpace(ref, phenotypes = "Cell_Cycle", refAssay = "logcounts",
                       ncomp = 3)
raw <- predict(model, query)
# Normalised scores, as PhiSpace() stores them.
head(normPhiScores(raw))

Description

Print method for PhiSpaceClustering objects

Usage

## S3 method for class 'PhiSpaceClustering'
print(x, ...)

Arguments

Value

x, invisibly. Called for the printed summary.

Description

Converting single cells to pseudo-bulks.

Usage

pseudoBulk(
  sce,
  phenotypes = NULL,
  response = NULL,
  clusterid = NULL,
  assayName = "counts",
  resampSizes = 100,
  proportion = NULL,
  calcMean = FALSE,
  nPool = 15,
  seed = 904800
)

Arguments

Value

An updated SingleCellExpeirment object with a pseudobulk assay.

Examples

sce <- scuttle::mockSCE(ncells = 200, ngenes = 50)
pb <- pseudoBulk(sce, phenotypes = "Cell_Cycle", resampSizes = 10, nPool = 5)
dim(pb$reference)

Description

Uses supervised learning methods (PLS-DA, PLS, or DWD) to rank features by their ability to discriminate between groups or predict a continuous response. Based on PhiSpace's correlatePhiSpace but generalized to work with any numeric data (not just PhiSpace scores).

Usage

rankFeatures(
  data,
  response,
  method = c("PLSDA", "PLS", "DWD"),
  source = c("reducedDim", "assay"),
  assay_name = "logcounts",
  reducedDim_name = "PhiSpace",
  ncomp = NULL,
  center = TRUE,
  scale = FALSE,
  dwd_params = list(),
  seed = NULL
)

Arguments

Details

Methods:

• PLSDA: Partial Least Squares Discriminant Analysis for multi-class classification. Features ranked by coefficient magnitude.

• PLS: Partial Least Squares regression for continuous response. Features ranked by coefficient magnitude.

• DWD: Distance Weighted Discrimination for binary classification. Features ranked by discriminant weights.

DWD Parameters (in dwd_params list):

• kernel: Kernel function (default: vanilladot())

• qval: q-value parameter (default: 1)

• lambda: Regularization parameter or sequence (default: auto-tuned)

• cv_folds: Cross-validation folds (default: 5)

• max_cells: Optional limit on the number of cells with a non-linear kernel (default: Inf, no limit). A non-linear kernel needs a cells by cells kernel matrix (8 bytes per entry: 0.8 GB for 10,000 cells, 80 GB for 100,000). If set, rankFeatures() stops before fitting when there are more cells than this.

Value

A list with class "FeatureRanking" containing:

Examples

set.seed(1)
X <- matrix(rnorm(100 * 20), 100, 20,
            dimnames = list(NULL, paste0("gene", 1:20)))
group <- rep(c("a", "b"), each = 50)
X[group == "b", 1:3] <- X[group == "b", 1:3] + 2
res <- rankFeatures(X, response = group, method = "PLSDA")
head(res$feature_ranking)

Description

Rank transform of a SingleCellExperiment object.

Usage

RankTransf(sce, assayname = "counts", targetAssay = "rank", sparse = TRUE)

Arguments

Value

An updated SingleCellExperiment object with a rank transformed assay.

Examples

sce <- scuttle::mockSCE(ncells = 20, ngenes = 10)
sce <- RankTransf(sce)
assay(sce, "rank")[1:3, 1:3]

Description

Turn a matrix to a data.frame withe newly defined colnames.

Usage

reNameCols(mat, key = "comp")

Arguments

Value

Data frame.

Examples

mat <- matrix(1:6, 2, 3)
reNameCols(mat)
reNameCols(mat, key = "PC")

Description

Ranks the values within each column (the genes within each cell), with ties given the minimum rank, and rescales the ranks to 0 to 1: (rank - 1)/(nrow(X) - 1). A sparse matrix with no negative values stays sparse, because its zeros have rank 1 and therefore stay 0.

Usage

RTassay(X)

Arguments

Value

Rank transformed gene by cell matrix (sparse).

Description

Creates and optionally saves spatial heatmaps for all cell types from PhiSpace continuous annotations. This function generates publication-ready visualizations showing the spatial distribution of cell type scores across tissue sections.

Usage

saveCellTypeMaps(
  sce,
  methodName = "PhiSpace",
  tissueName = "SpatialSample",
  coordNames = c("x", "y"),
  freeColScale = FALSE,
  quants = c(0.1, 1),
  psize = 0.5,
  savePlots = TRUE,
  returnPlots = FALSE,
  legendPosition = "none",
  censQuant = 1,
  ctypes = NULL,
  outputDir = "figs/spatialCellTypeHeatmaps",
  width = 10,
  height = 10,
  fignrow = 4,
  figncol = 4,
  fsize_title = 10,
  plot_margin = c(0, 0, 0, 0),
  fileFormat = "png",
  dpi = 300
)

Arguments

Details

This function creates spatial heatmaps showing the distribution of PhiSpace cell type scores across tissue sections. Each cell type is visualized as a separate heatmap where color intensity represents the confidence score for that cell type at each spatial location.

Key features:

• Automatic handling of both SingleCellExperiment and SpatialExperiment objects

• Flexible color scaling options (unified vs. independent scales)

• Multi-panel output for efficient visualization of many cell types

• Customizable censoring to reduce visualization noise

• Multiple output formats supported

Color scaling:

• freeColScale = FALSE: Uses the same color scale across all cell types, facilitating direct comparison of scores between different cell types

• freeColScale = TRUE: Each cell type uses its own optimal color scale, maximizing contrast within each individual plot

Output organization: When saving plots, multiple cell types are arranged in multi-panel figures (e.g., 4x4 grids). If there are more cell types than can fit in one figure, multiple files will be created with sequential numbering.

Value

If returnPlots = TRUE, returns a named list of ggplot objects, one for each cell type. If savePlots = TRUE, plots are saved to the specified directory. Invisible NULL otherwise.

See Also

VizSpatial for single cell type visualization PhiSpace for generating cell type annotations

Examples

set.seed(1)
ref <- logNormTransf(scuttle::mockSCE(ncells = 200, ngenes = 300))
query <- logNormTransf(scuttle::mockSCE(ncells = 100, ngenes = 300))
spe <- SpatialExperiment::SpatialExperiment(
  assays = list(logcounts = logcounts(query)),
  spatialCoords = cbind(x = runif(100), y = runif(100))
)
spe <- PhiSpace(ref, spe, phenotypes = "Cell_Cycle", refAssay = "logcounts",
                ncomp = 3)
# Return the maps instead of writing files.
maps <- saveCellTypeMaps(spe, savePlots = FALSE, returnPlots = TRUE)
names(maps)

Description

Converts a cell by cell type likelihood matrix to a probability matrix by setting negative values to zero and normalizing each row to sum to 1.

Usage

Score2Prob(PhiSc)

Arguments

Details

The function performs the following steps:

1. Sets all negative similarity values to zero

2. Calculates the sum of each row

3. Divides each element in a row by the row sum to create probabilities

4. Handles edge cases where rows sum to zero after removing negatives

For rows that contain all negative values (resulting in zero sums after transformation), the function will issue a warning and set those rows to all zeros. Alternative behavior could be implemented to assign uniform probabilities.

Value

A numeric matrix of the same dimensions as the input, where:

• All negative values are set to zero

• Each row sums to 1 (forms a probability distribution)

• Row and column names are preserved from the input

Examples

set.seed(1)
scores <- matrix(runif(20, -1, 1), 5, 4, dimnames = list(NULL, LETTERS[1:4]))
round(Score2Prob(scores), 2)

Description

scoreCells() provides a lightweight correlation- and signature-based fallback for regimes where a full PhiSpace model is not meaningful, such as single-class references or references with very few classes. It stores score matrices in reducedDim() slots with one column per reference class.

Usage

scoreCells(
  reference,
  query,
  class_col = NULL,
  assay_ref = "logcounts",
  assay_query = "logcounts",
  signature_genes = NULL,
  signature_method = c("mean", "findMarkers"),
  marker_test = c("t", "wilcox", "binom"),
  marker_pval_type = "any",
  marker_direction = c("up", "down", "any"),
  n_top_genes = 300,
  n_signature_genes = 100,
  remove_housekeeping = TRUE,
  housekeeping_patterns = c("^Rpl", "^Rps", "^mt-", "^MT-", "^Mrpl", "^Mrps"),
  housekeeping_genes = NULL,
  shared_genes_only = TRUE,
  scoring = c("both", "correlation", "signature"),
  cor_method = c("spearman", "pearson"),
  zscore_signature = TRUE,
  score_prefix = "scoreCells",
  BPPARAM = BiocParallel::SerialParam(),
  verbose = TRUE
)

Arguments

Details

A correlation score measures similarity between a query cell and a reference class centroid in the relative expression pattern across that class's effective signature genes. Different classes can therefore be scored using different genes. Correlations are NA for query cells with fewer than two complete observations or zero expression variance across the relevant signature.

A signature score is the average query expression across the same effective signature genes, optionally z-scored. When scoring = "both", the correlation and signature branches use exactly the same genes for each class.

Value

The modified query object with score matrices stored in reducedDim() slots and run details stored in metadata(query)$scoreCells.

Examples

set.seed(1)
ref <- logNormTransf(scuttle::mockSCE(ncells = 200, ngenes = 300))
query <- logNormTransf(scuttle::mockSCE(ncells = 100, ngenes = 300))
query <- scoreCells(ref, query, class_col = "Cell_Cycle",
                    signature_method = "mean", n_signature_genes = 20,
                    verbose = FALSE)
reducedDimNames(query)

Description

Computes pooled size factors with scran::computeSumFactors() and log-normalises the counts with logNormTransf().

Usage

scranTransf(sce, assayName = "counts", clusts = NULL)

Arguments

Value

SCE object with the assay logcounts and the size factors, centred to mean 1, in colData(sce)$sizeFactor.

Examples

sce <- scuttle::mockSCE(ncells = 200, ngenes = 200)
# Pool cells within known groups to compute the size factors.
sce <- scranTransf(sce, clusts = sce$Cell_Cycle)
assayNames(sce)

Description

Select nfeat top features from each column (label) of impScores

Usage

selectFeat(impScores, nfeat = 5, absVal = TRUE)

Arguments

Value

Vector of selected features.

Examples

set.seed(1)
imp <- matrix(rnorm(40), 10, 4,
              dimnames = list(paste0("gene", 1:10), LETTERS[1:4]))
selectFeat(imp, nfeat = 2)$selectedFeat

Description

Spatial smoothing of gene expression using KNN with kernel weighting

Usage

spatial_smooth_expression(
  expression_matrix,
  coordinates,
  k = 10,
  kernel = "linear",
  sigma = NULL,
  include_self = TRUE,
  verbose = TRUE
)

Arguments

Value

Smoothed gene x cell expression matrix

Description

Spatially-aware subsampling of SpatialExperiment objects

Usage

spatialSampler(
  spe,
  prop = 0.1,
  method = "grid",
  grid_size = NULL,
  seed = 123,
  min_cells_per_region = 1,
  balance_regions = FALSE,
  verbose = TRUE
)

Arguments

Value

Subsampled SpatialExperiment object

Examples

set.seed(1)
sce <- logNormTransf(scuttle::mockSCE(ncells = 300, ngenes = 50))
spe <- SpatialExperiment::SpatialExperiment(
  assays = list(logcounts = logcounts(sce)),
  spatialCoords = cbind(x = runif(300), y = runif(300))
)
sub <- spatialSampler(spe, prop = 0.2, method = "grid")
ncol(sub)

Description

Spatial smoother wrapper for SpatialExperiment and SingleCellExperiment objects

Usage

spatialSmoother(
  object,
  reducedDim2smooth = "PhiSpace",
  smoothReducedDim = TRUE,
  assay2smooth = "logcounts",
  smoothedReducedDim = NULL,
  smoothedAssay = NULL,
  x_coord = NULL,
  y_coord = NULL,
  k = 10,
  kernel = "linear",
  sigma = NULL,
  include_self = TRUE,
  verbose = TRUE
)

Arguments

Value

Modified object with new smoothed assay or reduced dimension

Examples

set.seed(1)
ref <- logNormTransf(scuttle::mockSCE(ncells = 200, ngenes = 300))
query <- logNormTransf(scuttle::mockSCE(ncells = 100, ngenes = 300))
spe <- SpatialExperiment::SpatialExperiment(
  assays = list(logcounts = logcounts(query)),
  spatialCoords = cbind(x = runif(100), y = runif(100))
)
spe <- PhiSpace(ref, spe, phenotypes = "Cell_Cycle", refAssay = "logcounts",
                ncomp = 3)
spe <- spatialSmoother(spe, k = 5, verbose = FALSE)
reducedDimNames(spe)

Description

Create partitions of data for cross-validation.

Usage

split2(x, n)

Arguments

Value

A partition of index vector x to n folds.

Description

Subsample from a sce object

Usage

subsample(sce, key = NULL, proportion = 0.1, minCellNum = 50, seed = 5202056)

Arguments

Value

A downsized SCE object

Examples

sce <- scuttle::mockSCE(ncells = 200, ngenes = 10)
small <- subsample(sce, proportion = 0.2)
ncol(small)
# Stratified by a colData column, keeping at least 20 cells per class.
strat <- subsample(sce, key = "Cell_Cycle", proportion = 0.1, minCellNum = 20)
table(strat$Cell_Cycle)

Description

Summary method for PhiSpaceClustering objects

Usage

## S3 method for class 'PhiSpaceClustering'
summary(object, ...)

Arguments

Value

object, invisibly. Called for the printed summary.

Description

Compute regression model using selected features.

Usage

SuperPC(
  reference,
  YY,
  ncomp,
  selectedFeat = NULL,
  assayName = "logcounts",
  regMethod = c("PCA", "PLS"),
  center = TRUE,
  scale = FALSE,
  sparse = TRUE,
  DRinfo = FALSE
)

Arguments

Value

A list containing regression input and output.

Description

Fits the PhiSpace regression model on an annotated reference and returns it as a PhiSpaceModel object. The model can be saved (for example with saveRDS()) and used later to score queries with predict() or PhiSpace(), without the reference cells.

Usage

trainPhiSpace(
  reference,
  phenotypes = NULL,
  response = NULL,
  refAssay,
  regMethod = c("PLS", "PCA"),
  ncomp = NULL,
  nfeat = NULL,
  selectedFeat = NULL,
  center = TRUE,
  scale = FALSE,
  DRinfo = FALSE,
  cellTypeThreshold = NULL,
  genes = NULL,
  keepStats = TRUE,
  nfeatPool = 2000,
  referenceName = NULL,
  species = NULL,
  geneIdType = NULL,
  preprocessing = NULL
)

Arguments

Details

PhiSpaceR_1ref() and PhiSpace() fit the same model on the genes that the reference shares with the query. trainPhiSpace() uses all reference genes, or the genes given in genes.

A query may lack some of the model genes, for example a targeted spatial panel. With keepStats = TRUE (the default), the model stores the cross-products $X'X$ and $X'Y$ of the centred (and scaled) reference over the model genes. predict() then refits the model on the genes that the query has, without the reference cells. The refitted model equals a model trained on the reference with selectedFeat set to those genes.

With nfeat, the genes are selected by a fit on all reference genes, whereas PhiSpace() selects them among the genes that the reference shares with the query. A model trained with nfeat therefore stores the statistics of a larger set of candidate genes: the top nfeatPool genes per phenotype. If the query lacks some model genes, predict() refits the model on the candidate genes that the query has, selects nfeat genes per phenotype from that fit and refits the model on them. The result approximates the PhiSpace() fit on the reference cells; with all genes as candidates (nfeatPool = Inf), the two are equal. When the query genes are known before training, for example a targeted panel, set genes to them: the model then selects its genes among the query genes, as PhiSpace() does.

The statistics are not kept for the "rank" assay. Ranks are computed within each cell over the model genes, so removing genes changes the reference values and an exact refit needs the reference cells. A "rank" model therefore scores a query that lacks genes approximately, with a warning (see predict.PhiSpaceModel()).

$X'X$ has one row and one column per model gene: it takes $8 G^2$ bytes for $G$ genes, for example 72 MB for 3,000 genes and 3.2 GB for 20,000 genes. Use nfeat (with a smaller nfeatPool), selectedFeat or genes to train on fewer genes, or keepStats = FALSE. A larger nfeatPool gives a selection closer to that of PhiSpace(), and a larger model.

Value

A PhiSpaceModel object: a list with

atlas_re

The fitted model, as returned in PhiSpaceR_1ref()$atlas_re.

selectedFeat

Genes used by the model, in model order.

impScores

Feature importance scores (see PhiSpaceR_1ref()).

phenoDict

Phenotype labels and their categories, or NULL if response was given.

responseNames

Names of the score columns.

refAssay

The training assay.

nCells

Number of reference cells used for training.

classSizes

Number of reference cells in each phenotype label, in the order of phenoDict, or NULL if response was given. Labels with few cells give less reliable scores.

stats

NULL, or a list with XtX (genes x genes) and XtY (genes x phenotypes): the cross-products of the centred (and scaled) reference over the model genes (or over the candidate genes, see nfeatPool), with the uncoded response, and the column means Xmeans and standard deviations Xscals used.

nfeat, nfeatPool

The nfeat used for gene selection, or NULL; the nfeatPool of the stored candidate genes, or NULL if the statistics cover only the selected genes.

referenceName, species, geneIdType, preprocessing

As supplied, or NULL.

valueProfile

A summary of the reference values over the model genes, used to check queries: whether all non-zero values are integers, the share of negative values and the 99th percentile of the absolute non-zero values, in up to 2,000 evenly spaced cells.

format_version, phispace_version, created

Model format version, the PhiSpace version that trained the model, and the date.

See Also

predict.PhiSpaceModel(), PhiSpace(), PhiSpaceR_1ref().

Examples

set.seed(1)
ref <- logNormTransf(scuttle::mockSCE(ncells = 200, ngenes = 300))
query <- logNormTransf(scuttle::mockSCE(ncells = 100, ngenes = 300))
model <- trainPhiSpace(ref, phenotypes = "Cell_Cycle", refAssay = "logcounts",
                       ncomp = 3, referenceName = "mock reference")
model
scores <- predict(model, query)
head(scores)
# A model can replace the reference in PhiSpace().
query <- PhiSpace(model, query)

Description

Translate cell type labels from finer to coarser according to a dictionary.

Usage

translateLabel(text, dictionary, dFrom = "label.fine", dTo = "label.main")

Arguments

Value

A vector containing translated labels.

Examples

dictionary <- data.frame(
  label.fine = c("CD4 T", "CD8 T", "Naive B"),
  label.main = c("T cell", "T cell", "B cell")
)
translateLabel(c("CD8 T", "Naive B", "CD4 T"), dictionary)

Description

Computes the K-fold cross-validation loss of a PhiSpace model over a grid of numbers of components (ncomp) and then over a grid of numbers of features per phenotype (nfeat), and returns the chosen values with the selected features. In an interactive session the function plots each loss curve and asks for a value unless ncomp or nfeat is given. In a non-interactive session it chooses the ncomp with the lowest loss, and nfeat must be given when tune_nfeat = TRUE.

Usage

tunePhiSpace(
  reference,
  assayName = "logcounts",
  phenotypes = NULL,
  YY = NULL,
  ncomp = NULL,
  impScores = NULL,
  center = TRUE,
  scale = FALSE,
  tune_ncomp = TRUE,
  tune_nfeat = TRUE,
  ncompLimits = c(1, 100),
  ncompGridSize = 20,
  ncompGrid = NULL,
  selectedFeat = NULL,
  nfeatLimits = c(10, 15000),
  nfeatGridSize = 30,
  nfeatV = NULL,
  Kfolds = 5,
  regMethod = "PLS",
  labelCode = "-1,1",
  Ncores = 1,
  seed = 5202056,
  cellTypeThreshold = NULL,
  nfeat = NULL
)

Arguments

Value

A list with ncomp, nfeat, impScores (feature importance scores), selectedFeat (selected features), and tuneNcompErrs and tuneNfeatErrs (data frames of the cross-validation loss for each grid value, or NULL when that parameter was not tuned).

Examples

set.seed(1)
ref <- logNormTransf(scuttle::mockSCE(ncells = 200, ngenes = 300))
# Outside an interactive session, nfeat must be given.
tuned <- tunePhiSpace(ref, assayName = "logcounts", phenotypes = "Cell_Cycle",
                      ncompGrid = 1:4, nfeatV = c(20, 50), Kfolds = 3,
                      nfeat = 50)
tuned$ncomp
tuned$tuneNcompErrs

Description

The 2D spatial coordinates (x and y) should be stored as two columns in colData.

Usage

VizSpatial(
  obj,
  x_coord = "x",
  y_coord = "y",
  ptSize = 2,
  ptShape = 16,
  colBy = NULL,
  feature = NULL,
  assay2use = NULL,
  reducedDim = NULL,
  reducedDim2use = "PhiSpace",
  censor = FALSE,
  quant = 0.5,
  legend.position = "right",
  legend.symb.size = NULL,
  legend.title = NULL,
  fsize = 14,
  reOrder = FALSE,
  ...
)

Arguments

Value

A ggplot2 object.

Examples

set.seed(1)
ref <- logNormTransf(scuttle::mockSCE(ncells = 200, ngenes = 300))
query <- logNormTransf(scuttle::mockSCE(ncells = 100, ngenes = 300))
spe <- SpatialExperiment::SpatialExperiment(
  assays = list(logcounts = logcounts(query)),
  spatialCoords = cbind(x = runif(100), y = runif(100))
)
spe <- PhiSpace(ref, spe, phenotypes = "Cell_Cycle", refAssay = "logcounts",
                ncomp = 3)
VizSpatial(spe, reducedDim = "G1")
VizSpatial(spe, feature = "Gene_0001", assay2use = "logcounts")

Description

Minimal quality control (QC): remove features with all zero values.

Usage

zeroFeatQC(sce, assayName = "counts", verbose = TRUE)

Arguments

Value

An updated SingleCellExperiment object after minimal QC.

Examples

sce <- scuttle::mockSCE(ncells = 20, ngenes = 10)
counts(sce)[1:2, ] <- 0
sce <- zeroFeatQC(sce)
dim(sce)