Train a PhiSpace model from a reference

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.

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

reference: A SingleCellExperiment (or SummarizedExperiment) object. The annotated reference dataset.
phenotypes: Character vector. Column name(s) in colData(reference) with the phenotypes to predict. If NULL, response must be provided.
response: Named matrix. Rows correspond to cells (columns) in reference; columns correspond to phenotypes. If not NULL, overrides phenotypes.
refAssay: Character. Name of the assay in reference used for training. Queries must be preprocessed in the same way, so there is no default.
regMethod: Character. "PLS" (default) or "PCA".
ncomp: Integer. Number of components. If NULL, the total number of phenotype levels.
nfeat: Integer. Number of top features per phenotype. If NULL, all genes are used. See PhiSpaceR_1ref().
selectedFeat: Character vector. Pre-selected features; overrides nfeat.
center, scale: Logical. Centring and scaling of the features.
DRinfo: Logical. Whether to keep the PLS or PCA scores and loadings.
cellTypeThreshold: Integer or NULL. Cell types with fewer cells than this are removed before training. Only used with phenotypes.
genes: Character vector or NULL. If given, training uses only these genes (those present in the reference).
keepStats: Logical. Whether to store the cross-product statistics that refit the model on a subset of its genes. Ignored for the "rank" assay. See Details.
nfeatPool: Number or NULL. With nfeat and keepStats = TRUE, the statistics are stored for the top nfeatPool genes per phenotype (at least nfeat), the candidates for selecting genes again when a query lacks model genes. Inf keeps all genes; NULL keeps only the selected genes, which are then refitted without a new selection. See Details.
referenceName, species, geneIdType: Character or NULL. Optional descriptions of the reference, stored in the model.
preprocessing: Character or NULL. Optional description of how refAssay was computed, for example "logTransf(use_log1p = TRUE)". Queries must be preprocessed in the same way; the description is printed with the model and in the warnings of the query check (see predict.PhiSpaceModel()).

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.

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.

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)

Arguments

Value

Details

See also

Examples