CellTypist Documentation

By default, CellTypist performs independent cell predictions. To incorporate cell-cell transcriptomic relationships, enable the majority voting classifier by passing majority_voting = True to annotate(). This approach assumes similar cell subtypes are likely to form clusters.

Over-clustering

To define cell-cell relations, CellTypist uses a Leiden clustering pipeline with a heuristic over-clustering approach. You can provide your own over-clustering via the over_clustering argument, which accepts:

1. A plain file with one cell per line.
2. A string key for an existing metadata column in the AnnData.
3. A list-like object (e.g., a numpy 1D array).

Results and Visualization

When using majority voting, the AnnotationResult object's .predicted_labels attribute includes extra columns: over_clustering and majority_voting.

When using to_adata(), you can specify insert_conf_by = 'majority_voting' to include confidence scores for the majority-voting results instead of raw predictions.

When using celltypist.dotplot(), you can set use_as_prediction = 'majority_voting' to visualize the match between majority-voting results and manual annotations.

#Turn on the majority voting classifier as well.
predictions = celltypist.annotate(input_file, model = 'Immune_All_Low.pkl', majority_voting = True)

#Add your own over-clustering result.
predictions = celltypist.annotate(input_file, model = 'Immune_All_Low.pkl', majority_voting = True, over_clustering = '/path/to/over_clustering/file')

You can train a custom model using the celltypist.train function to transfer cell type labels to other scRNA-seq datasets.

Input Formats

• Gene Expression Data: Can be a path to a table (.csv, .mtx) or an AnnData (.h5ad). Tables should contain raw counts; AnnData should contain log1p normalised expression (to 10,000 counts per cell) in .X or .raw.X. You can also pass in-memory objects like csr_matrix or AnnData. A cell-by-gene format is required.
• Cell Type Labels: A path to a file with one label per line, or a list-like object (e.g., tuple, series). If using AnnData, you can provide a column name from .obs.
• Genes: Automatically extracted from tables/AnnData. Otherwise, provide a path to a file with one gene per line or a list-like object.

Training Methods

1. Traditional Logistic Regression: Default for datasets $\le$ 100k cells. Uses solver, C (inverse L2 regularization), and max_iter.
2. SGD Logistic Regression: Enabled via use_SGD = True. Recommended for large datasets to reduce training time. Uses alpha (L2 regularization) and max_iter.
3. Mini-batch SGD: For very large datasets (>500k cells), use use_SGD = True and mini_batch = True. This bins cells into batches (default batch_size = 1000) and trains over multiple epochs (default 10). Use balance_cell_type = True to prevent undersampling rare cell types.
4. Two-pass Training (Feature Selection): Use feature_selection = True to perform fast feature selection based on importance (absolute regression coefficients) before re-running the classifier on the top genes (default top_genes = 300).

# Basic training
new_model = celltypist.train(expression_input, labels = label_input, genes = gene_input)

# Training with subset of genes (e.g. highly variable genes)
# Use check_expression = False to skip normalization checks when using subsets
new_model = celltypist.train(some_adata[:, some_adata.var.highly_variable], labels = label_input, check_expression = False)

# Training with SGD
new_model = celltypist.train(expression_input, labels = label_input, genes = gene_input, use_SGD = True)

# Training with SGD mini-batch
new_model = celltypist.train(expression_input, labels = label_input, genes = gene_input, use_SGD = True, mini_batch = True)

# Two-pass training with feature selection
new_model = celltypist.train(expression_input, labels = label_input, genes = gene_input, feature_selection = True)

CellTypist uses serialized models for cell type predictions. You can discover, download, and inspect these models using the celltypist.models module.

Download and Update Models

• models.models_description(): Lists all available models.
• models.download_models(model='name.pkl'): Downloads a specific model or a list of models.
• models.download_models(force_update=True): Updates all models to their latest versions.
• models.download_models(): Downloads all available models.

Model Storage

By default, models are stored in ~/.celltypist/. You can change this location by setting the CELLTYPIST_FOLDER environment variable.

export CELLTYPIST_FOLDER='/path/to/model/folder/'

import celltypist
from celltypist import models

# Show all available models
models.models_description()

# Download a specific model
models.download_models(model='Immune_All_Low.pkl')

# Download all available models
models.download_models()

# Update all models
models.download_models(force_update=True)