Score a query with a stored PhiSpace model

Source: R/PhiSpaceModel.R

Score a query with a stored PhiSpace model

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

Arguments

object

A PhiSpaceModel from trainPhiSpace().

newdata

The query: a SummarizedExperiment (for example a SingleCellExperiment) or a gene by cell matrix, with gene names as row names. It must share at least one gene with the model.

assay

Character. Assay of newdata to use. Defaults to the model's refAssay. With "rank", the genes are re-ranked within each cell over the model genes, as in PhiSpaceR_1ref().

nfeat

Integer or NULL. For a model trained with nfeat and statistics over candidate genes (nfeatPool): the number of genes per phenotype to select among the candidate genes that the query has. If NULL, the training nfeat is used, and genes are selected again only if the query lacks model genes.

...

Not used.

Value

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

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

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