ModuleScoreCalculator

Calculate the module scores for each cell

The module scores are calculated by biopipen.utils::RunModuleScoring() with the scoring method specified by env.defaults.method (or per module by method in the module dict):

Scores from different methods are not comparable with each other — only the column names are consistent.

Input

  • srtobj: The Seurat object passed from the upstream process.

Output

  • rdsfile: Default: {{in.srtobj | stem}}.qs.
    The seurat object with module scores added to the metadata.

Environment Variables

  • defaults (ns): The default parameters for modules.
    • method (choice): Default: seurat.
      The scoring method to use, one of seurat, ucell, mean, aucell, ssgsea, jasmine, scse or scps. Can be overridden per module.
    • features: The features (genes) to calculate the scores.
      A comma-separated string of genes, e.g.
      "HAVCR2,ENTPD1,LAYN,LAG3", yields one score column named by the module key. A list of gene vectors, e.g.
      ["HAVCR2","ENTPD1"], yields one column per element, named {key}1, {key}2, ... if unnamed, or {key}_{name} if named. You can also specify cc.genes, cc.genes.updated.2019 or cc.genes.mouse (or use kind: "cc", with features defaulting to cc.genes) to calculate cell cycle scores. Three columns will be added to the metadata: {key}_S.Score, {key}_G2M.Score and {key}_Phase. This works for all methods. Use one of the reserved no-prefix keys ("_", "-", "*" or "#") as the module key to keep the plain S.Score, G2M.Score and Phase names. For diffusion map modules (kind: "dm"), this is the number of components to keep (default 2).
    • nbin (type=int): Default: 24.
      Number of bins of aggregate expression levels for all analyzed features. Only for the seurat method.
    • ctrl (type=int): Default: 100.
      Number of control features selected from the same bin per analyzed feature. Only for the seurat method.
    • k (flag): Default: False.
      Use feature clusters returned from DoKMeans.
      Only for the seurat method.
    • assay: The assay to use (for tools that accept it).
    • seed (type=int): Default: 8525.
      Set a random seed. Only for the seurat method.
    • search (flag): Default: False.
      Search for symbol synonyms for features that don't match features in object? Only for the seurat method.
    • <more>: Other parameters, passed to the underlying tool of the method. For seurat, they go to Seurat::AddModuleScore() or Seurat::CellCycleScoring() (see https://satijalab.org/seurat/reference/addmodulescore and https://satijalab.org/seurat/reference/cellcyclescoring).
      For ucell: maxRank, w_neg and slot (default "counts", not layer). For mean: layer (alias slot, default "counts") selects the layer, and assay the assay.
      For aucell: aucMaxRank, plotStats. For ssgsea: kcdf, verbose, min.sz, max.sz, tau, etc. For scse/scps: layer (default "data"). scps uses the bundled scPS implementation, which runs PCA on the scale.data of the object, so the signature genes must be scaled first (ScaleData(features = ...) or SCTransform); it also requires the GSEABase package. For diffmap modules (kind: "dm"): n_pcs (use PCA embeddings instead of assay data) and other arguments passed to destiny::DiffusionMap().
      The agg and keep parameters from old versions are removed and ignored.
  • ncores (type=int): Default: 1.
    The number of cores to use for reading and writing the seurat object.
  • modules (type=json): Default: {}.
    The modules to calculate the scores.
    Keys are the names of the expression programs and values are the dicts inherited from env.defaults.
    Here are some examples -

    {
        "CellCycleMouse": {"features": "cc.genes.mouse"},
        "CellCycle": {"kind": "cc", "features": "cc.genes.updated.2019"},
        "TcellState": {
            "features": {
                "Exhaustion": ["HAVCR2", "ENTPD1", "LAYN", "LAG3"],
                "Activation": ["IFNG"]
            },
            "method": "ucell",
            "maxRank": 500
        },
        "Proliferation": {"features": "STMN1,TUBB"},
        "DC": {"kind": "dm"}
    }
    

    For CellCycle, the columns CellCycle_S.Score, CellCycle_G2M.Score and CellCycle_Phase will be added to the metadata.

    For TcellState, the columns TcellState_Exhaustion and TcellState_Activation will be added to the metadata, one for each program in the named features list (the list values are gene vectors, not comma-separated strings).

    For DC, a diffusion map will be calculated with destiny (regardless of method), and the first 2 components will be added as the DC reduction as well as the DC_1 and DC_2 columns to the metadata. dm is a shortcut for diffmap/diffusion_map.
    You can later plot the diffusion map by using reduction = "DC" in env.dimplots in SeuratClusterStats.
    This requires SingleCellExperiment and destiny R packages.
    - post_mutaters (type=json): Default: {}.
    The mutaters to mutate the metadata after calculating the module scores.
    The mutaters will be applied in the order specified, so an entry may use a column an earlier entry created.
    This is useful when you want to create new scores based on the calculated module scores, or when a label has to be refined by a module score computed here (this process runs after CellTypeAnnotation).
    A <column>:ident key sets <column> as the object identity after the mutation.

Metadata

The metadata of the Seurat object will be updated with the module scores:

ModuleScoreCalculator-metadata

Description

Calculates the module scores of each cell, using Seurat (R), through Seurat::AddModuleScore() and Seurat::CellCycleScoring().

Base class

biopipen.ns.scrna.ModuleScoreCalculator

Deviations

The parameters are passed through to Seurat unchanged: this process overrides no inherited parameter and adds none.