CellTypeAnnotation

Annotate all or selected T/B cell clusters.

Annotate the cell clusters. Currently, the following ways are supported:

  1. Pass the cell type annotation directly (at cluster-level or cell-level)
  2. Use ScType
  3. Use scCATCH
  4. Use hitype
  5. Use celltypist
  6. Use scSorter
  7. Use SCINA
  8. Use SingleR
  9. Use scHDeepInsight
  10. Use GPTCelltype
  11. Use cellassign
  12. Use scBERT
  13. Use CelliD

The annotated cell types will replace the original identity column in the metadata, so that the downstream processes will use the annotated cell types.

Note

When cell types are annotated, the original identity column (e.g. seurat_clusters) will be renamed to envs.backup_col (e.g. seurat_clusters_id), and the new identity column will be added.

If you are using cluster-based tool, a text file containing the mapping from the original identity to the new cell types will be generated and saved to a tsv file under <workdir>/<pipline_name>/CellTypeAnnotation/0/output/.

The <workdir> is typically ./.pipen and the <pipline_name> is Immunopipe by default.

Note

If you have other annotation processes, including SeuratClustering process or SeuratMap2Ref process enabled in the same run, you may want to specify a different name for the column to store the annotated cell types using envs.newcol, so that the results from different annotation processes won't overwrite each other.

Input

  • sobjfile: The single-cell object in RDS/qs/qs2/h5ad format.

Output

  • outfile: Default: {{in.sobjfile | stem}}.annotated.{{- ext0(in.sobjfile) if envs.outtype == 'input' else envs.outtype -}}.
    The rds/qs/qs2/h5ad file of seurat object with cell type annotated.
    A text file containing the mapping from the old identity to the new cell types will be generated and saved to cluster2celltype.tsv under the job output directory.
    Note that if envs.ident is specified, the output Seurat object will have the identity set to the specified column in metadata.

Environment Variables

  • tool (choice): Default: direct.
    The tool to use for cell type annotation.
  • assay: The assay to use for the analysis. If not specified, the default assay will be used.
    Will not be inherited by the cases under envs.cases.
    To use a different assay for a case, specify it in the case args.
    This will be also used to convert Seurat object to h5ad if the input is Seurat object and the output is h5ad.
  • sctype_tissue: The tissue to use for sctype.
    Available tissues should be the first column (tissueType) of sctype_db.
    If not specified, all rows in sctype_db will be used.
  • sctype_db: The database to use for sctype.
    Check examples at https://github.com/IanevskiAleksandr/sc-type/blob/master/ScTypeDB_full.xlsx
  • ident: The column name in metadata to use as the clusters.
    If not specified, the identity column will be used when input is rds/qs/qs2 (supposing we have a Seurat object).
    If input data is h5ad, this is required to run cluster-based annotation tools.
    For celltypist, this is a shortcut to set over_clustering in celltypist_args.
  • backup_col: Default: seurat_clusters_id.
    The backup column name to store the original identities.
    If not specified, the original identity column will not be stored.
    If envs.newcol is specified, this will be ignored.
  • hitype_tissue: The tissue to use for hitype.
    Available tissues should be the first column (tissueType) of hitype_db.
    If not specified, all rows in hitype_db will be used.
  • hitype_db: The database to use for hitype.
    Compatible with sctype_db.
    See also https://pwwang.github.io/hitype/articles/prepare-gene-sets.html You can also use built-in databases, including hitypedb_short, hitypedb_full, and hitypedb_pbmc3k.
  • scsorter_db: The database to use for scSorter. It will be loaded and passed to the anno argument of RunScSorter(). It could be either:
    • A TSV file with cell type annotations, with columns Type, Marker, and Weight.
    • A RDS/qs2 file of the annotation data frame with the same columns as above.
      You can also use # followed by the column names to specify the columns as Type, Marker and weight (optional), for example, file:///path/to/scsorter_db.tsv#celltype,marker,weight.
  • scsorter_args (ns): The arguments for scSorter::RunScSorter() if tool is scsorter.
  • scina_db (type=str): The path to the SCINA signature file.
    It can be an RDS file containing a named list of signature genes (the names are the cell types and the values are the marker gene symbols), or a CSV file with the markers for each cell type in a column.
  • scina_args (ns): The arguments for SCINA::SCINA() if tool is scina.
    • max_iter: Maximum number of EM iterations (default: 100).
    • convergence_n: Stop if assignment stays stable for N consecutive rounds (default: 10).
    • convergence_rate: Fraction of cells with stable assignment for convergence (default: 0.99).
    • sensitivity_cutoff: Cutoff (0-1) for removing signatures of absent cell types (default: 1).
    • rm_overlap (flag): Whether to remove genes shared between multiple signatures (default: TRUE).
    • allow_unknown (flag): Whether to allow unknown cells (default: TRUE).
    • <more>: Other arguments for SCINA::SCINA().
  • singler_db (type=str): The path to the SingleR reference file.
    It can be an RDS, qs, or qs2 file containing a reference object, supporting:
    • SummarizedExperiment (e.g., from the celldex package).
      References can be obtained via celldex::HumanPrimaryCellAtlasData(), celldex::BlueprintEncodeData(), celldex::MonacoImmuneData(), celldex::DatabaseImmuneCellExpressionData(), celldex::NovershternHematopoieticData(), celldex::ImmGenData(), celldex::MouseRNAseqData().
    • Seurat object. Labels are auto-detected from metadata.
      Save with saveRDS() or biopipen.utils::write_obj().
      Both the Bioconductor and CRAN versions of SingleR are supported and auto-detected at runtime.
  • singler_args (ns): The arguments for SingleR::SingleR() if tool is singler.
    Both the Bioconductor and CRAN versions are auto-detected.
    • label (type=str): The metadata/colData column name for reference labels. Auto-detected from label.main, label.fine, label.ont, label in order.
    • <more>: See the SingleR documentation for your version:
    • [Bioconductor](https: //rdrr.io/bioc/SingleR/man/SingleR.html) or CRAN.
  • schdeepinsight_ref (type=str): The path to the scHDeepInsight reference RDS file. The bundled reference.rds from the scHDeepInsight repo provides immune cell reference.
    See https://github.com/shangruJia/scHDeepInsight.
  • schdeepinsight_args (ns): The arguments for scHDeepInsight if tool is schdeepinsight.
    • batch_size (type=int): Batch size for CNN prediction
    • (default: 128).
    • python (type=str): Path to Python executable with SCHdeepinsight installed.
    • assay (type=str): Assay to use for h5ad conversion.
  • gptcelltype_args (ns): The arguments for GPTCelltype::gptcelltype() if tool is gptcelltype.
    • api_key (type=str): OpenAI API key (required).
    • model (type=str): GPT model (required, e.g.
      'gpt-4', 'gpt-4o').
    • base_url (type=str): Custom base URL for OpenAI-compatible providers. Sets OPENAI_BASE_URL environment variable.
    • tissuename (type=str): Tissue name for context.
    • assay (type=str): Assay to use for FindAllMarkers().
    • <more>: Additional args passed to
    • `Seurat:: FindAllMarkers()`.
  • cellassign_db (type=str): The path to the marker gene info file for cellassign. Supports:
    • RDS/qs2 file: a binary gene×celltype matrix or a named list (cell type → vector of marker genes)
    • CSV/TSV file: with columns gene and cell_type
  • cellassign_args (ns): The arguments for cellassign::cellassign() if tool is cellassign.
    • python (type=str): Default: python.
      Path to Python with tensorflow installed.
    • assay (type=str): Assay to extract raw counts from.
    • min_delta (type=int): Min log-fold change for marker overexpression (default: 2).
    • B (type=int): Number of RBF dispersion bases
    • (default: 20).
    • shrinkage (flag): Hierarchical shrinkage on delta
    • n_batches (type=int): Data subsample batches
    • learning_rate (type=float): ADAM learning rate
    • max_iter_em (type=int): Max EM iterations
    • verbose (flag): Print progress (default: TRUE).
    • <more>: Additional args to
    • `cellassign:: cellassign()`.
  • scbert_ref (type=str): The path to the scBERT repo directory (containing performer_pytorch/).
  • scbert_model (type=str): The path to the fine-tuned model checkpoint (.pth file).
  • scbert_label_dict (type=str): The path to the label dictionary pickle file (maps class indices to cell type names).
  • scbert_args (ns): The arguments for scBERT inference if tool is scbert.
    • python (type=str): Path to Python with scBERT dependencies (torch, scanpy, etc.).
    • bin_num (type=int): Number of bins for expression embedding (default: 5).
    • gene_num (type=int): Number of genes expected by the model (default: 16906).
    • seed (type=int): Random seed (default: 2021).
    • pos_embed (flag): Use Gene2vec positional encoding (default: TRUE).
    • novel_type (flag): Enable novel cell type detection (default: FALSE).
    • unassign_thres (type=float): Confidence threshold for unassigned cells (default: 0.5).
    • <more>: Additional args to the wrapper script.
  • cellid_db (type=str): The path to the marker gene set file for cellid. Supports:
    • RDS/qs2 file: a named list (cell type → vector of marker genes)
    • CSV/TSV file: with columns gene and cell_type
  • cellid_args (ns): The arguments for CelliD if tool is cellid.
    • nmcs (type=int): Number of MCA components
    • (default: TRUE).
    • n_features (type=int): Top n features per cell for hypergeometric test (default: 200).
    • dims (type=auto): MCA dimensions to use
    • min_size (type=int): Min overlapping genes
    • log_trans (flag): -log10 transform p-values
    • p_adjust (flag): Benjamini-Hochberg correction

  • cell_types (type=auto): Default: [].
    The cell types to use for direct or cell-level annotation.
    For direct, the cell types will be assigned to the clusters in the order of the original identities.
    If given as a list (array), you can use "-" or "" as the placeholder for the clusters that you want to keep the original cell types. If the length of cell_types is shorter than the number of clusters, the remaining clusters will be kept as the original cell types.
    You can also use NA to remove the clusters from downstream analysis. This only works when envs.newcol is not specified.
    If given as a dict (map), the keys are the original cluster names and the values are the new cell types.

    Note

    If tool is direct and cell_types is not specified or an empty list, the original cell types will be kept and nothing will be changed.

    For cell, it must be a TSV file with cell-level annotations.
    You can specify the column names after the #. For example, file:///path/to/cell_types.tsv#cell_id,cell_type will use cell_id as the cell id column to match the cell ids in the Seurat object, and cell_type as the cell type column to assign the cell types.
    Multiple cell type columns can be specified, and the first one will be used as the new identity column.
    You can also use 1-based column index to specify the columns, for example, file:///path/to/cell_types.tsv#1,3 will use the first column as the cell id column and the third column as the cell type column.
    If cells in the Seurat object are not found in the cell type file, NAs will be assigned to those cells.
    If not columns are specified, the first two columns will be used as the cell id and cell type columns.
    Prefix file:// is optional.

  • more_cell_types (type=json): The additional cell type annotations to add to the metadata.
    The keys are the new column names and the values are the cell types lists.
    The cell type lists work the same as cell_types above.
    This is useful when you want to keep multiple annotations of cell types.

  • sccatch_args (ns): The arguments for scCATCH::findmarkergene() if tool is sccatch.

    • species: The specie of cells.
    • cancer: Default: Normal.
      If the sample is from cancer tissue, then the cancer type may be defined.
    • tissue: Tissue origin of cells must be defined.
    • marker: The marker genes for cell type identification.
    • if_use_custom_marker (flag): Default: False.
      Whether to use custom marker genes. If True, no species, cancer, and tissue are needed.
    • <more>: Other arguments for scCATCH::findmarkergene().
      You can pass an RDS file to sccatch_args.marker to work as custom marker. If so, if_use_custom_marker will be set to TRUE automatically.
  • celltypist_args (ns): The arguments for celltypist::celltypist() if tool is celltypist.
    • model: The path to model file.
    • python: Default: python.
      The python path where celltypist is installed.
    • majority_voting: Default: True.
      When true, it refines cell identities within local subclusters after an over-clustering approach at the cost of increased runtime.
    • over_clustering (type=auto): The column name in metadata to use as clusters for majority voting.
      Set to False to disable over-clustering.
      When in.sobjfile is rds/qs/qs2 (supposing we have a Seurat object), the default ident is used by default.
      Otherwise, it is False by default.
    • assay: When converting a Seurat object to AnnData, the assay to use.
      If input is h5seurat, this defaults to RNA.
      If input is Seurat object in RDS, this defaults to the default assay.
  • merge (flag): Default: False.
    Whether to merge the clusters with the same cell types.
    Otherwise, a suffix will be added to the cell types (ie. .1, .2, etc).
  • newcol: The new column name to store the cell types.
    If not specified, the identity column will be overwritten.
    If specified, the original identity column will be kept and Idents will be kept as the original identity.
    For tool cell, this can be used to save the cell types to a new column in metadata in additional to the column name specified in the cell type annotation file (and set as the identity).
    For tool scsorter, this can be used to save the cell types to a new column in metadata in addition to scSorter_celltype (and set as the identity).
  • add_prefix (flag): Whether to add a prefix to the new column names in metadata.
    Only used when in non-default cases. The prefix will be the case name followed by _.
  • cases (type=json): Default: {}.
    Run multiple cases of cell type annotation on the same Seurat object.
    The keys are the prefix of column names added to the metadata (unless add_prefix is False), and the values will inherit the above options.
    The default case is DEFAULT, meaning no prefix will be added to the column names.
    The annotation from the last case will be set as the identity of the output Seurat object.
    If any case requires h5ad conversion (e.g., celltypist), the object is pre-converted once and shared across those tools.
  • ncores (type=int): Default: 1.
    Number of cores to use for parallel execution of multiple cases.
    When > 1, cases are run in parallel via mclapply. This is not inherited by individual cases.
  • outtype (choice): Default: input.
    The output file type. Currently only works for celltypist.
    An RDS file will be generated for other tools.
    • input: Use the same file type as the input.
    • rds: Use RDS file.
    • qs: Use qs2 file.
    • qs2: Use qs2 file.
    • h5ad: Use AnnData file.

Examples

[CellTypeAnnotation.envs]
tool = "direct"
cell_types = ["CellType1", "CellType2", "-", "CellType4"]

The cell types will be assigned as:

0 -> CellType1
1 -> CellType2
2 -> 2
3 -> CellType4

Metadata

When envs.tool is direct and envs.cell_types is empty, the metadata of the Seurat object will be kept as is.

When envs.newcol is specified, the original identity column (e.g. seurat_clusters) will be kept is, and the annotated cell types will be saved in the new column.
Otherwise, the original identity column will be replaced by the annotated cell types and the original identity column will be saved at envs.backup_col (e.g. seurat_clusters_id).

CellTypeAnnotation-metadata