# SeuratClusterStats

Statistics of the clustering.

Including the number/fraction of cells in each cluster, the gene expression values
and dimension reduction plots. It's also possible to perform stats on
TCR clones/clusters or other metadata for each T-cell cluster.<br />

## Input

- `srtobj`:
    The seurat object loaded by `SeuratClustering`

## Output

- `outdir`: *Default: `{{in.srtobj | stem}}.cluster_stats`*. <br />
    The output directory.<br />
    Different types of plots will be saved in different subdirectories.<br />
    For example, `clustree` plots will be saved in `clustrees` subdirectory.<br />
    For each case in `envs.clustrees`, both the png and pdf files will be saved.<br />

## Environment Variables

- `mutaters` *(`type=json`)*: *Default: `{}`*. <br />
    The mutaters to mutate the metadata to subset the cells.<br />
    The mutaters will be applied in the order specified.<br />
    You can also use the clone selectors to select the TCR clones/clusters.<br />
    See <https://pwwang.github.io/scplotter/reference/clone_selectors.html>.<br />
    You can also use key `<newcol>:ident` to set the `<newcol>` as the default
    ident for the stats.<br />
    See also <https://pwwang.github.io/biopipen.utils.R/reference/MutateSeuratMeta.html>
- `cache` *(`type=auto`)*: *Default: `/tmp`*. <br />
    Whether to cache the plots.<br />
    Currently only plots for features are supported, since creating the those
    plots can be time consuming.<br />
    If `True`, the plots will be cached in the job output directory, which will
    be not cleaned up when job is rerunning.<br />
- `clustrees_defaults` *(`ns`)*:
    The parameters for the clustree plots.<br />
    - `devpars` *(`ns`)*:
        The device parameters for the clustree plot.<br />
        - `res` *(`type=int`)*: *Default: `100`*. <br />
            The resolution of the plots.<br />
        - `height` *(`type=int`)*:
            The height of the plots.<br />
        - `width` *(`type=int`)*:
            The width of the plots.<br />
    - `more_formats` *(`type=list`)*: *Default: `[]`*. <br />
        The formats to save the plots other than `png`.<br />
    - `save_code` *(`flag`)*: *Default: `False`*. <br />
        Whether to save the code to reproduce the plot.<br />
    - `prefix` *(`type=auto`)*: *Default: `True`*. <br />
        string indicating columns containing clustering information.<br />
        The trailing dot is not necessary and will be added automatically.<br />
        When `TRUE`, clustrees will be plotted when there is `FindClusters` or
        `FindClusters.*` in the `obj@commands`.<br />
        The latter is generated by `SeuratSubClustering`.<br />
        This will be ignored when `envs.clustrees` is specified
        (the prefix of each case must be specified separately).<br />
    - `<more>`:
        Other arguments passed to `scplotter::ClustreePlot`.<br />
        See <https://pwwang.github.io/scplotter/reference/ClustreePlot.html>
- `clustrees` *(`type=json`)*: *Default: `{}`*. <br />
    The cases for clustree plots.<br />
    Keys are the names of the plots and values are the dicts inherited from `env.clustrees_defaults` except `prefix`.<br />
    There is no default case for `clustrees`.<br />
- `stats_defaults` *(`ns`)*:
    The default parameters for `stats`.<br />
    This is to do some basic statistics on the clusters/cells. For more comprehensive analysis,
    see <https://pwwang.github.io/scplotter/reference/CellStatPlot.html>.<br />
    The parameters from the cases can overwrite the default parameters.<br />
    - `subset`:
        An expression to subset the cells, will be passed to `tidyrseurat::filter()`.<br />
    - `devpars` *(`ns`)*:
        The device parameters for the clustree plot.<br />
        - `res` *(`type=int`)*: *Default: `100`*. <br />
            The resolution of the plots.<br />
        - `height` *(`type=int`)*:
            The height of the plots.<br />
        - `width` *(`type=int`)*:
            The width of the plots.<br />
    - `descr`:
        The description of the plot, showing in the report.<br />
    - `more_formats` *(`type=list`)*: *Default: `[]`*. <br />
        The formats to save the plots other than `png`.<br />
    - `save_code` *(`flag`)*: *Default: `False`*. <br />
        Whether to save the code to reproduce the plot.<br />
    - `save_data` *(`flag`)*: *Default: `False`*. <br />
        Whether to save the data used to generate the plot.<br />
    - `<more>`:
        Other arguments passed to `scplotter::CellStatPlot`.<br />
        See <https://pwwang.github.io/scplotter/reference/CellStatPlot.html>.<br />
- `stats` *(`type=json`)*: *Default: `{'Number of cells in each cluster (Bar Chart)': Diot({'plot_type': 'bar', 'x_text_angle': 90}), 'Number of cells in each cluster by Sample (Bar Chart)': Diot({'plot_type': 'bar', 'group_by': 'Sample', 'x_text_angle': 90})}`*. <br />
    The number/fraction of cells to plot.<br />
    Keys are the names of the plots and values are the dicts inherited from `env.stats_defaults`.<br />
- `ngenes_defaults` *(`ns`)*:
    The default parameters for `ngenes`.<br />
    The default parameters to plot the number of genes expressed in each cell.<br />
    - `more_formats` *(`type=list`)*: *Default: `[]`*. <br />
        The formats to save the plots other than `png`.<br />
    - `subset`:
        An expression to subset the cells, will be passed to `tidyrseurat::filter()`.<br />
    - `devpars` *(`ns`)*:
        The device parameters for the plots.<br />
        - `res` *(`type=int`)*: *Default: `100`*. <br />
            The resolution of the plots.<br />
        - `height` *(`type=int`)*: *Default: `800`*. <br />
            The height of the plots.<br />
        - `width` *(`type=int`)*: *Default: `1000`*. <br />
            The width of the plots.<br />
    - `add_box`: *Default: `True`*. <br />
- `ngenes` *(`type=json`)*: *Default: `{'Number of genes expressed in each cluster': Diot({})}`*. <br />
    The number of genes expressed in each cell.<br />
    Keys are the names of the plots and values are the dicts inherited from `env.ngenes_defaults`.<br />
- `features_defaults` *(`ns`)*:
    The default parameters for `features`.<br />
    - `features` *(`type=auto`)*:
        The features to plot.<br />
        It can be either a string with comma separated features, a list of features, a file path with `file://` prefix with features
        (one per line), or an integer to use the top N features from `VariantFeatures(srtobj)`.<br />
        It can also be a dict with the keys as the feature group names and the values as the features, which
        is used for heatmap to group the features.<br />
    - `order_by` *(`type=auto`)*:
        The order of the clusters to show on the plot.<br />
        An expression passed to `dplyr::arrange()` on the grouped meta data frame (by `ident`).<br />
        For example, you can order the clusters by the activation score of
        the cluster: `desc(mean(ActivationScore, na.rm = TRUE))`, suppose you have a column
        `ActivationScore` in the metadata.<br />
        You may also specify the literal order of the clusters by a list of strings (at least two).<br />
    - `subset`:
        An expression to subset the cells, will be passed to `tidyrseurat::filter()`.<br />
    - `devpars` *(`ns`)*:
        The device parameters for the plots.<br />
        - `res` *(`type=int`)*: *Default: `100`*. <br />
            The resolution of the plots.<br />
        - `height` *(`type=int`)*:
            The height of the plots.<br />
        - `width` *(`type=int`)*:
            The width of the plots.<br />
    - `descr`:
        The description of the plot, showing in the report.<br />
    - `more_formats` *(`type=list`)*: *Default: `[]`*. <br />
        The formats to save the plots other than `png`.<br />
    - `save_code` *(`flag`)*: *Default: `False`*. <br />
        Whether to save the code to reproduce the plot.<br />
    - `save_data` *(`flag`)*: *Default: `False`*. <br />
        Whether to save the data used to generate the plot.<br />
    - `<more>`:
        Other arguments passed to `scplotter::FeatureStatPlot`.<br />
        See <https://pwwang.github.io/scplotter/reference/FeatureStatPlot.html>
- `features` *(`type=json`)*: *Default: `{}`*. <br />
    The plots for features, include gene expressions, and columns from metadata.<br />
    Keys are the titles of the cases and values are the dicts inherited from `env.features_defaults`.<br />
- `dimplots_defaults` *(`ns`)*:
    The default parameters for `dimplots`.<br />
    You can also set `dims` to `[1, 2, 3]` to make a 3D dimensional reduction plot.<br />
    Note that the default `n.components` for `RunUMAP` is 2, so if you want to make a 3D UMAP plot,
    you need to set `n.components` to 3 in `RunUMAP` parameters in `SeuratSubClustering` or `SeuratClustering`.<br />
    - `group_by`:
        The identity to use.<br />
        If it is from subclustering (reduction `sub_umap_<ident>` exists), this reduction will be used if `reduction`
        is set to `dim` or `auto`.<br />
    - `split_by`:
        The column name in metadata to split the cells into different plots.<br />
    - `subset`:
        An expression to subset the cells, will be passed to `tidyrseurat::filter()`.<br />
    - `devpars` *(`ns`)*:
        The device parameters for the plots.<br />
        - `res` *(`type=int`)*: *Default: `100`*. <br />
            The resolution of the plots.<br />
        - `height` *(`type=int`)*:
            The height of the plots.<br />
        - `width` *(`type=int`)*:
            The width of the plots.<br />
    - `reduction` *(`choice`)*: *Default: `dim`*. <br />
        Which dimensionality reduction to use.<br />
        - `dim`:
            Use `Seurat::DimPlot`.<br />
            First searches for `umap`, then `tsne`, then `pca`.<br />
            If `ident` is from subclustering, `sub_umap_<ident>` will be used.<br />
        - `auto`:
            Same as `dim`
        - `umap`:
            Use `Seurat::UMAPPlot`.<br />
        - `tsne`:
            Use `Seurat::TSNEPlot`.<br />
        - `pca`:
            Use `Seurat::PCAPlot`.<br />
    - `<more>`:
        See <https://pwwang.github.io/scplotter/reference/CellDimPlot.html>
- `dimplots` *(`type=json`)*: *Default: `{'Dimensional reduction plot': Diot({'label': True}), 'VDJ Presence': Diot({'group_by': 'VDJ_Presence'})}`*. <br />
    The dimensional reduction plots.<br />
    Keys are the titles of the plots and values are the dicts inherited from `env.dimplots_defaults`. It can also have other parameters from
    [`scplotter::CellDimPlot`](https://pwwang.github.io/scplotter/reference/CellDimPlot.html).<br />

## Examples

### Clustree Plot

```toml
[SeuratClusterStats.envs.clustrees."Clustree Plot"]
prefix = "seurat_clusters"
devpars = {height = 500}
```

![Clustree Plot](https://raw.githubusercontent.com/pwwang/immunopipe/tests-output/seuratclusterstats/SeuratClusterStats/sampleinfo.scRep.cluster_stats/clustrees/seurat_clusters.clustree.png){: width="80%" }

### Number of cells in each cluster (Bar Chart)

```toml
[SeuratClusterStats.envs.stats."Number of cells in each cluster (Bar Chart)"]
plot_type = "bar"
x_text_angle = 90
```

![Number of cells in each cluster (Bar Chart)](https://raw.githubusercontent.com/pwwang/immunopipe/tests-output/seuratclusterstats/SeuratClusterStats/sampleinfo.scRep.cluster_stats/stats/Number-of-cells-in-each-cluster-Bar-Chart.png){: width="80%" }

### Number of cells in each cluster by Sample (Bar Chart)

```toml
[SeuratClusterStats.envs.stats."Number of cells in each cluster by Sample (Bar Chart)"]
plot_type = "bar"
group_by = "Sample"
x_text_angle = 90
```

![Number of cells in each cluster by Sample (Bar Chart)](https://raw.githubusercontent.com/pwwang/immunopipe/tests-output/seuratclusterstats/SeuratClusterStats/sampleinfo.scRep.cluster_stats/stats/Number-of-cells-in-each-cluster-by-Sample-Bar-Chart.png){: width="80%" }

### Number of cells in each cluster by Diagnosis

```toml
[SeuratClusterStats.envs.stats."Number of cells in each cluster by Diagnosis"]
plot_type = "bar"
group_by = "Diagnosis"
frac = "group"
x_text_angle = 90
swap = true
position = "stack"
```

![Number of cells in each cluster by Diagnosis](https://raw.githubusercontent.com/pwwang/immunopipe/tests-output/seuratclusterstats/SeuratClusterStats/sampleinfo.scRep.cluster_stats/stats/Number-of-cells-in-each-cluster-by-Diagnosis.png){: width="80%" }

### Number of cells in each cluster by Diagnosis (Circos Plot)

```toml
[SeuratClusterStats.envs.stats."Number of cells in each cluster by Diagnosis (Circos Plot)"]
plot_type = "circos"
group_by = "Diagnosis"
```

![Number of cells in each cluster by Diagnosis (Circos Plot)](https://raw.githubusercontent.com/pwwang/immunopipe/tests-output/seuratclusterstats/SeuratClusterStats/sampleinfo.scRep.cluster_stats/stats/Number-of-cells-in-each-cluster-by-Diagnosis-Circos-Plot.png){: width="80%" }

### Number of cells in each cluster by Diagnosis (Sankey Plot)

```toml
[SeuratClusterStats.envs.stats."Number of cells in each cluster by Diagnosis (Sankey Plot)"]
plot_type = "sankey"
group_by = ["seurat_clusters", "Diagnosis"]
links_alpha = 0.6
devpars = {width = 800}
```

![Number of cells in each cluster by Diagnosis (Sankey Plot)](https://raw.githubusercontent.com/pwwang/immunopipe/tests-output/seuratclusterstats/SeuratClusterStats/sampleinfo.scRep.cluster_stats/stats/Number-of-cells-in-each-cluster-by-Diagnosis-Sankey-Plot.png){: width="80%" }

### Number of cells in each cluster by Sample (Spider Plot)

```toml
[SeuratClusterStats.envs.stats."Number of cells in each cluster by Sample (Spider Plot)"]
plot_type = "spider"
group_by = "Diagnosis"
palette = "Set1"
```

![Number of cells in each cluster by Sample (Spider Plot)](https://raw.githubusercontent.com/pwwang/immunopipe/tests-output/seuratclusterstats/SeuratClusterStats/sampleinfo.scRep.cluster_stats/stats/Number-of-cells-in-each-cluster-by-Sample-Spider-Plot.png){: width="80%" }

### Number of genes detected in each cluster

```toml
[SeuratClusterStats.envs.ngenes."Number of genes detected in each cluster"]
plot_type = "violin"
add_box = true
add_point = true
```

![Number of genes detected in each cluster](https://raw.githubusercontent.com/pwwang/immunopipe/tests-output/seuratclusterstats/SeuratClusterStats/sampleinfo.scRep.cluster_stats/ngenes/Number-of-genes-detected-in-each-cluster.png){: width="80%" }

### Feature Expression in Clusters (Violin Plots)

```toml
[SeuratClusterStats.envs.features_defaults]
features = ["CD3D", "CD4", "CD8A", "MS4A1", "CD14", "LYZ", "FCGR3A", "NCAM1", "KLRD1"]

[SeuratClusterStats.envs.features."Feature Expression in Clusters (Violin Plots)"]
plot_type = "violin"
ident = "seurat_clusters"
```

![Feature Expression in Clusters (Violin Plots)](https://raw.githubusercontent.com/pwwang/immunopipe/tests-output/seuratclusterstats/SeuratClusterStats/sampleinfo.scRep.cluster_stats/features/Feature-Expression-in-Clusters-Violin-Plots.png){: width="80%" }

### Feature Expression in Clusters (Ridge Plots)

```toml
# Using the same features as above
[SeuratClusterStats.envs.features."Feature Expression in Clusters (Ridge Plots)"]
plot_type = "ridge"
ident = "seurat_clusters"
flip = true
```

![Feature Expression in Clusters (Ridge Plots)](https://raw.githubusercontent.com/pwwang/immunopipe/tests-output/seuratclusterstats/SeuratClusterStats/sampleinfo.scRep.cluster_stats/features/Feature-Expression-in-Clusters-Ridge-Plots.png){: width="80%" }

### Feature Expression in Clusters by Diagnosis

```toml
# Using the same features as above
[SeuratClusterStats.envs.features."Feature Expression in Clusters by Diagnosis"]
plot_type = "violin"
group_by = "Diagnosis"
ident = "seurat_clusters"
comparisons = true
sig_label = "p.signif"
```

![Feature Expression in Clusters by Diagnosis](https://raw.githubusercontent.com/pwwang/immunopipe/tests-output/seuratclusterstats/SeuratClusterStats/sampleinfo.scRep.cluster_stats/features/Feature-Expression-in-Clusters-by-Diagnosis.png){: width="80%" }

### Feature Expression in Clusters (stacked)

```toml
# Using the same features as above
[SeuratClusterStats.envs.features."Feature Expression in Clusters (stacked)"]
plot_type = "violin"
ident = "seurat_clusters"
add_bg = true
stack = true
add_box = true
```

![Feature Expression in Clusters (stacked)](https://raw.githubusercontent.com/pwwang/immunopipe/tests-output/seuratclusterstats/SeuratClusterStats/sampleinfo.scRep.cluster_stats/features/Feature-Expression-in-Clusters-stacked.png){: width="80%" }

### CD4 Expression on UMAP

```toml
[SeuratClusterStats.envs.features."CD4 Expression on UMAP"]
plot_type = "dim"
feature = "CD4"
highlight = "seurat_clusters == 'c1'"
```

![CD4 Expression on UMAP](https://raw.githubusercontent.com/pwwang/immunopipe/tests-output/seuratclusterstats/SeuratClusterStats/sampleinfo.scRep.cluster_stats/features/CD4-Expression-on-UMAP.png){: width="80%" }

### Feature Expression in Clusters by Diagnosis (Heatmap)

```toml
[SeuratClusterStats.envs.features."Feature Expression in Clusters by Diagnosis (Heatmap)"]
# Grouped features
features = {"T cell markers" = ["CD3D", "CD4", "CD8A"], "B cell markers" = ["MS4A1"], "Monocyte markers" = ["CD14", "LYZ", "FCGR3A"], "NK cell markers" = ["NCAM1", "KLRD1"]}
plot_type = "heatmap"
ident = "Diagnosis"
columns_split_by = "seurat_clusters"
name = "Expression"
devpars = {height = 560}
```

![Feature Expression in Clusters by Diagnosis (Heatmap)](https://raw.githubusercontent.com/pwwang/immunopipe/tests-output/seuratclusterstats/SeuratClusterStats/sampleinfo.scRep.cluster_stats/features/Feature-Expression-in-Clusters-by-Diagnosis-Heatmap.png){: width="80%" }

### Feature Expression in Clusters by Diagnosis (Heatmap with annotations)

```toml
# Using the default features
[SeuratClusterStats.envs.features."Feature Expression in Clusters by Diagnosis (Heatmap with annotations)"]
ident = "seurat_clusters"
cell_type = "dot"
plot_type = "heatmap"
name = "Expression Level"
dot_size = "nanmean"
dot_size_name = "Percent Expressed"
add_bg = true
rows_split_by = "Diagnosis"
cluster_rows = false
flip = true
palette = "YlOrRd"
column_annotation = ["percent.mt", "VDJ_Presence"]
column_annotation_type = {"percent.mt" = "violin", VDJ_Presence = "pie"}
column_annotation_params = {"percent.mt" = {show_legend = false}}
devpars = {width = 1400, height = 900}
```

![Feature Expression in Clusters by Diagnosis (Heatmap with annotations)](https://raw.githubusercontent.com/pwwang/immunopipe/tests-output/seuratclusterstats/SeuratClusterStats/sampleinfo.scRep.cluster_stats/features/Feature-Expression-in-Clusters-by-Diagnosis-Heatmap-with-annotations.png){: width="80%" }

### Dimensional reduction plot

```toml
[SeuratClusterStats.envs.features."Dimensional reduction plot"]
label = true
```

![Dimensional reduction plot](https://raw.githubusercontent.com/pwwang/immunopipe/tests-output/seuratclusterstats/SeuratClusterStats/sampleinfo.scRep.cluster_stats/dimplots/Dimensional-reduction-plot.dim.png){: width="80%" }

### Dimensional reduction plot (with marks)

```toml
[SeuratClusterStats.envs.dimplots."Dimensional reduction plot (with marks)"]
add_mark = true
mark_linetype = 2
```

![Dimensional reduction plot (with marks)](https://raw.githubusercontent.com/pwwang/immunopipe/tests-output/seuratclusterstats/SeuratClusterStats/sampleinfo.scRep.cluster_stats/dimplots/Dimensional-reduction-plot-with-marks.dim.png){: width="80%" }

### Dimensional reduction plot (with hex bins)

```toml
[SeuratClusterStats.envs.dimplots."Dimensional reduction plot (with hex bins)"]
hex = true
hex_bins = 50
```

![Dimensional reduction plot (with hex bins)](https://raw.githubusercontent.com/pwwang/immunopipe/tests-output/seuratclusterstats/SeuratClusterStats/sampleinfo.scRep.cluster_stats/dimplots/Dimensional-reduction-plot-with-hex-bins.dim.png){: width="80%" }

### Dimensional reduction plot (with Diagnosis stats)

```toml
[SeuratClusterStats.envs.dimplots."Dimensional reduction plot (with Diagnosis stats)"]
stat_by = "Diagnosis"
stat_plot_type = "ring"
stat_plot_size = 0.15
```

![Dimensional reduction plot (with Diagnosis stats)](https://raw.githubusercontent.com/pwwang/immunopipe/tests-output/seuratclusterstats/SeuratClusterStats/sampleinfo.scRep.cluster_stats/dimplots/Dimensional-reduction-plot-with-Diagnosis-stats.dim.png){: width="80%" }

### Dimensional reduction plot by Diagnosis

```toml
[SeuratClusterStats.envs.dimplots."Dimensional reduction plot by Diagnosis"]
facet_by = "Diagnosis"
highlight = true
theme = "theme_blank"
```

![Dimensional reduction plot by Diagnosis](https://raw.githubusercontent.com/pwwang/immunopipe/tests-output/seuratclusterstats/SeuratClusterStats/sampleinfo.scRep.cluster_stats/dimplots/Dimensional-reduction-plot-by-Diagnosis.dim.png){: width="80%" }

