CellTypist is an automated cell type annotation tool for scRNA-seq datasets on the basis of logistic regression classifiers optimised by the stochastic gradient descent algorithm. CellTypist allows for cell prediction using either built-in (with a current focus on immune sub-populations) or custom models, in order to assist in the accurate classification of different cell types and subtypes.

CellTypist website

Information of CellTypist can be also found in our CellTypist portal.

Interactive tutorials

Using CellTypist for cell type classification
Using CellTypist for multi-label classification
Best practice in large-scale cross-dataset label transfer using CellTypist

Install CellTypist

Using pip

pip install celltypist

Using conda

conda install -c bioconda -c conda-forge celltypist

Usage (classification)

1. Use in the Python environment

1.1. Import the module

python import celltypist from celltypist import models

1.2. Download available models

The models serve as the basis for cell type predictions. Information of available models can be also found here. python #Show all available models that can be downloaded and used. models.models_description() #Download a specific model, for example, `Immune_All_Low.pkl`. models.download_models(model = 'Immune_All_Low.pkl') #Download a list of models, for example, `Immune_All_Low.pkl` and `Immune_All_High.pkl`. models.download_models(model = ['Immune_All_Low.pkl', 'Immune_All_High.pkl']) #Update the models by re-downloading the latest versions if you think they may be outdated. models.download_models(model = ['Immune_All_Low.pkl', 'Immune_All_High.pkl'], force_update = True) #Show the local directory storing these models. models.models_path A simple way is to download all available models. Since each model is on average 1 megabyte (MB), we encourage the users to download all of them. python #Download all the available models. models.download_models() #Update all models by re-downloading the latest versions if you think they may be outdated. models.download_models(force_update = True) By default, a folder .celltypist/ will be created in the user's home directory to store model files. A different path/folder can be specified by exporting the environment variable CELLTYPIST_FOLDER in your configuration file (e.g. in ~/.bash_profile). bash #In the shell configuration file. export CELLTYPIST_FOLDER='/path/to/model/folder/'

1.3. Overview of the models

All models are serialised in a binary format by pickle. python #Get an overview of the models that are downloaded in `1.2.`. #By default (`on_the_fly = False`), all possible models (even those that are not downloaded) are shown. models.models_description(on_the_fly = True)

1.4. Inspect the model of interest

To take a look at a given model, load the model as an instance of the Model class as defined in CellTypist. python #Select the model from the above list. If the `model` argument is not provided, will default to `Immune_All_Low.pkl`. model = models.Model.load(model = 'Immune_All_Low.pkl') #The model summary information. model #Examine cell types contained in the model. model.cell_types #Examine genes/features contained in the model. model.features

1.5. Celltyping based on the input of count table

CellTypist accepts the input data as a count table (cell-by-gene or gene-by-cell) in the format of .txt, .csv, .tsv, .tab, .mtx or .mtx.gz. A raw count matrix (reads or UMIs) is required. Non-expressed genes (if you are sure of their expression absence in your data) are suggested to be included in the input table as well, as they point to the negative transcriptomic signatures when compared with the model used. python #Get a demo test data. This is a UMI count csv file with cells as rows and gene symbols as columns. input_file = celltypist.samples.get_sample_csv() Assign the cell type labels from the model to the input test cells using the celltypist.annotate function. python #Predict the identity of each input cell. predictions = celltypist.annotate(input_file, model = 'Immune_All_Low.pkl') #Alternatively, the model argument can be a previously loaded `Model` as in 1.4. predictions = celltypist.annotate(input_file, model = model) If your input file is in a gene-by-cell format (genes as rows and cells as columns), pass in the transpose_input = True argument. In addition, if the input is provided in the .mtx format, you will also need to specify the gene_file and cell_file arguments as the files containing names of genes and cells, respectively. python #In case your input file is a gene-by-cell table. predictions = celltypist.annotate(input_file, model = 'Immune_All_Low.pkl', transpose_input = True) #In case your input file is a gene-by-cell mtx file. predictions = celltypist.annotate(input_file, model = 'Immune_All_Low.pkl', transpose_input = True, gene_file = '/path/to/gene/file.txt', cell_file = '/path/to/cell/file.txt') Again, if the model argument is not specified, CellTypist will by default use the Immune_All_Low.pkl model.

The annotate function will return an instance of the AnnotationResult class as defined in CellTypist. python #Summary information for the prediction result. predictions #Examine the predicted cell type labels. predictions.predicted_labels #Examine the matrix representing the decision score of each cell belonging to a given cell type. predictions.decision_matrix #Examine the matrix representing the probability each cell belongs to a given cell type (transformed from decision matrix by the sigmoid function). predictions.probability_matrix By default, with the annotate function, each query cell is predicted into the cell type with the largest score/probability among all possible cell types (mode = 'best match'). This mode is straightforward and can be used to differentiate between highly homogeneous cell types.

However, in some scenarios where a query cell cannot be assigned to any cell type in the reference model (i.e., a novel cell type) or can be assigned to multiple cell types (i.e., multi-label classification), a mode of probability match can be turned on (mode = 'prob match') with a probability cutoff (default to 0.5, p_thres = 0.5) to decide the cell types (none, 1, or multiple) assigned for a given cell. python #Query cell will get the label of 'Unassigned' if it fails to pass the probability cutoff in each cell type. #Query cell will get multiple label outputs (concatenated by '|') if more than one cell type passes the probability cutoff. predictions = celltypist.annotate(input_file, model = 'Immune_All_Low.pkl', mode = 'prob match', p_thres = 0.5) The three tables in the AnnotationResult (.predicted_labels, .decision_matrix and .probability_matrix) can be written out to local files (tables) by the function to_table, specifying the target folder for storage and the prefix common to each table. python #Export the three results to csv tables. predictions.to_table(folder = '/path/to/a/folder', prefix = '') #Alternatively, export the three results to a single Excel table (.xlsx). predictions.to_table(folder = '/path/to/a/folder', prefix = '', xlsx = True) The resulting AnnotationResult can be also transformed to an AnnData which stores the expression matrix in the log1p normalised format (to 10,000 counts per cell) by the function to_adata. The predicted cell type labels can be inserted to this AnnData as well by specifying insert_labels = True (which is the default behavior of to_adata).

Confidence scores of query cells can be inserted by specifying insert_conf = True (which is also the default behavior of to_adata). The scores correspond to the probabilities of cell predictions based on either predictions.predicted_labels.predicted_labels or predictions.predicted_labels.majority_voting (see 1.7.), which can be specified by insert_conf_by (default to the former, predicted_labels). python #Get an `AnnData` with predicted labels and confidence scores embedded into the observation metadata columns. adata = predictions.to_adata(insert_labels = True, insert_conf = True) #Inspect these columns (`predicted_labels` and `conf_score`). adata.obs In addition, you can insert the decision matrix into the AnnData by passing in insert_decision = True, which represents the decision scores of each cell type distributed across the input cells. Alternatively, setting insert_prob = True will insert the probability matrix into the AnnData. The latter is the recommended way as probabilities are more interpretable (though sometimes not all query datasets converge to a meaningful range of probability values).

After the insertion, multiple columns will show up in the cell metadata of AnnData, with each column's name as a cell type name. Of note, all these columns (including the predicted_labels and conf_score) can be prefixed with a specific string by setting prefix in to_adata. python #Get an `AnnData` with predicted labels, confidence scores, and decision matrix. adata = predictions.to_adata(insert_labels = True, insert_conf = True, insert_decision = True) #Get an `AnnData` with predicted labels, confidence scores, and probability matrix (recommended). adata = predictions.to_adata(insert_labels = True, insert_conf = True, insert_prob = True) You can now manipulate this object with any functions or modules applicable to AnnData. Actually, CellTypist provides a quick function to_plots to visualise your AnnotationResult and store the figures without the need of explicitly transforming it into an AnnData. python #Visualise the predicted cell types overlaid onto the UMAP. predictions.to_plots(folder = '/path/to/a/folder', prefix = '') A different prefix for the output figures can be specified with the prefix tag, and UMAP coordinates will be generated for the input dataset using a canonical Scanpy pipeline. The labels in the figure may be crowded if too many cell types are predicted (can be alleviated by a majority voting process, see 1.7.).

If you also would like to inspect the decision score and probability distributions for each cell type involved in the model, pass in the plot_probability = True argument. This may take a bit longer time as one figure will be generated for each of the cell types from the model. python #Visualise the decision scores and probabilities of each cell type overlaid onto the UMAP as well. predictions.to_plots(folder = '/path/to/a/folder', prefix = '', plot_probability = True) Multiple figures will be generated, including the predicted cell type labels overlaid onto the UMAP space, plus the decision score and probability distributions of each cell type on the UMAP.

1.6. Celltyping based on AnnData

CellTypist also accepts the input data as an AnnData generated from for example Scanpy.

Since the exp