Skip to contents

Prepare gene sets

prepare-gene-sets.Rmd

Using gene sets from ScType

hitype is designed to be compatible with ScType. So the gene sets provided by ScType can be used directly.

library(hitype)

gs <- gs_prepare(
  "https://raw.githubusercontent.com/IanevskiAleksandr/sc-type/master/ScTypeDB_short.xlsx"
)
gs$gene_sets[[1]]$`Acinar cells`
#> $markers
#>  [1] "CTRB1"    "KLK1"     "RBPJL"    "PTF1A"    "CELA3A"   "PRSS1"   
#>  [7] "SPINK1"   "ZG16"     "CEL"      "CELA2A"   "CPB1"     "CELA1"   
#> [13] "RNASE1"   "AMY2B"    "CPA2"     "CPA1"     "CELA3B"   "PNLIP"   
#> [19] "CTRB2"    "PLA2G1B"  "PRSS2"    "CLPS"     "REG1A"    "SYCN"    
#> [25] "PNLIPRP1" "CTRC"     "REG3A"    "PRSS3"    "REG1B"    "CFB"     
#> [31] "GDF15"    "MUC1"     "C15orf48" "AKR1C3"   "OLFM4"    "GSTA1"   
#> [37] "LGALS2"   "PDZK1IP1" "RARRES2"  "CXCL17"   "GSTA2"    "ANPEP"   
#> [43] "LYZ"      "ANGPTL4"  "ALDOB"   
#> 
#> $weights
#>  [1] 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1
#> [39] 1 1 1 1 1 1 1

# gs <- gs_prepare(
#  "https://raw.githubusercontent.com/IanevskiAleksandr/sc-type/master/ScTypeDB_long.xlsx"
# )

Universal marker format (long table)

Besides the wide ScType format below, gs_prepare() also accepts the universal marker format — a long table with one row per (cell type, marker) pair, as used across the author’s biopipen tools. It is also the default output of train_weights() and find_markers().

The table can be a data.frame or a file (.txt/.tsv, .csv, .xlsx, .rds, or .qs/.qs2 if the qs2 package is installed) with the following columns:

  • cell_type (required): Cell type name.
  • gene (required): Marker gene.
  • direction (optional): positive or negative (aliases pos/neg/+/-, case-insensitive). Negative markers penalize a cell type.
  • weight (optional): Numeric magnitude of the marker weight. Combined with direction: a positive marker gets weight abs(weight), a negative marker gets -abs(weight). If direction is missing, the signed weight is used as-is. If neither is given, the marker gets weight 1. Zero-weight markers are allowed.
  • tissue (optional): Tissue type. One can pass tissue_type to gs_prepare() to filter gene sets by tissue type.
  • species, cancer (optional): Reserved filter columns (accepted and ignored by gs_prepare()).
  • level (optional): Cell type level, as in the ScType format below.

Column names are matched case-insensitively and by alias (celltype/type → cell_type; marker/gene_symbol → gene; sign → direction; tissueType → tissue).

markers <- data.frame(
    cell_type = rep(c("CD4 T", "CD8 T"), each = 3),
    gene = c("CD3E", "CD4", "IL7R", "CD3E", "CD8A", "CD8B"),
    direction = c("positive", "positive", "negative", "positive", "positive", "positive"),
    weight = c(2.0, 1.5, 0.5, 2.0, 1.0, 1.0)
)
gs <- gs_prepare(markers)
gs$gene_sets[[1]]$`CD4 T`
#> $markers
#> [1] "CD3E" "CD4"  "IL7R"
#> 
#> $weights
#> [1]  2.0  1.5 -0.5

Preparing your own gene sets (wide ScType format)

You can also prepare your own gene sets in the wide ScType format. The gene sets should be a data.frame or a tab-delimited file with the following columns:

  • tissueType (optional): Tissue type. One can pass tissue_type to gs_prepare() to filter gene sets by tissue type.
  • cellName (required): Cell type name.
  • geneSymbolmore1 (required): Markers for the cell type. Multiple markers should be separated by ,. One can use a suffix + to indicate that the marker is a positive marker, and - to indicate that the marker is a negative marker. Multiple +’s are allowed to indicate that the marker is a strong positive marker. Multiple -’s are allowed to indicate that the marker is a strong negative marker. For example, CD3E+++ indicates that CD3E is a strong positive marker, and CD14--- indicates that CD14 is a strong negative marker.
  • geneSymbolmore2 (required): Negative markers for the cell type. This column can be empty strings. This is kept for compatibility with ScType. No suffixes are allowed in this column. A marker in this column is the same as a marker in the previous column with a suffix -.
  • level (optional): Cell type level. The level of the cellName. It must start from 1 and increase by 1. The final cell type consists of one cellName from each level.
  • nextLevels: Indication of possible cellNames at the next level. Levels should be separated by ;. The cellName at each level should be separated by ,.
    • The format is cellName1,cellName2;cellName3,cellName4;... for each cellName at the current level.
    • For example, for CD4 at level 1, nextLevels Naive;Activated indicates that CD4 should be followed by Naive at level 2 and Activated at level 3.
    • If the nextLevels is also specified for Naive at level 2, then the cellName at level 3 for CD4 will be the intersection of Activated and the cellNames at level 3 for Naive limited by nextLevels for Naive.
    • If a level in nextLevels is empty, then the cellNames at that level will be all cellNames at the next level limited by nextLevels of that level.
    • ! can be used to indicate that the cellNames at the next level should be excluded. For example, !Naive indicates that Naive should be excluded from the cellNames at the next level.
    • If ! is the only character in a level, then all cellNames at that level will be excluded.

Any data.frame of markers (e.g. the output of train_weights()) can be passed directly to gs_prepare():

markers <- data.frame(
    cellName = c("CD4 T", "CD8 T"),
    geneSymbolmore1 = c("CD3E,CD4,IL7R", "CD3E,CD8A,CD8B"),
    geneSymbolmore2 = c("", "")
)
gs <- gs_prepare(markers)